Skip to main content
Docs

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

    Tools · Quantum Chemistry

    Pysisyphus

    Transition states, minimum-energy reaction paths, IRCs, and activation barriers on the GFN-xTB potential energy surface.

    Updated October 18, 2026

    On this page

    Prices, workflows, and method papersOpen in the app

    Pysisyphus locates transition states and minimum-energy reaction paths with pysisyphus, an optimizer for potential energy surfaces, driving the GFN-xTB tight-binding methods from the Grimme group as the calculator. It fills the gap between single-well calculations such as xTB / CREST and kinetics tools such as the Transition-State-Theory Rate Calculator: given a reactant and a product, it finds the saddle point between them, confirms it connects the two minima, and reports the barrier.

    How a run works

    1. The input structures are read as 3D coordinates. Every structure must list the same atoms in the same order, because the path is interpolated atom by atom.
    2. In the reaction-path mode, both endpoints are pre-optimized, and a chain of images between them is relaxed toward the minimum-energy path.
    3. The highest image becomes the starting guess for a transition-state optimization (RS-P-RFO with an exact Hessian).
    4. The intrinsic reaction coordinate (IRC) is followed downhill from the transition state in both directions, and both ends are optimized to minima.
    5. Optionally, xTB Hessians on the transition state and the two minima give enthalpies, entropies, and the imaginary frequency (rigid rotor, harmonic oscillator).

    Choosing a mode

    • Reaction path: two endpoints in, the full chain of states, transition state, and IRC out. This is the usual starting point.
    • TS optimization: starts from your own transition-state guess, for example from a previous run or a constrained scan, then follows the IRC unless you turn it off.
    • IRC only: follows the IRC from a structure that is already a converged transition state, to check which minima it connects.

    Choosing a path method

    • Growing string adds images from both ends until they meet. It needs no initial path and is the default.
    • Nudged elastic band interpolates all images at once. It is the method to use when you have a rough transition-state guess: the interpolation passes through it on the way from reactant to product.

    More images resolve the path better and cost proportionally more gradients. GFN2-xTB is the default Hamiltonian; GFN1-xTB is available for comparison. GFN-FF is not offered, because a force field with fixed bonds cannot describe bonds breaking and forming. Solvation uses the ALPB implicit solvent model.

    Reading the results

    • barriers.csv: one row per direction (<reaction id>_fwd and _rev) with the electronic barrier de_act_kj_mol, the reaction energy de_rxn_kj_mol, and, with thermochemistry, dh_act (kJ/mol), ds_act (J/mol/K), dg_act_at_t_kj_mol, and imag_freq_cm1. The columns use the Transition-State-Theory Rate Calculator's names and default units, so the table can feed it directly; in a workflow, only rows with dh_act and ds_act are passed on. An error column notes non-converged stages, failed Hessians, a transition state without exactly one imaginary mode, or a start side made of several fragments (its barrier is from the pre-reactive complex, not the separated molecules).
    • ts.sdf: the optimized transition state with its energy and imaginary frequency, reported as a negative wavenumber.
    • path.sdf: the chain-of-states images followed by the IRC frames from the reactant side through the transition state to the product side, each tagged with its energy relative to the reactant-side minimum. path_energies.csv holds the same energy profile.
    • Records carry connectivity only (single bonds from interatomic distances, no bond orders or formal charges), because a transition state or an intermediate frame has no single Lewis structure.

    In the reaction-path mode, the reactant side is the minimum closest to your reactant input. In the TS-optimization and IRC modes the direction of the IRC is only the sign of the imaginary mode, so the reactant side is the lower-energy minimum.

    Limits and not covered

    Barriers are GFN-xTB estimates: good for screening mechanisms and ranking pathways, not a substitute for DFT or coupled-cluster barriers. The field limits, including the image count, are listed below; structures are capped in size, and each optimization stage stops after a fixed number of cycles and reports whether it converged. PySCF and GPU calculators, excited-state surfaces, ab initio molecular dynamics, and multi-step mechanisms in one run are not part of this tool.

    Optimize endpoints with xTB / CREST first; in a workflow, a filter step that keeps the lowest-energy structure turns its conformer output into a single endpoint. Feed the barriers output to the Transition-State-Theory Rate Calculator for rate constants and Arrhenius parameters, and compare them with fits from the Kinetic Parameter Fitter or rule-based rates from the RMG Mechanism Generator.

    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.

    Pysisyphus pysisyphus

    Job type
    pysisyphus
    Hardware
    cpu (default)
    Typical runtime
    30 min on CPU

    Payload

    Payload fields
    FieldTypeDescription
    moderequiredstring

    'path': two endpoints → chain of states → TS optimization → IRC. 'tsopt': TS optimization from ts_guess. 'irc': IRC from a converged TS in ts_guess.

    One of: "path", "tsopt", "irc"

    input_formatrequiredstring

    Format of reactant, product and ts_guess text (3D coordinates required).

    One of: "sdf", "molblock"

    reactantstring | object

    Reactant 3D structure (mode 'path').

    productstring | object

    Product 3D structure in the same atom order as reactant (mode 'path').

    ts_guessstring | object | null

    TS geometry: required starting point for 'tsopt' / 'irc'; in 'path' an optional intermediate the NEB interpolation passes through (cos_method 'neb' only).

    cos_methodstring

    Chain-of-states method for mode 'path': growing string or nudged elastic band. Defaults to 'gsm', or to 'neb' when a ts_guess is given (the growing string cannot use one).

    Default: "gsm"One of: "gsm", "neb"

    n_imagesinteger

    Chain-of-states images between the endpoints (mode 'path').

    Default: 10Limits: ≥ 5, ≤ 20

    run_ircboolean

    Follow the IRC from the optimized TS (modes 'path' and 'tsopt'; always on for 'irc').

    Default: true

    methodstring

    GFN-xTB Hamiltonian. GFN-FF is not offered: it keeps a fixed bond topology.

    Default: "gfn2"One of: "gfn2", "gfn1"

    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

    thermoboolean

    xTB Hessians on the minima and TS for activation enthalpy / entropy (RRHO) and the imaginary frequency.

    Default: true

    temperature_knumber

    Thermochemistry temperature (only with thermo).

    Default: 298.15Limits: ≥ 10, ≤ 2000

    reaction_idstring

    Label written to the barrier table's reaction_id column.

    Default: "rxn1"Limits: pattern ^[A-Za-z0-9_.-]{1,64}$

    Example

    from cognichem_client import CogniChem

client = CogniChem.from_env()  # reads COGNICHEM_API_KEY
payload = {
    "mode": "path",
    "input_format": "sdf",
    "reactant": "formaldehyde\n     RDKit          3D\n\n  4  3  0  0  0  0  0  … (408 characters)",
    "product": "hydroxycarbene\n     RDKit          3D\n\n  4  3  0  0  0  0  0… (410 characters)",
    "cos_method": "gsm",
    "n_images": 10,
    "run_irc": True,
    "method": "gfn2",
    "charge": 0,
    "uhf": 0,
    "solvent": None,
    "thermo": True,
    "temperature_k": 298.15,
    "reaction_id": "h2co_hcoh",
}

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

job = client.jobs.submit(
    job_name="my-pysisyphus-run",
    job_type="pysisyphus",
    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

    • MoleculesSDF, MOLBLOCK
    • MoleculesSDF, MOLBLOCK
    • Molecules · optionalSDF, MOLBLOCK

    Workflow outputs

    • ArchiveZIP
    • TableCSV
    • MoleculesSDF
    • MoleculesSDF