Skip to content

ORCA

ORCA: write orca.inp, run orca orca.inp, and parse stdout and output files.

Inputs map to ORCA as follows:

  • model.method and model.basis start the simple-input line, ! method basis. Extra simple-input words, such as CPCM(water), TightSCF, or D3BJ, can go in model.method after the method name. Leave basis empty for composite methods.
  • The calculation type adds ! energy/engrad/freq/opt/optts. {"numgrad": True} and {"numfreq": True} request numerical derivatives.
  • A keyword set to True adds a simple-input word, so {"tightscf": True} writes ! tightscf; False or None leaves it out. Any other non-dictionary value is an error, so nothing is dropped silently.
  • {"maxcore": 2000} and {"pal": 4} become %maxcore and %pal nprocs. ORCA runs serially unless pal (or threads) is given, whatever the calculation's thread count: its parallel runs need OpenMPI's mpirun (without it they fail, kind environment), so they are asked for, never assumed. A count smaller than pal lowers it, with a resource_capped warning.
  • A keyword whose value is a dictionary becomes an input block: {"scf": {"maxiter": 200}} writes %scf maxiter 200 end. Keys are kept as written; ORCA ignores case.
  • The structure is written to geometry.xyz with its charge and multiplicity. Setting coords, or method/basis inside a block, is an error.
  • cmdline_args are appended to the orca command.

