tools_orca — ORCA calculators and conformer searches

ASE calculators for the ORCA quantum chemistry package.

ORCA performs the electronic-structure calculations used here, from DFT presets and cheap screening up to CCSD(T)/CBS. It is installed and licensed separately from reactiontools; everything here locates its executable through _resolve_orca(), which honours an explicit orca_path= argument, then $ASE_ORCA_COMMAND, $ORCA_COMMAND, $ORCA_PATH (the executable itself or its install directory), $ORCA_DIR and finally PATH. The executable check guards against a name collision: the unrelated GNOME Orca screen reader also uses the command orca. See build_tools/README.md for the quantum chemistry package’s install steps.

orca_calc_preset() builds an ASE calculator from a handful of presets, so a DFT, MP2, CCSD(T) or QM/XTB2 job can be set up without hand-writing ORCA’s input syntax. That calculator drops straight into the reaction-path functions in reactiontools.tools_reaction. The orca_preset_* dictionaries below name a few levels of theory worth reaching for by habit, and are splatted into it. orca_optimise_atoms() and orca_calculate_goat() run ORCA’s own drivers instead of ASE’s, for a geometry optimisation and a GOAT conformer search respectively.

Beyond the presets sit three tiers of increasing cost, cheapest first:

orca_cheap_calculator

xTB – ORCA’s own native implementation by default, or the external xtb binary – and Grimme “3c” composite methods: optimisers, Sella TS searches, NEB paths, conformer screens.

orca_calculator

OMol25-level DFT (wB97M-V/def2-TZVPD), set up for mechanism work: saddle searches, IRCs, NEB-TS, frequencies. sella_ts_search() drives a Sella saddle search over its gradients.

orca_gold_standard

Compound CCSD(T)/CBS focal-point energies, the usual recipe

E[CCSD(T)/CBS] = E_HF(CBS) + E_MP2corr(CBS) + [E_CCSDTcorr - E_MP2corr]_small

with an optional DFT geometry + frequency stage in front of it, on top of a geometry from either of the tiers above. reaction_energy() differences the results.

orca_calc_preset(orca_path: str | Path | None = None, directory: str | None = None, calc_type: str = 'DFT', xc: str = 'r2SCAN-3c', charge: int = 0, multiplicity: int = 1, basis_set: str = '', n_procs: int = 1, f_solv: bool | str | None = False, f_disp: bool | str | None = False, atom_list: str | None = None, calc_extra: str | None = None, blocks_extra: str | None = None, scf_option: str | None = None) → ORCA[source]

Build an ASE ORCA calculator from a small set of common presets.

Assembles the ORCA “simple input” line and block section for one of a few common calculation types, so callers do not have to hand-write ORCA input syntax for routine DFT, MP2, CCSD(T) or QM/XTB2 jobs.

Parameters:

  • orca_path (str or None, optional) – Path to the ORCA executable; see _resolve_orca() for the environment fallbacks. A missing or bogus binary raises here, at construction, rather than at run time.

  • directory (str or None, optional) – Working directory for ORCA’s input/output files. If None, a new temporary directory is created.

  • calc_type (str, optional) – One of 'DFT', 'MP2', 'CCSD' or 'QM/XTB2', each building the corresponding ORCA method keyword(s). Any other value is passed straight through as the ORCA method keyword.

  • xc (str, optional) – Exchange-correlation functional, used for 'DFT' and as the QM region’s method for 'QM/XTB2'.

  • charge (int, optional) – Total charge.

  • multiplicity (int, optional) – Spin multiplicity. Values above 1 switch 'DFT'/'QM/XTB2' to a UKS reference and 'MP2'/'CCSD' to a UKS reference as well.

  • basis_set (str, optional) – Basis set keyword, appended to the simple input line (and, for 'MP2'/'CCSD', also used as the auxiliary /C basis).

  • n_procs (int, optional) – Number of MPI processes requested via %pal.

  • f_solv (bool or str, optional) – Implicit solvation via CPCM/SMD. True uses water; a string names an explicit SMD solvent; False/None disables solvation.

  • f_disp (bool or str, optional) – Dispersion correction. True uses D4; a string is used as the dispersion keyword directly; False/None disables it.

  • atom_list (str or None, optional) – ORCA atom-selection string for the QM region (without braces), used only when calc_type is 'QM/XTB2'.

  • calc_extra (str or None, optional) – Extra text appended to the simple input line, e.g. 'TIGHTOPT'.

  • blocks_extra (str or None, optional) – Extra ORCA block text appended after %pal/%CPCM. Ignored when calc_type is 'QM/XTB2', which builds its own blocks instead.

  • scf_option (str or None, optional) – Extra SCF-related keyword appended to the simple input line.

