External QC codes (ORCA / Psi4 / others)

vibe-qc plays well with other quantum-chemistry codes via ASE’s calculator interface. The :mod:vibeqc.benchmark cross-validation framework treats ORCA, Psi4, NWChem, Gaussian, Q-Chem, and PySCF as peers — same Atoms goes through every available code, results land in a shared comparison table, you assert agreement (or investigate the disagreement).

This page documents:

1. Which external codes vibe-qc’s benchmark framework supports.

2. How to install each (we don’t redistribute external codes — user provisions, we point at the installation).

3. The Python-environment realities (Psi4’s conda lock-in, ASE-Python-API vs ASE-FileIO modes, etc.).

4. Licensing / redistribution constraints worth knowing about.

Tip

The fastest sanity check that the codes are wired up correctly is python -c "from vibeqc.benchmark import print_calculator_availability; print_calculator_availability()" — it probes every supported calculator and reports which is available, with diagnostic notes on what’s missing.

Supported calculators at a glance

Code	Type	Implementation	License	Status
vibe-qc	Python-native	Built-in	MPL-2.0	always available
PySCF	Python-native	Built-in DIY shim (vibeqc.benchmark.PySCFCalculator)	Apache-2.0	pip install pyscf
ORCA	FileIO subprocess	ASE’s ase.calculators.orca	Proprietary, academic-free	user-installed binary
Psi4	Python-bindings	ASE’s ase.calculators.psi4	LGPL-3.0	user-installed (conda); same Python required
NWChem	FileIO subprocess	ASE’s ase.calculators.nwchem	ECL-2.0	user-installed binary
Gaussian	FileIO subprocess	ASE’s ase.calculators.gaussian	Commercial	user-installed binary
Q-Chem	FileIO subprocess	ASE’s ase.calculators.qchem	Commercial	user-installed binary
GAMESS-US	FileIO subprocess	ASE’s ase.calculators.gamess_us	Free for academic use	user-installed binary
Turbomole	FileIO subprocess	ASE’s ase.calculators.turbomole	Commercial	user-installed binary

“FileIO subprocess” means the ASE wrapper writes an input file, spawns the external binary as a subprocess, and parses the output — so the binary has to be on $PATH. “Python-bindings” means ASE imports the code’s Python module — so it has to be importable in the same interpreter as vibe-qc.

PySCF — Python-native

PySCF is the Python-native QC stack we use for cross-validation in CI. It’s MPL-2.0-compatible, on PyPI, and installs into the same venv as vibe-qc.

.venv/bin/pip install pyscf

vibe-qc’s framework wraps PySCF via a built-in :class:vibeqc.benchmark.PySCFCalculator (a thin ASE adapter we ship rather than relying on the third-party ase-pyscf package — avoids an extra dependency). Supported methods: RHF, UHF, RKS, UKS, with energy + forces.

from vibeqc.benchmark import PySCFCalculator

calc = PySCFCalculator(basis="6-31g*", method="RHF")
calc = PySCFCalculator(basis="6-31g*", method="RKS",
                       functional="PBE")

Note

The shim does from pyscf import grad automatically — that’s what registers the per-method mf.Gradients() factory on PySCF’s SCF classes. Without it, mf.Gradients() would raise NotImplementedError from PySCF’s base class.

ORCA

ORCA is a feature-rich QC package from the Max-Planck-Institut für Kohlenforschung + FACCTS GmbH. Free for academic use with registration at https://orcaforum.kofo.mpg.de/; commercial licensing via FACCTS.

Warning

vibe-qc does not redistribute ORCA. You’ll need to download and install it yourself from the official site. If you’re at a university or non-profit research institution, the academic license is free; commercial users need a FACCTS license. The binary install for ORCA 6.x is ~3 GB and includes its own MPI

• supporting libraries.

macOS install

