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.
  • 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 when ORCA writes it), 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.

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 QCCOMPUTE_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`` (it installs qccodec) and ORCA, free for academic
use from https://orcaforum.kofo.mpg.de. Put the ORCA directory first on PATH, or point
qccompute at it with QCCOMPUTE_ORCA_EXECUTABLE or ``executables={"orca": ...}``: 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
qccompute does from the release after 0.15.0 (the one with ``executables=``).

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
    # collect_files=True,  # keep every output file (orca.gbw, orca.hess, ...)
    # executables={"orca": "/opt/orca/orca"},  # or set QCCOMPUTE_ORCA_EXECUTABLE
)

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("ORCA version:", results.provenance.program_version)

Optimization

examples/orca/optimization.py

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

Requires: ``pip install qccompute`` (it installs qccodec) and ORCA on PATH, ahead of
``/usr/bin/orca`` (the GNOME screen reader on many Linux desktops); or set
QCCOMPUTE_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.trajectory`` 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=..., collect_files=..., executables=...

results = output.results
print("Steps:", len(results.trajectory))
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`` (it installs qccodec) and ORCA on PATH, ahead of
``/usr/bin/orca`` (the GNOME screen reader on many Linux desktops); or set
QCCOMPUTE_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=..., collect_files=..., executables=...

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