Returns:

ase.calculators.orca.ORCA – A configured ORCA calculator requesting an energy and gradient (EnGrad).

orca_preset_dft_cheap = {'atom_list': None, 'basis_set': '6-31+G(d,p)', 'calc_extra': None, 'calc_type': 'DFT', 'f_disp': False, 'f_solv': False, 'scf_option': None, 'xc': 'BLYP'}

BLYP/6-31+G(d,p), gas phase, no dispersion. For a first look at a structure, or for the many single points of a scan.

Type:

Cheap DFT

orca_preset_dft_gold = {'atom_list': None, 'basis_set': 'DEF2-SVP', 'calc_extra': None, 'calc_type': 'DFT', 'f_disp': True, 'f_solv': True, 'scf_option': None, 'xc': 'B3LYP'}

B3LYP/def2-SVP with D4 dispersion in implicit water. f_disp/f_solv are True rather than named, which orca_calc_preset() reads as D4 and WATER; pass a string instead for a different solvent or dispersion correction.

Type:

Production DFT

orca_preset_xtb = {'atom_list': None, 'basis_set': '', 'calc_extra': None, 'calc_type': 'XTB2', 'f_disp': False, 'f_solv': False, 'scf_option': None, 'xc': ''}

a semi-empirical tight-binding method, orders of magnitude cheaper than DFT. Fast enough to drive a NEB with, which is what makes it the usual choice for a first band before refining at a higher level.

Type:

GFN2-xTB

orca_preset_mp2_gold = {'atom_list': None, 'basis_set': 'DEF2-TZVPP', 'calc_extra': None, 'calc_type': 'MP2', 'f_disp': False, 'f_solv': True, 'scf_option': None, 'xc': ''}

DLPNO-MP2/def2-TZVPP in implicit water, for a correlated energy on a geometry optimised more cheaply.

orca_preset_ccsd_gold = {'atom_list': None, 'basis_set': 'DEF2-TZVPP', 'calc_extra': None, 'calc_type': 'CCSD(T)', 'f_disp': False, 'f_solv': True, 'scf_option': None, 'xc': ''}

CCSD(T)/def2-TZVPP in implicit water, the reference energy to judge the others against. Note the calc_type is the literal ORCA keyword 'CCSD(T)', which orca_calc_preset() passes straight through, and so runs canonical CCSD(T). Pass calc_type='CCSD' instead for the linear-scaling DLPNO-CCSD(T) approximation, which is the only tractable option beyond a handful of atoms.

orca_optimise_atoms(atoms: Atoms, charge: int = 0, multiplicity: int = 1, orca_path: str | Path | None = None, xc: str = 'r2SCAN-3c', basis_set: str = '', tight_opt: bool = True, tight_scf: bool = False, f_solv: bool | str | None = False, f_disp: bool | str | None = False, n_procs: int = 1) → Atoms[source]

Optimise a geometry at the DFT level with ORCA.

Builds a DFT calculator via orca_calc_preset() with an OPT/TIGHTOPT keyword, runs it in a scratch directory, and reads back the final geometry from ORCA’s own optimisation trajectory.

