Skip to main content
Docs

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

    Tools · Quantum Chemistry

    xTB / CREST

    Semi-empirical quantum chemistry with GFN2-xTB and GFN-FF, from single points and frequencies to CREST conformer, tautomer, and protomer ensembles.

    Updated October 12, 2026

    On this page

    Prices, workflows, and method papersOpen in the app

    xTB / CREST runs the extended tight-binding methods from the Grimme group. GFN2-xTB is a self-consistent tight-binding Hamiltonian parametrized for elements up to radon; GFN-FF is a generic force field derived from the same framework. Both are orders of magnitude cheaper than DFT, which makes them the usual first screen before PySCF Electronic Structure or docking. CREST (Conformer–Rotamer Ensemble Sampling Tool) drives xtb through metadynamics and genetic crossing to search conformational, tautomeric, and protonation-site space.

    How a run works

    1. Each input is read with RDKit. 3D records keep their coordinates; SMILES and 2D records get hydrogens, a 3D conformer from ETKDG, and an MMFF94 relaxation (UFF when MMFF lacks parameters).
    2. Each molecule runs on its own: xtb for single points, optimizations, and frequencies, or CREST for the ensemble modes.
    3. Energies, geometries, and vibrational data are collected into shared tables. A molecule that fails gets a row with its error, and the rest of the batch continues.

    Choosing a mode

    • Single-point energy: the energy, HOMO–LUMO gap, and dipole at the input geometry.
    • Geometry optimization: relaxes the structure at the chosen convergence level and keeps the input's bonds.
    • Frequencies and thermochemistry: optimizes at the tight or very tight level, then computes the Hessian. You get harmonic wavenumbers, IR intensities, reduced masses, the number of imaginary modes, and the zero-point energy, enthalpy, and free energy at the chosen temperature.
    • CREST conformer search: a conformer–rotamer ensemble within an energy window, deduplicated by RMSD.
    • CREST tautomers: prototropic tautomers from repeated protonation and deprotonation.
    • CREST protonation and deprotonation sites: protomers one proton up or down from the input. The reported charge of each structure shifts by one accordingly.

    Choosing a method

    • GFN2-xTB is the default and the right choice for most organic and drug-like molecules.
    • GFN-FF is much faster and suits large or very flexible molecules where a force field is good enough for sampling. Refine the low-energy structures with GFN2-xTB or DFT afterwards. CREST's tautomer and protomer searches need GFN2-xTB.

    Solvation uses the ALPB implicit solvent model; leave it at gas phase for vacuum energies. Leave the charge at 0 to use each molecule's formal charge from its structure, or set a value to apply it to every molecule. Unpaired electrons sets the spin state.

    Reading the results

    Energies are total electronic energies in Hartree; relative energies are in kcal/mol within each molecule.

    • structures.sdf: one record per structure, tagged with molecule_index, structure_index, charge, energy_hartree, rel_energy_kcal_mol, and, in CREST modes, population.
    • energies.csv: one row per structure with the same values, a SMILES string, and a status. For tautomers and protomers the SMILES is read from the new geometry, so it names the tautomer. bond_perception_failed means the structure is kept but its bonds could not be worked out from the coordinates.
    • population: Boltzmann weights of the structures' electronic energies at the chosen temperature, within each molecule. The weights cover the whole CREST ensemble, so they add up to less than 1 when the structure limit drops some structures.
    • vibrations.csv: one row per vibrational mode (frequencies mode only), with wavenumber_cm1, reduced_mass_amu, and ir_intensity_km_mol. Imaginary modes are negative wavenumbers.
    • logs/: the xtb or CREST output for each molecule.

    Limits and not covered

    Molecule and atom counts are lower for the CREST modes than for single points and optimizations; the field limits are listed below. Each CREST run stops after 30 minutes and each xtb run after an hour. If a large batch runs out of the job's time budget, the molecules that were not started get a skipped row in energies.csv, and the finished ones are still returned. Raman intensities, explicit solvation (QCG), CENSO-style DFT reranking of ensembles, and periodic systems are not part of this tool.

    Conformer Ensemble Generator is the cheaper classical alternative when force-field ensembles are enough. Run Molecule Standardizer first to clean parent structures. In a workflow, the structures output carries relative energy and population metrics, so a filter step can keep the lowest-energy conformers before PySCF Electronic Structure, AutoDock Vina, or 3D Shape Similarity.

    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.

    xTB / CREST xtb-crest

    Job type
    xtb-crest
    Hardware
    cpu (default)
    Typical runtime
    30 min on CPU

    Payload

    Payload fields
    FieldTypeDescription
    moderequiredstring

    One of: "energy", "opt", "hess", "crest", "tautomers", "protonate", "deprotonate"

    input_data[]required(string | object)[]

    Limits: min items 1, max items 200

    input_formatrequiredstring

    One of: "smiles", "molblock", "sdf"

    methodstring

    Default: "gfn2"One of: "gfn2", "gfnff"

    opt_levelstring

    xtb optimization level (opt and hess only). The default is 'normal' for opt and 'tight' for hess; hess rejects 'crude' and 'normal'.

    Default: "normal"One of: "crude", "normal", "tight", "vtight"

    chargeinteger

    Default: 0Limits: ≥ -10, ≤ 10

    uhfinteger

    Default: 0Limits: ≥ 0, ≤ 10

    solventstring | null

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

    temperature_knumber

    Default: 298.15Limits: ≥ 10, ≤ 2000

    energy_window_kcalnumber

    Default: 6Limits: ≥ 0.1, ≤ 30

    rmsd_threshold_angstromnumber

    Default: 0.125Limits: ≥ 0.01, ≤ 2

    max_structuresinteger

    Default: 50Limits: ≥ 1, ≤ 1000

    add_hydrogensboolean

    Default: true

    random_seedinteger

    Default: 42Limits: ≥ 0

    Example

    from cognichem_client import CogniChem

client = CogniChem.from_env()  # reads COGNICHEM_API_KEY
payload = {
    "mode": "hess",
    "input_data": ["CCO"],
    "input_format": "smiles",
    "method": "gfn2",
    "opt_level": "tight",
    "charge": 0,
    "uhf": 0,
    "solvent": None,
    "temperature_k": 298.15,
}

estimate = client.jobs.estimate(job_type="xtb-crest", payload=payload, resource="cpu")
print(f"Reserves ${estimate.cost:.2f}")

job = client.jobs.submit(
    job_name="my-xtb-crest-run",
    job_type="xtb-crest",
    payload=payload,
    resource="cpu",
)
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)SMILES, MOLBLOCK, SDF

    Workflow outputs

    • ArchiveZIP
    • TableCSV
    • MoleculesSDF
    • TableCSV