The macOS binary ships unsigned outside the Mac App Store, so Gatekeeper will refuse to load the dylibs unless you remove the quarantine attribute:

# After unzipping the official tarball to e.g. ~/orca_6_1_1_macosx_arm64_openmpi411
cd ~/orca_6_1_1_macosx_arm64_openmpi411
sudo xattr -r -d com.apple.quarantine .
./orca --version       # should print the ORCA banner

Linux install

Linux binaries usually run as-is once unzipped. Verify with:

cd ~/orca_6_1_1_linux_x86_64_openmpi411
./orca --version

Make ORCA discoverable

The vibe-qc framework looks for the orca binary via, in order:

1. Environment variable ASE_ORCA_COMMAND (full command template, e.g. "orca PREFIX.inp > PREFIX.out")

2. Environment variable ORCA_COMMAND (just the binary path)

3. Environment variable ORCA_PATH (install directory; we look for $ORCA_PATH/orca)

4. which orca — $PATH lookup

Pick whichever fits your shell / shell-init story. Common pattern:

# In .bashrc / .zshrc:
export ORCA_PATH="$HOME/orca_6_1_1_macosx_arm64_openmpi411"
export PATH="$ORCA_PATH:$PATH"

Then make_orca_calculator(...) returns a ready-to-use ASE calculator:

from vibeqc.benchmark import make_orca_calculator

orca = make_orca_calculator(orcasimpleinput="HF 6-31G* EnGrad")
if orca is None:
    print("ORCA not found — set ORCA_PATH or add orca to PATH")

orcasimpleinput= is the ORCA “simple input” line — the same syntax you’d put on the ! line in an ORCA input file. Always end with EnGrad if you want forces (otherwise ASE falls back to finite-difference on energies, which is much slower).

License + redistribution

• ORCA’s license explicitly forbids redistribution of the binaries. Don’t bundle ORCA into a Docker image, conda package, or shared-server install that other users access. Each user provisions their own copy under their own license.

• The ORCA forum at https://orcaforum.kofo.mpg.de/ requires registration but is free for academics; commercial users go through https://www.faccts.de/.

• Output files (.out, .gbw, .hess) are yours to share / publish freely — the license restricts the binary, not the results.

Psi4

Psi4 is a permissive-licensed (LGPL-3.0) QC package with strong emphasis on coupled-cluster methods. ASE’s Psi4 wrapper is Python-bindings based: it does import psi4 in the same Python interpreter as the calculator, then calls Psi4’s Python API directly. So the binary on $PATH is not enough — the matching psi4 Python module needs to be importable in your vibe-qc venv.

The conda Python-version trap

The official Psi4 distribution ships as a self-contained conda environment (psi4conda installer). It pins a specific Python version — at the time of writing, Python 3.13. vibe-qc’s venv is whatever Python 3.11+ you set up. If those don’t match, import psi4 fails with ImportError from a binary-incompatible extension module, even though psi4 --version on the command line works fine.

Two ways out:

1. Pip-install psi4 into the vibe-qc venv (when available):

   pip install psi4
   

   Currently Psi4 isn’t on PyPI directly — only conda. Track https://psicode.org/psi4manual/master/build_planning.html for the PyPI status.

2. Run vibe-qc inside the psi4conda env — the inverse: activate psi4conda first, then pip install vibe-qc into that env. You lose the venv-isolation pattern documented elsewhere, but you get a working import psi4 plus vibe-qc.

Detection

vibe-qc’s detect_calculators() distinguishes “no Psi4 anywhere” from “Psi4 binary on PATH but import psi4 fails in this Python”:

psi4    ✗ missing  (psi4 binary at /Users/.../psi4conda/bin/psi4,
                    but `import psi4` fails in this Python.
                    Either pip-install psi4 into the vibe-qc venv,
                    or run vibe-qc inside the psi4conda env.)

The version-mismatch branch is the most common state on developer machines. If you see it, install via one of the two paths above before trying make_psi4_calculator(...) — it’ll return None otherwise.