Unlike optimise_geom(), which drives an ASE optimiser over a calculator, this hands the whole relaxation to ORCA. Use it when ORCA’s internal coordinates converge a molecule that BFGS in Cartesians struggles with.

Parameters:

  • atoms (ase.Atoms) – Starting geometry. Its calc is set to the ORCA calculator as a side effect.

  • charge (int, optional) – Total charge.

  • multiplicity (int, optional) – Spin multiplicity.

  • orca_path (str or None, optional) – Path to the ORCA executable; see _resolve_orca() for the environment fallbacks. A missing or bogus binary raises here, at construction, rather than at run time.

  • xc (str, optional) – Exchange-correlation functional.

  • basis_set (str, optional) – Basis set keyword.

  • tight_opt (bool, optional) – If True, use TIGHTOPT instead of OPT.

  • tight_scf (bool, optional) – If True, add TIGHTSCF to the optimisation keywords.

  • f_solv (bool or str, optional) – Implicit solvation; see orca_calc_preset().

  • f_disp (bool or str, optional) – Dispersion correction; see orca_calc_preset().

  • n_procs (int, optional) – Number of MPI processes requested via %pal.

Returns:

ase.Atoms – The optimised geometry, read from ORCA’s orca.xyz output.

orca_calculate_goat(atoms: Atoms, charge: int = 0, multiplicity: int = 1, orca_path: str | Path | None = None, n_procs: int = 1, method: str = 'XTB') → tuple[list[Atoms], DataFrame][source]

Run ORCA’s GOAT conformer search and collect the resulting ensemble.

Worth running before a band is built: a NEB between two arbitrary conformers explores the conformational change as well as the reaction, and the barrier that comes back is not the one you wanted.

Parameters:

  • atoms (ase.Atoms) – Starting geometry for the conformer search.

  • charge (int, optional) – Total charge.

  • multiplicity (int, optional) – Spin multiplicity.

  • orca_path (str or None, optional) – Path to the ORCA executable; see _resolve_orca() for the environment fallbacks. A missing or bogus binary raises here, at construction, rather than at run time.

  • n_procs (int, optional) – Number of MPI processes requested via %pal.

  • method (str, optional) – Level of theory GOAT explores at, appended to the GOAT keyword. The default 'XTB' is what makes the search affordable: GOAT runs many optimisations, so the method has to be a cheap one. Anything ORCA accepts as a method keyword works; '' leaves the input line as a bare GOAT, which falls back to ORCA’s own default.

Returns:

tuple – (atoms, df): every conformer in the final ensemble, in the order ORCA wrote them, and their energies and populations as parsed by _extract_conformer_info().

CHEAP_METHODS: dict[str, tuple[str, str]] = {'b97-3c': ('B97-3c', 'B97 GGA / def2-mTZVP composite'), 'gfn-ff': ('XTBFF', 'GFN-FF force field, seconds per structure'), 'gfn1-xtb': ('XTB1', 'GFN1-xTB semi-empirical tight binding'), 'gfn2-xtb': ('XTB2', 'GFN2-xTB, the usual screening workhorse'), 'hf-3c': ('HF-3c', 'HF/MINIX + gCP + D3, cheapest wavefunction level'), 'pbeh-3c': ('PBEh-3c', 'PBE hybrid / def2-mSVP composite'), 'r2scan-3c': ('r2SCAN-3c', 'r2SCAN meta-GGA / def2-mTZVPP, best 3c geometries')}

alias -> (ORCA keyword, description), cheapest first. The GFN keywords here are the external-interface ones; see NATIVE_XTB_METHODS for their in-ORCA equivalents, which is what these aliases resolve to by default.

NATIVE_XTB_METHODS: dict[str, tuple[str, str]] = {'gfn1-xtb': ('NATIVE-XTB1', 'NATIVE-SPXTB1'), 'gfn2-xtb': ('NATIVE-XTB2', 'NATIVE-SPXTB2')}

