ORCA¶
ORCA: write orca.inp, run orca orca.inp, and parse stdout and output files.
Inputs map to ORCA as follows:
model.methodandmodel.basisstart the simple-input line,! method basis. Extra simple-input words, such asCPCM(water),TightSCF, orD3BJ, can go inmodel.methodafter the method name. Leavebasisempty for composite methods.- The calculation type adds
! energy/engrad/freq/opt/optts.{"numgrad": True}and{"numfreq": True}request numerical derivatives. - A keyword set to
Trueadds a simple-input word, so{"tightscf": True}writes! tightscf;FalseorNoneleaves it out. Any other non-dictionary value is an error, so nothing is dropped silently. {"maxcore": 2000}and{"pal": 4}become%maxcoreand%pal nprocs. ORCA runs serially unlesspal(orthreads) is given, whatever the calculation's thread count: its parallel runs need OpenMPI'smpirun(without it they fail, kindenvironment), so they are asked for, never assumed. A count smaller thanpallowers it, with aresource_cappedwarning.- 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.xyzwith its charge and multiplicity. Settingcoords, ormethod/basisinside a block, is an error. cmdline_argsare appended to theorcacommand.
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¶
"""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¶
"""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)