Make Psi4 discoverable

from vibeqc.benchmark import make_psi4_calculator

psi4 = make_psi4_calculator(method="hf", basis="6-31g*")
if psi4 is None:
    print("Psi4 not importable — see version-mismatch note above")

method= follows Psi4’s convention ("hf", "b3lyp", "mp2", "ccsd(t)", etc.). Forces are computed via Psi4’s analytic gradient API where supported, FD otherwise.

License + redistribution

• Psi4 is LGPL-3.0 — vibe-qc users can install it freely. We don’t redistribute it because the conda-only distribution + Python-version coupling makes redistribution awkward, not because licensing forbids it.

• Output files: yours to use freely (LGPL doesn’t restrict outputs).

NWChem / Gaussian / Q-Chem / GAMESS-US / Turbomole

These are FileIO subprocess calculators in the same family as ORCA — install the binary, put it on $PATH, the ASE wrapper spawns it. detect_calculators() finds them via shutil.which() on their conventional binary name:

Code	Binary	License	Notes
NWChem	nwchem	ECL-2.0 (academic-friendly)	https://nwchemgit.github.io/
Gaussian 16	g16	Commercial only	https://gaussian.com/
Q-Chem	qchem	Commercial	https://www.q-chem.com/
GAMESS-US	rungms	Free for academic with registration	https://www.msg.chem.iastate.edu/gamess/
Turbomole	dscf	Commercial	https://www.turbomole.org/

vibe-qc’s framework doesn’t ship a make_<code>_calculator() helper for each of these — use ASE’s wrapper directly:

from ase.calculators.nwchem import NWChem
from vibeqc.benchmark import compare_calculators
from vibeqc.ase import VibeQC

calc_nwchem = NWChem(label="nwchem-h2o",
                     basis="6-31g*", task="energy")

results = compare_calculators(
    atoms,
    [
        ("vibe-qc/RHF/6-31G*", VibeQC(basis="6-31g*")),
        ("NWChem/RHF/6-31G*",  calc_nwchem),
    ],
    properties=("energy", "forces"),
)

If you regularly cross-check against one of these, an issue requesting a make_<code>_calculator() helper alongside ORCA / Psi4 is a welcome contribution — same shape as make_orca_calculator in :mod:vibeqc.benchmark.

Sanity-check the setup

scripts/check_external_codes.sh (see Phase F roadmap) is the one-stop diagnostic — it runs print_calculator_availability() and prints the result. Until it ships, the same one-liner works:

.venv/bin/python -c "
from vibeqc.benchmark import print_calculator_availability
print_calculator_availability()
"

Expected output on a system with vibe-qc + PySCF + ORCA installed but no other external codes:

gamess_us  ✗ missing    (Python wrapper present, but 'rungms' not on $PATH …)
gaussian   ✗ missing    (Python wrapper present, but 'g16' not on $PATH …)
nwchem     ✗ missing    (Python wrapper present, but 'nwchem' not on $PATH …)
orca       ✓ available  (/Users/.../orca_6_1_1_macosx_arm64_openmpi411/orca)
psi4       ✗ missing    (Install with `pip install psi4` into the vibe-qc venv …)
pyscf      ✓ available  (Python-native)
qchem      ✗ missing    (Python wrapper present, but 'qchem' not on $PATH …)
turbomole  ✗ missing    (Python wrapper present, but 'dscf' not on $PATH …)
vibeqc     ✓ available  (Python-native)

See also

• ASE integration user guide — how the vibeqc.ase.VibeQC calculator works, and how it slots into the comparison framework.

• cross-validation tutorial — end-to-end walkthrough using ORCA + Psi4 + PySCF.

• examples/ase_compare/ — runnable scripts: H₂O HF / DFT cross-validation, water dimer dispersion, basis-set convergence sweep, NH₃ NEB barrier.