alias -> (restricted, spin-polarised) keyword for ORCA’s own xTB code. ORCA 6 implements the GFN Hamiltonians internally: no external binary, MPI parallel under %pal, and configured with the ordinary %scf block rather than a %xtb one, which it rejects outright. GFN-FF has no native counterpart and stays on the external interface.

orca_cheap_calculator(method: str = 'gfn2-xtb', directory: str | Path = 'orca_cheap', charge: int = 0, multiplicity: int = 1, orca_path: str | Path | None = None, n_procs: int = 1, maxcore: int = 3000, solvent: str | None = None, solvent_model: str = 'auto', forces: bool = True, scf_convergence: str = '', extra_keywords: str = '', extra_blocks: str = '', quiet: bool = True, native: bool | str = 'auto', spin_polarised: bool = False) → ORCA[source]

Build an ASE ORCA calculator at a cheap level of theory.

These are the levels you drive ASE with – optimisers, Sella TS searches, NEB paths, conformer screens – to make the geometries that orca_gold_standard() then puts a CCSD(T)/CBS energy on.

Parameters:

  • method (str, optional) – One of CHEAP_METHODS, cheapest first: gfn-ff, gfn1-xtb, gfn2-xtb, hf-3c, pbeh-3c, b97-3c, r2scan-3c. The two GFN-xTB levels run through ORCA’s native implementation by default; gfn-ff has none, so it needs an external xtb binary.

  • directory (str or pathlib.Path, optional) – Working directory. Give every NEB image, and every parallel worker, a separate one – they all write orca.inp/orca.out and will otherwise overwrite each other. Reusing one directory across the steps of a single optimisation is good: ORCA’s AutoStart picks up the previous orca.gbw and converges the next SCF much faster.

  • charge (int, optional) – Total charge of the system.

  • multiplicity (int, optional) – Spin multiplicity, 2S + 1.

  • orca_path (str or pathlib.Path or None, optional) – Path to the ORCA binary; see _resolve_orca() for the fallbacks.

  • n_procs (int, optional) – MPI ranks for %pal.

  • maxcore (int, optional) – Memory per rank in MB.

  • solvent (str or None, optional) – ORCA solvent name, e.g. "water". None gives gas phase.

  • solvent_model (str, optional) – "auto" picks ALPB for xTB and CPCM for the DFT/HF levels; override with an explicit "CPCM", "SMD" or "ALPB" if you need it. Native xTB does run CPCM and SMD, but only by falling back to ORCA’s general SCF machinery, which gives up much of the speed; ALPB is the one it solves natively.

  • forces (bool, optional) – Adds EnGrad to the keyword line. Leave this on for anything that moves atoms: ASE’s ORCA template ignores the requested properties, so without it ORCA never prints a gradient and get_forces() fails. Turn it off only for pure single-point energies.

  • scf_convergence (str, optional) – SCF convergence keyword, e.g. "TightSCF". Empty uses ORCA’s default.

  • extra_keywords (str, optional) – Appended verbatim to the ! line and the % blocks respectively, e.g. extra_keywords="SlowConv" for a sulky SCF.

  • extra_blocks (str, optional) – Appended verbatim to the ! line and the % blocks respectively, e.g. extra_keywords="SlowConv" for a sulky SCF.

  • quiet (bool, optional) – Suppress the four-line caveat ASE prints on every single gradient read. Set False to get stock ASE behaviour back.

  • native (bool or str, optional) – Which xTB implementation to use, for the GFN-xTB levels only. "auto" (the default) and True take ORCA’s native code, which needs no external binary, runs under %pal and is configured through the ordinary %scf block. False takes the external interface, which shells out to otool_xtb/xtb – ORCA 6 stopped bundling that, so it has to be installed separately and pointed at with $XTBEXE.

  • spin_polarised (bool, optional) – Use the spin-polarised native Hamiltonian, NATIVE-SPXTB*. Plain xTB stays restricted even at multiplicity > 1 and fills the frontier orbitals fractionally; this goes unrestricted and adds the spin-polarisation correction, which is what open-shell radicals want. Native only.