Calculation types: energy, gradient, hessian (also the gradient where ORCA gives it: keywords={"engrad": True} asks for it beside ! freq, which also tightens ORCA's SCF convergence; and the harmonic frequencies and normal modes from <basename>.hess: unit-length Cartesian displacements without translations and rotations, imaginary frequencies negative), optimization, and transition_state (OptTS; give ORCA a starting Hessian, e.g. {"geom": {"calc_hess": True}}). ORCA keeps the input's coordinates and atom order. No input field carries atom indices.

Keywords are checked as far as the codec can: values must be True, a dictionary, False/None, or maxcore/pal numbers. ORCA's simple-input words, blocks and block settings are too many to list, but ORCA refuses an unknown one itself before calculating anything, and the codec reports that as kind input, code unknown_key (a misspelled method or basis set is input without a code).

Failures and their kinds: an SCF that does not converge is convergence (code scf_not_converged), with the energy of its last iteration; coupled-perturbed SCF equations (for analytic Hessians) that end with perturbations above their tolerance are convergence (response_not_converged), with the results ORCA wrote, since ORCA itself carries on with them; an optimization that runs out of cycles is convergence (max_iter), with its trajectory attached (ORCA itself reports it as a normal termination); a multiplicity the number of electrons cannot have is input; a module out of memory is resource (host_memory), with required_gib and available_gib in the error's details where ORCA prints what a step needed against %maxcore (the SCF's estimate, DLPNO's minimum), in the terms of ORCA's memory keyword: the %maxcore with which the step fits and the one it ran with, each times the processes (ORCA's per-process MB of 2^20 bytes), in GiB. Any other error termination is internal, with ORCA's error line.

ORCA stops when the SCF does not converge unless %scf ConvIgnored true lets it carry on with the unconverged SCF; its results then come with the warning loosely_converged, whose message gives the last iteration's residuals.

Run ORCA by its full path: its parallel runs need it, and on many Linux desktops /usr/bin/orca is the GNOME screen reader. qccompute always runs the absolute path; put ORCA first on PATH or set QCCODEC_ORCA_EXECUTABLE.

Examples

Each script runs as written. Copy it, delete the options you don't need, and run it with python script.py. They live in the repository's examples/ folder.

Single point: energy, gradient, Hessian

examples/orca/single_point.py

"""ORCA single point: energy, gradient, or Hessian.

Requires: ``pip install qccompute[qccodec]`` and ORCA, free for academic use from
https://orcaforum.kofo.mpg.de. Put the ORCA directory first on PATH, or point qccodec
at it with QCCODEC_ORCA_EXECUTABLE: on many Linux desktops ``/usr/bin/orca`` is the
GNOME screen reader, not ORCA. Parallel runs (``pal``) also need the OpenMPI version
ORCA was built with, and ORCA stops with "ORCA has to be called with full pathname"
unless it runs by its absolute path, which qccodec always does.

How the codec talks to ORCA (manual: https://www.faccts.de/docs/orca/6.0/manual/):

- ``model.method`` and ``model.basis`` start the simple-input line, ``! method basis``.
  Further simple-input words go in ``model.method`` after the method name, e.g.
  "wB97X-D3 TightSCF" or "b3lyp D3BJ CPCM(water)". Leave ``basis`` out for composite
  methods such as "r2scan-3c".
- The calculation type adds ``! Energy``, ``! EnGrad``, or ``! Freq``.
- ``maxcore`` (MB per process) and ``pal`` (number of processes) become ``%maxcore``
  and ``%pal nprocs ... end``.
- A keyword whose value is a dictionary becomes an input block:
  ``{"scf": {"maxiter": 200}}`` writes ``%scf maxiter 200 end``.
- A keyword set to True adds a simple-input word: ``{"TightSCF": True}`` writes
  ``! tightscf`` (ORCA ignores case), and ``numgrad``/``numfreq`` request
  numerical gradients and Hessians. False or None leaves the word out.
- The molecule is passed in your coordinates and atom order; ORCA does not move it.
- ORCA stops on an unknown simple-input word ("INPUT ERROR ... UNRECOGNIZED OR
  DUPLICATED KEYWORD(S)"); the raised error carries ORCA's output.
"""

from qccompute import compute
from qcdata import CalcType, Model, ProgramInput, Structure

calctype = CalcType.gradient  # or CalcType.energy, CalcType.hessian

# Coordinates are in bohr (Structure.from_xyz / Structure.open read angstrom files).
structure = Structure(
    symbols=["O", "H", "H"],
    geometry=[[0.0, 0.0, 0.0], [0.524, 1.687, 0.48], [1.146, -0.45, -1.354]],
    charge=0,
    multiplicity=1,
)

prog_input = ProgramInput(
    program="orca",
    calctype=calctype,
    structure=structure,
    # Simple-input words after the method; CPCM(water) is implicit solvent.
    model=Model(method="wB97X-D3 TightSCF CPCM(water)", basis="def2-SVP"),
    # e.g. Model(method="r2SCAN-3c") with no basis, or "uks" for open shells
    keywords={
        "maxcore": 1000,  # memory per process, MB
        # "pal": 4,  # parallel processes (needs OpenMPI)
        #
        # Any ORCA input block, as a dictionary:
        "scf": {"maxiter": 200},
        # "cpcm": {"epsilon": 80.4, "refrac": 1.33},  # a custom solvent, with "CPCM"
        #
        # Numerical derivatives, for methods without analytic ones:
        # "numgrad": True,
        # "numfreq": True,
    },
)

output = compute(
    prog_input,
    # timeout=3600,  # seconds before ORCA is killed
)

results = output.results
print("Energy (Hartree):", results.energy)
if results.gradient is not None:
    print("Gradient (Hartree/bohr):\n", results.gradient)
if results.hessian is not None:
    print("Hessian (Hartree/bohr^2), shape:", results.hessian.shape)
    print(
        "Frequencies (cm^-1):", results.vibrational_analysis.frequencies
    )  # imaginary are negative
    print(
        "Normal modes (modes, atoms, xyz):",
        results.vibrational_analysis.normal_modes_cartesian.shape,
    )
print("ORCA version:", results.provenance.program_version)

Optimization

examples/orca/optimization.py

"""ORCA geometry optimization with its built-in optimizer.

Requires: ``pip install qccompute[qccodec]`` and ORCA on PATH, ahead of
``/usr/bin/orca`` (the GNOME screen reader on many Linux desktops); or set
QCCODEC_ORCA_EXECUTABLE. See single_point.py for installing and running ORCA.

Notes for ORCA optimizations (manual: https://www.faccts.de/docs/orca/6.0/manual/,
"Geometry Optimization"):

- The codec adds ``! Opt``. Convergence presets are simple-input words that go in
  ``model.method``: "LooseOpt", "TightOpt", "VeryTightOpt".
- Optimizer settings go in the ``geom`` block: ``{"geom": {"maxiter": 100}}``.
  Constraints and scans also live there, with ORCA's 0-based atom indices, which
  match ``structure``.
- Every step in ``results.frames`` carries its structure, energy, and gradient,
  read from ORCA's ``orca_trj.xyz`` and its output.
- The first step is your input structure: ORCA does not move or reorient it.
- For transition states use ``CalcType.transition_state`` (transition_state.py).
"""

from qccompute import compute
from qcdata import CalcType, Model, ProgramInput, Structure

# Coordinates are in bohr.
structure = Structure(
    symbols=["O", "H", "H"],
    geometry=[[0.0, 0.0, 0.0], [0.524, 1.687, 0.48], [1.146, -0.45, -1.354]],
    charge=0,
    multiplicity=1,
)

prog_input = ProgramInput(
    program="orca",
    calctype=CalcType.optimization,
    structure=structure,
    # Simple-input words after the method: convergence preset, solvent, ...
    model=Model(
        method="wB97X-D3 TightOpt", basis="def2-SVP"
    ),  # add "CPCM(water)" for solvent
    keywords={
        "maxcore": 1000,  # memory per process, MB
        # "pal": 4,  # parallel processes (needs OpenMPI)
        "geom": {
            "maxiter": 50,  # optimization steps
            # "calc_hess": True,  # exact Hessian at the first step
        },
    },
)

output = compute(prog_input)  # timeout=... (seconds)

results = output.results
print("Frames (structures evaluated):", len(results.frames))
print("Energies (Hartree):", results.energies)
print("Final structure (bohr):\n", results.final_structure.geometry)
# Save the trajectory, e.g. to view in a molecule viewer:
# results.save("optimization.json"); results.final_structure.save("final.xyz")

Transition state

examples/orca/transition_state.py

"""ORCA transition-state search (OptTS).

Requires: ``pip install qccompute[qccodec]`` and ORCA on PATH, ahead of
``/usr/bin/orca`` (the GNOME screen reader on many Linux desktops); or set
QCCODEC_ORCA_EXECUTABLE. See single_point.py for installing and running ORCA.

Notes for ORCA transition-state searches (manual:
https://www.faccts.de/docs/orca/6.0/manual/, "Transition State Searches"):

- The codec adds ``! OptTS``. ORCA's eigenvector-following needs a good starting
  Hessian: ``{"geom": {"calc_hess": True}}`` computes the exact one at the first step
  (ORCA otherwise starts from a model Hessian and can miss the saddle point).
  ``recalc_hess`` recomputes it every n steps for difficult cases.
- Start close to the saddle point. This example starts from nearly planar ammonia;
  its inversion transition state is planar, with one imaginary frequency.
- Check the result with a Hessian (single_point.py with CalcType.hessian): a
  transition state has exactly one imaginary (negative) frequency.
- For a scan or NEB to find a starting guess, see ORCA's manual; the codec runs only
  the OptTS step itself.
"""

from qccompute import compute
from qcdata import CalcType, Model, ProgramInput, Structure

# Nearly planar ammonia, coordinates in bohr.
structure = Structure(
    symbols=["N", "H", "H", "H"],
    geometry=[
        [0.0, 0.0, 0.25],
        [1.77, 0.0, -0.10],
        [-0.885, 1.533, -0.10],
        [-0.885, -1.533, -0.10],
    ],
)

prog_input = ProgramInput(
    program="orca",
    calctype=CalcType.transition_state,
    structure=structure,
    model=Model(method="wB97X-D3", basis="def2-SVP"),
    keywords={
        "maxcore": 1000,  # memory per process, MB
        # "pal": 4,  # parallel processes (needs OpenMPI)
        "geom": {
            "calc_hess": True,  # exact Hessian at the first step
            "maxiter": 50,
            # "recalc_hess": 5,  # recompute the exact Hessian every 5 steps
        },
    },
)

output = compute(prog_input)  # timeout=... (seconds)

results = output.results
print("Frames (structures evaluated):", len(results.frames))
print("Transition-state energy (Hartree):", results.energies[-1])
print("Transition-state structure (bohr):\n", results.final_structure.geometry)