Skip to main content
Docs

Search guides and API endpoints, for example “Idempotency-Key” or “submit job”.

    Tools · Quantum Chemistry

    QC Conformer Ranking & Descriptors

    Rank conformer ensembles by DFT free energy in solution, with Boltzmann populations, ensemble free energy, conformational entropy, and frontier-orbital descriptors.

    Updated November 13, 2026

    On this page

    Prices, workflows, and method papersOpen in the app

    QC Conformer Ranking & Descriptors re-ranks a conformer ensemble with density functional theory and reports which conformers are actually populated. Force-field and GFN2-xTB conformer energies carry errors of a few kcal/mol, enough to reorder an ensemble; a composite or hybrid DFT tier brings the ordering to the 1 kcal/mol class. Conformers are ranked on free energy, optionally in implicit solvent, rather than on the gas-phase electronic energy, which over-stabilizes folded and intramolecularly hydrogen-bonded conformers. Single points run with GPU4PySCF on GPU resources or PySCF on CPU.

    How a run works

    The stages follow the CENSO scheme (Grimme et al., 2021): each one drops conformers that cannot matter, so the expensive steps run only on the survivors.

    1. Group. Each SDF record is one conformer, and records are grouped by compound, read from their 3D geometry. Both enantiomers of a chiral compound form one molecule: a conformer that is the mirror image of the molecule's first one is reflected, so a Conformer Ensemble Generator file from a SMILES without stereo is still one ensemble. Diastereomers and E/Z isomers are separate molecules. Each record keeps its own molecule_index and structure_index (as xTB / CREST writes them) as source_molecule_index and source_structure_index, which join the vibrations table.
    2. Deduplicate. Two conformers are duplicates when their symmetry-aware RMSD over heavy atoms and polar hydrogens is within the threshold and, when both carry upstream energies, their energy gap is too. Heavy atoms alone cannot tell OH and NH rotamers apart. Mirror-image conformers are kept apart, so a degenerate pair of gauche conformers counts twice in the populations, as it should.
    3. Input window. When every conformer of a molecule carries an upstream energy (free_energy_hartree, energy_hartree, energy_kcal_mol, or, within one upstream molecule, rel_energy_kcal_mol), conformers far above the lowest are dropped before any DFT.
    4. Screen (accurate preset). r²SCAN-3c single points, plus the thermal correction; conformers above the screening window are dropped.
    5. Refine. The final single points on the survivors. With a solvent, each survivor also gets a gas-phase single point so its solvation energy is reported.
    6. Populations. Boltzmann weights of the free energy at each temperature, with the ensemble free energy and the conformational (Gibbs–Shannon) entropy for each molecule. Conformers within the final window of the lowest one form the chainable output.

    What is ranked

    For each conformer, G = E + G_thermal:

    • E is the DFT energy at the refine level, in the implicit solvent when one is chosen. SMD includes cavity and dispersion terms, so solvated minus gas-phase energies estimate solvation free energies; C-PCM and IEF-PCM are electrostatics only.
    • G_thermal is the quasi-RRHO free-energy correction from a vibrations.csv you supply, the same treatment as QC Thermochemistry. Without that table the ranking uses E alone (plus solvation).

    Every row says which terms went into its ranking (E, E+solv, E+G_thermal, or E+solv+G_thermal), so a table ranked on electronic energy is never mistaken for one ranked on free energy.

    Choosing a preset

    • Accurate (default): r²SCAN-3c screening, then ωB97M-V/def2-TZVP refinement. ωB97M-V is one of the most accurate hybrid functionals for conformational energies.
    • Fast: r²SCAN-3c only. The composite method's dispersion and basis-set corrections keep its error well below a small-basis hybrid's, at a fraction of the cost.
    • Custom: one stage at a method and basis you choose from the PySCF Electronic Structure list.

    Getting frequencies for the thermal correction

    Run xTB / CREST in its frequencies mode on the conformers and pass its structures.sdf as the conformers and its vibrations.csv as the vibrations. The GFN2-xTB Hessians are cheap, and the free-energy correction they give is much less sensitive to the method than the electronic energy is. In a workflow, connect both outputs of that step straight to this tool.

    Reading the results

    • ranking.csv: one row per conformer (duplicates excluded), ranked ones first, with the energies, e_rel_kcal_mol, dg_solv_kcal_mol, g_thermal_kcal_mol, g_rel_kcal_mol, population at the first temperature, ranking_basis, HOMO/LUMO energies and gap, dipole moment, and a status (ok, failed, skipped, or the window that pruned it).
    • populations.csv: populations at every temperature.
    • ensemble.csv: one row per molecule and temperature, with the counts at each stage, the lowest conformer, the ensemble free energy, and the conformational entropy.
    • conformers.sdf: the conformers in the final window, tagged with their relative free energy and population, ready for the next step.
    • duplicates.csv: each dropped duplicate and the conformer it matched.

    Chaining

    The ranked conformers keep their molecule and structure indices, so they still join the vibrations table they came from. Feed them to Vibrational Spectrum Library with upstream populations and the input geometry to weight the ensemble IR spectrum by DFT populations instead of xTB ones, or to QC Thermochemistry for the full thermodynamic functions of the populated conformers.

    Validation

    CPU runs with r²SCAN-3c optimized geometries and the accurate preset, without the thermal correction:

    SystemPhaseΔE (kcal/mol)Reference
    n-Butane, gauche − antigas0.56about 0.6 (high-level ab initio)
    1,2-Dichloroethane, gauche − transgas1.03about 1.1 (experimental gas-phase ΔH)
    1,2-Dichloroethane, gauche − transSMD water−0.38gauche favored in polar solvents

    The reversal of 1,2-dichloroethane from gas to water is the solution-phase effect the tool exists to capture. Its per-conformer SMD solvation energies are more negative than the experimental hydration free energy, so treat dg_solv as a model value rather than a measurement.

    Limits and not covered

    Single points run on the input geometries; DFT geometry optimization of the lowest conformers is not part of this version, and neither are per-atom charges (use PySCF Electronic Structure). The methods are single-reference DFT, so multireference and biradical systems are out of scope, and one multiplicity applies to every conformer. Conformer ordering is at the 1 kcal/mol level of the chosen functional, not sub-kcal. Generating the ensemble is a separate step.

    Generate ensembles with xTB / CREST or Conformer Ensemble Generator, compute single structures with PySCF Electronic Structure, and use the populations in Vibrational Spectrum Library or QC Thermochemistry.

    Run it from the API

    Submit with Submit a job and the job_type below. Price it first with Estimate job reservation cost: submitting reserves that amount from your wallet, and the charge settles at the actual runtime.

    QC Conformer Ranking & Descriptors qc-ensemble-rank

    Job type
    qc-ensemble-rank
    Hardware
    cput4l4a10 (default)l40sa100-40gba100-80gbh100h200b200
    Typical runtime
    10 min on Nvidia A10

    Payload

    Payload fields
    FieldTypeDescription
    input_data[]required(string | object)[]

    Limits: min items 1, max items 200

    input_formatrequiredstring

    One of: "sdf", "molblock"

    presetstring

    accurate: r2SCAN-3c screen, then wB97M-V/def2-TZVP refine on survivors (CENSO pattern). fast: one r2SCAN-3c stage. custom: one stage at 'method' / 'basis'.

    Default: "accurate"One of: "accurate", "fast", "custom"

    methodstring

    custom preset only. r2scan-3c and wb97x-3c fix their own basis; 'basis' is rejected with them.

    Default: "r2scan-3c"One of: "hf", "b3lyp-d3", "wb97x-v", "wb97m-v", "r2scan-3c", "wb97x-3c"

    basisstring

    custom preset only, non-composite methods.

    Default: "def2-tzvp"One of: "def2-svp", "def2-tzvp", "def2-tzvpp", "def2-svpd", "def2-tzvpd", "6-31g*"

    chargeinteger

    Total charge for every conformer. Omit to use each conformer's formal charge.

    Limits: ≥ -20, ≤ 20

    multiplicityinteger

    Spin multiplicity for every conformer; an electron count that cannot have it is an error.

    Default: 1Limits: ≥ 1, ≤ 11

    solventstring

    Implicit solvent (same names as pyscf-electronic / xtb-crest ALPB). Omit for gas phase. Survivors also get a gas-phase single point so dg_solv is reported.

    One of: "water", "methanol", "acetonitrile", "acetone", "dmso", "dmf", "thf", "ch2cl2", "chcl3", "toluene", "benzene", "hexane", "ether", "ethylacetate", "dioxane", "octanol"

    solvent_modelstring

    Implicit solvent model; requires 'solvent'.

    Default: "smd"One of: "smd", "cpcm", "iefpcm"

    temperatures_k[]number[]

    Population temperatures; the first drives the windows and the SDF population tag.

    Default: [298.15]Limits: min items 1, max items 5

    input_window_kcal_molnumber

    Drop conformers above this window on the upstream energies, applied only when every conformer of a molecule carries one.

    Default: 6Limits: > 0, ≤ 100

    screen_window_kcal_molnumber

    accurate preset only: drop conformers above this window after the screening stage (screening E + G_thermal) before refinement.

    Default: 4Limits: > 0, ≤ 100

    final_window_kcal_molnumber

    Conformers within this window of the lowest final G form the chainable conformers output; all refined conformers stay in the ranking table.

    Default: 2.5Limits: > 0, ≤ 100

    dedup_rmsd_angstromnumber

    Symmetry-aware RMSD over heavy atoms and polar (N/O/S-bound) hydrogens below which two conformers are duplicates, so OH / NH rotamers stay distinct; 0 disables deduplication.

    Default: 0.125Limits: ≥ 0, ≤ 2

    dedup_energy_kcal_molnumber

    When both conformers carry upstream energies, they must also lie within this gap to count as duplicates.

    Default: 0.1Limits: ≥ 0, ≤ 5

    vibrationsfile_object

    Optional vibrations.csv (molecule_index, structure_index, wavenumber_cm1, ...) from an xtb-crest hess or pyscf-electronic freq run on the same conformers; adds the quasi-RRHO thermal correction G_thermal. Without it the ranking basis is E (+ solvation).

    qrrhostring

    Low-frequency treatment for G_thermal (as qc-thermo); requires 'vibrations'.

    Default: "grimme_head_gordon"One of: "grimme_head_gordon", "grimme_entropy", "rrho"

    cutoff_cm1number

    Quasi-RRHO switching frequency w0; not allowed with 'rrho'. Requires 'vibrations'.

    Default: 100Limits: > 0, ≤ 1000

    imaginary_modestring

    Imaginary frequencies: drop and count (ignore) or fail the conformer (reject). Requires 'vibrations'.

    Default: "ignore"One of: "ignore", "reject"

    File fields take {"name": "x.pdb", "content_b64": "…"} or a stored artifact, {"$artifact": {"id": "art-…", "port": "…"}}. Files are up to 25 MiB each.

    Example

    from cognichem_client import CogniChem

client = CogniChem.from_env()  # reads COGNICHEM_API_KEY
payload = {
    "input_data": [
        "ethanol\n     RDKit          3D\n\n  9  8  0  0  0  0  0  0  0 … (2,643 characters)",
    ],
    "input_format": "sdf",
    "preset": "custom",
    "method": "hf",
    "basis": "def2-svp",
    "temperatures_k": [298.15],
}

estimate = client.jobs.estimate(job_type="qc-ensemble-rank", payload=payload, resource="a10")
print(f"Reserves ${estimate.cost:.2f}")

job = client.jobs.submit(
    job_name="my-qc-ensemble-rank-run",
    job_type="qc-ensemble-rank",
    payload=payload,
    resource="a10",
)
status = client.jobs.wait(job.process_id)
if status.status == "completed":
    client.jobs.result(job.process_id, save_path=".")

    Sample data from the job catalog; long values are shortened here. Each job_name must be unique among your jobs.

    Workflow inputs

    • Molecules (list)SDF, MOLBLOCK
    • Table · optionalCSV

    Workflow outputs

    • ArchiveZIP
    • MoleculesSDF
    • TableCSV
    • TableCSV