Returns:

ase.calculators.orca.ORCA – A plain ASE calculator, so it composes with anything that takes one.

Raises:

  • ValueError – If method is not in CHEAP_METHODS, if a native-only option is asked of a method with no native implementation, or if extra_blocks carries a %xtb block into a native run.

  • FileNotFoundError – If the external interface was chosen but no xtb driver could be found.

Examples

>>> from ase.build import molecule
>>> from ase.optimize import BFGS
>>> atoms = molecule("H2O")
>>> atoms.calc = orca_cheap_calculator("gfn2-xtb", directory="opt/mono")
>>> BFGS(atoms).run(fmax=0.02)
orca_calculator(charge: int = 0, multiplicity: int = 1, *, task: str = 'engrad', atoms: Atoms | None = None, basis: str = 'def2-TZVPD', solvent: str | None = None, solvation_model: str = 'cpcm', open_shell_singlet: bool = False, scf_strategy: str = 'default', scf_maxiter: int = 300, autostart: bool = True, moread: str | None = None, calc_hess: bool = True, hybrid_hess_atoms: Sequence[int] | None = None, recalc_hess: int | None = None, inhess_file: str | None = None, ts_mode: int | None = None, geom_maxiter: int | None = None, scan_coord: str | None = None, neb_product: str | None = None, neb_ts_guess: str | None = None, neb_images: int = 8, irc_hess_file: str | None = None, irc_maxiter: int = 70, temperature: float = 298.15, freq_increment: float = 0.005, nbo: bool = False, population: bool = False, n_procs: int = 1, maxcore: int = 3000, orca_path: str | None = None, directory: str = '.') → ORCA[source]

Build an ORCA calculator at the OMol25 level, set up for mechanism work.

The level of theory is wB97M-V/def2-TZVPD with RIJCOSX, a dense integration grid and tight SCF and integral thresholds – suitable for saddle searches, IRCs, NEB-TS and frequencies.

Parameters:

  • charge (int, optional) – Total charge of the system.

  • multiplicity (int, optional) – Spin multiplicity, 2S + 1.

  • task (str, optional) – One of TASK_KEYWORDS. Use "engrad" when driving from ASE (Sella, NEB, LBFGS) – it is the only task ASE can parse forces from. The other tasks hand control to ORCA’s own optimisers; ASE will run them but only recover the final energy.

  • atoms (ase.Atoms or None, optional) – Structure, required only when open_shell_singlet=True.

  • basis (str, optional) – Orbital basis set.

  • solvent (str or None, optional) – ORCA solvent name, e.g. "water", "acetonitrile", "dmso", "thf". None gives gas phase.

  • solvation_model (str, optional) – "cpcm" (fast, analytic gradients, smooth) or "smd" (better absolute solvation free energies, non-electrostatic terms can be less smooth along a reaction coordinate).

  • open_shell_singlet (bool, optional) – UKS + broken-symmetry guess. Leave False for ordinary heterolytic proton transfer, where the electron pair stays on the donor. Set True for HAT/PCET, where the saddle has genuine diradical character.

  • scf_strategy (str, optional) – "default" – ORCA’s DIIS -> SOSCF -> TRAH ladder. Recommended here. "omol" – DIIS NOSOSCF NormalConv, byte-comparable to OMol25. "slow" – adds SlowConv for stubborn cases.

  • scf_maxiter (int, optional) – Cap on SCF iterations.

  • autostart (bool, optional) – Let ORCA reuse <basename>.gbw from a previous run in the same directory as the SCF guess. Gives free orbital continuity along a scan or optimisation; disable if charge/multiplicity changes between runs, or when you want each point converged independently.

  • moread (str or None, optional) – Explicit .gbw file to take the starting orbitals from.

  • calc_hess (bool, optional) – Compute an exact Hessian before a saddle search. Applies to the optts tasks only.

  • hybrid_hess_atoms (sequence of int or None, optional) – Atom indices (0-based) to treat exactly in an otherwise model Hessian. For proton transfer, the donor/H/acceptor triad plus any directly bonded heavy atoms. Cuts the numerical Hessian cost sharply.

  • recalc_hess (int or None, optional) – Recompute the Hessian every this many geometry steps.

  • inhess_file (str or None, optional) – Read the starting Hessian from this file instead of computing one.

  • ts_mode (int or None, optional) – Index of the Hessian mode to follow uphill in a saddle search.

  • geom_maxiter (int or None, optional) – Cap on geometry steps.

  • scan_coord (str or None, optional) – Relaxed-scan specification for task="scan", e.g. "B 0 5 = 1.80, 1.00, 17".

  • neb_product (str or None, optional) – Product-side XYZ file. Required for task="neb-ts".

  • neb_ts_guess (str or None, optional) – Optional saddle-point guess XYZ, which speeds the band up considerably.

  • neb_images (int, optional) – Number of images in the band.

  • irc_hess_file (str or None, optional) – Hessian to start the IRC from; without it ORCA computes one.

  • irc_maxiter (int, optional) – Cap on IRC steps per direction.

  • temperature (float, optional) – Temperature in K for the thermochemistry.

  • freq_increment (float, optional) – Displacement in Angstrom for the numerical Hessian.

  • nbo (bool, optional) – Run NBO analysis with second-order perturbative donor-acceptor terms.

  • population (bool, optional) – Print Loewdin and Mulliken populations and bond orders.

  • n_procs (int, optional) – MPI ranks for %pal.

  • maxcore (int, optional) – Memory per rank in MB.

  • orca_path (str or None, optional) – Path to the ORCA binary; see _resolve_orca() for the fallbacks.

  • directory (str, optional) – Working directory for the run.

Returns:

ase.calculators.orca.ORCA – Calculator configured for task.

Raises:

  • ValueError – If task or scf_strategy is unknown, if open_shell_singlet is set without atoms, or if task="neb-ts" without neb_product.

  • FileNotFoundError – If no ORCA binary could be found; see _resolve_orca().

Locate a saddle point with Sella, using ORCA only for energy+gradient.

Sella accumulates curvature from the gradients it already needs, so this avoids the 6N-gradient numerical Hessian that ORCA’s OptTS would trigger. Confirm the result afterwards with task="freq".

Parameters:

  • atoms (ase.Atoms) – Starting guess for the saddle point. Modified in place.

  • charge (int, optional) – Total charge of the system.

  • multiplicity (int, optional) – Spin multiplicity, 2S + 1.

  • fmax (float, optional) – Force convergence threshold in eV/Angstrom.

  • steps (int, optional) – Maximum optimiser steps.

  • trajectory (str or None, optional) – Path to write the search trajectory to; None writes nothing.

  • internal (bool, optional) – Use Sella’s internal coordinates instead of Cartesian coordinates.

  • raise_on_unconverged (bool, optional) – Raise ConvergenceError instead of warning when the search hits steps without reaching fmax.

  • **calc_kwargs – Passed to orca_calculator(). task and atoms default to "engrad" and atoms.

Returns:

ase.Atoms – The same object, at the located saddle point, with info["converged"] recording whether the search reached fmax. As with optimise_ts(), converging says the search found a stationary point, not that it is a first-order saddle – run a frequency job to confirm that.

Raises:

reactiontools.tools_reaction.ConvergenceError – If the search did not converge and raise_on_unconverged is True.

class GoldStandard(atoms: Atoms, charge: int = 0, multiplicity: int = 1, e_hf_cbs: float = 0.0, e_corr_cbs: float = 0.0, e_total: float = 0.0, e_mp2_corr_cbs: float | None = None, delta_cc: float | None = None, zpe: float | None = None, gibbs_correction: float | None = None, enthalpy_correction: float | None = None, imaginary_frequencies: list[float] = <factory>, levels: dict[str, str]=<factory>, components: dict[str, dict[str, float]]=<factory>, directories: dict[str, ~pathlib.Path]=<factory>)[source]

Bases: object

Result of an orca_gold_standard() compound job.

Variables:

  • atoms (ase.Atoms) – Geometry the energies refer to, updated if the job optimised it.

  • charge (int) – Total charge of the system.

  • multiplicity (int) – Spin multiplicity, 2S + 1.

  • e_hf_cbs (float) – Hartree-Fock energy at the basis-set limit, in Hartree.

  • e_corr_cbs (float) – Total correlation energy at the basis-set limit, in Hartree.

  • e_total (float) – CCSD(T)/CBS electronic energy, the sum of the two above, in Hartree.

  • e_mp2_corr_cbs (float or None) – MP2 correlation energy at the limit. None on the extrapolate_cc route, which has no MP2 stage.

  • delta_cc (float or None) – The CCSD(T) - MP2 correction, in Hartree. None as above.

  • zpe (float or None) – Zero-point energy in Hartree, if frequencies were run.

  • enthalpy_correction (gibbs_correction,) – Thermal corrections G - E(el) and H - E(el), in Hartree.

  • imaginary_frequencies (list of float) – Imaginary modes in cm^-1: one is expected at a saddle, none at a minimum.

  • levels (dict of {str: str}) – Human-readable description of the level of theory per stage.

  • components (dict of {str: dict of {str: float}}) – Every energy parsed, keyed by stage name.

  • directories (dict of {str: pathlib.Path}) – Where each stage ran, for inspecting the raw output.

property energy: float

Electronic CCSD(T)/CBS energy in eV, i.e. the ASE convention.

property enthalpy: float | None

Enthalpy in Hartree, or None if no frequencies were run.

property gibbs: float | None

Gibbs energy in Hartree, or None if no frequencies were run.

summary() → str[source]

Format the energy breakdown as a human-readable report.

Returns:

str – Multi-line table of every component that was computed, in both Hartree and kcal/mol, with any imaginary modes listed at the end.

orca_gold_standard(atoms: Atoms, directory: str | Path = 'orca_gold', charge: int = 0, multiplicity: int = 1, orca_path: str | Path | None = None, n_procs: int = 1, maxcore: int = 3000, optimise: bool = True, frequencies: bool = True, transition_state: bool = False, opt_method: str = 'r2SCAN-3c', opt_basis: str | None = None, cc_method: str = 'DLPNO-CCSD(T)', cc_extra: str = 'TightPNO', mp2_method: str = 'RI-MP2', basis_family: str = 'cc', cardinals: tuple[int, int] = (3, 4), cc_cardinal: int | None = None, extrapolate_cc: bool = False, aux_basis: str | None = None, scf_convergence: str = 'TightSCF', frozen_core: bool = True, solvent: str | None = None, reuse: bool = True, verbose: bool = True) → GoldStandard[source]

Run a compound ORCA job for a CCSD(T)/CBS energy.

Stages, each in its own subdirectory of directory and each a separate ASE ORCA calculation:

  1. opt – geometry optimisation (+ frequencies) at opt_method.

  2. mp2_* – MP2 single points at the two cardinals, giving both the HF and the MP2 correlation energies used for the CBS limits.

  3. cc_* – CCSD(T) single point at cc_cardinal for the CCSD(T) - MP2 correction.

With extrapolate_cc=True the MP2 stages are skipped and the CCSD(T) correlation energy is extrapolated directly from both cardinals – the most accurate and by far the most expensive route.

Parameters:

  • atoms (ase.Atoms) – Starting geometry. Copied, so the caller’s object is untouched.

  • directory (str or pathlib.Path, optional) – Root directory; each stage gets a subdirectory of it.

  • charge (int, optional) – Total charge of the system.

  • multiplicity (int, optional) – Spin multiplicity, 2S + 1.

  • orca_path (str or pathlib.Path or None, optional) – Full path to the ORCA binary. Required for n_procs > 1. Falls back to $ASE_ORCA_COMMAND, $ORCA_COMMAND, $ORCA_PATH then PATH.

  • n_procs (int, optional) – MPI ranks for %pal.

  • maxcore (int, optional) – Memory per rank in MB.

  • optimise (bool, optional) – Optimise the geometry before the single points.

  • frequencies (bool, optional) – Run frequencies, giving the ZPE and thermal corrections, and verifying the stationary point.

  • transition_state (bool, optional) – Search for a saddle rather than a minimum, and expect exactly one imaginary mode.

  • opt_method (str, optional) – Level of theory for the geometry stage, either an ORCA keyword or a CHEAP_METHODS alias – "gfn2-xtb" resolves to the native implementation. A “3c” composite or an xTB Hamiltonian carries its own basis; anything else is paired with opt_basis.

  • opt_basis (str or None, optional) – Basis for an opt_method that has none of its own. Defaults to def2-TZVP.

  • cc_method (str, optional) – Coupled-cluster method, e.g. "DLPNO-CCSD(T)".

  • cc_extra (str, optional) – Extra keywords for the CC stage. "TightPNO" keeps the local approximation error well below the extrapolation error.

  • mp2_method (str, optional) – MP2 method for the CBS stages.

  • basis_family (str, optional) – "cc", "aug-cc" or "def2". Diffuse functions matter for anions and for weakly bound complexes.

  • cardinals (tuple of int, optional) – Basis cardinal numbers to extrapolate between, e.g. (3, 4) for cc-pVTZ/cc-pVQZ. (2, 3) is the cheap variant.

  • cc_cardinal (int or None, optional) – Cardinal number for the coupled-cluster stage. Defaults to the smaller of cardinals; if it is not one of them an extra MP2 job is run there so the delta stays consistent.

  • extrapolate_cc (bool, optional) – Extrapolate CCSD(T) directly instead of correcting an MP2 limit.

  • aux_basis (str or None, optional) – Auxiliary basis for the RI stages; ORCA picks one automatically if this is None.

  • scf_convergence (str, optional) – SCF convergence keyword applied to every stage.

  • frozen_core (bool, optional) – Freeze core orbitals in the correlated stages.

  • solvent (str or None, optional) – ORCA solvent name for a CPCM correction. None gives gas phase.

  • reuse (bool, optional) – Skip stages whose output already says ORCA TERMINATED NORMALLY.

  • verbose (bool, optional) – Print each stage as it runs, then the final summary.

Returns:

GoldStandard – Energies in Hartree, plus per-stage components and directories.

Raises:

  • ValueError – If basis_family and cardinals are not tabulated, or n_procs >     1 and the resolved ORCA command is not an absolute path – which ORCA’s own MPI launcher requires.

  • FileNotFoundError – If the ORCA binary cannot be located; see _resolve_orca().

  • RuntimeError – If what was located does not look like ORCA.

reaction_energy(reactants: list[GoldStandard], products: list[GoldStandard], thermo: str = 'gibbs') → float[source]

Compute a reaction energy from completed compound jobs.

Parameters:

  • reactants (list of GoldStandard) – The two sides of the reaction. List a species once per equivalent, so the stoichiometry balances.

  • products (list of GoldStandard) – The two sides of the reaction. List a species once per equivalent, so the stoichiometry balances.

  • thermo (str, optional) – Which energy to difference: "electronic", "enthalpy" or "gibbs". The latter two need jobs run with frequencies=True.

Returns:

float – Reaction energy in kcal/mol.

Raises:

  • KeyError – If thermo is not one of the three names above.

  • ValueError – If any species lacks the requested thermal correction.