Molecular QM Psi4

Psi4 capabilities for molecular quantum mechanics within the Simstack framework.

Dual-use

• Host (simstack-model): not installable — no pyproject.toml. Flat tree for

create_node_table / create_model_table (parent entrypoints + --dir).

• Container: installable — Dockerfile renames pyproject.docker → pyproject.toml

and runs uv pip install .. Shared deps install from git.

Dependencies (image)

Installed from git during the Docker build (see pyproject.docker):

• molecular_qm_models

• molecular_qm_util

• molecular_qm_dftb

• simstack (ww/new-features)

The image also installs Psi4 (conda-forge) and PySCF (pip). Both calculators

take the same QMInput model.

Use psi4_calculator, pyscf_calculator, or qm_calculator with QMEngineInput

to pick the engine. Workflow nodes such as compare_conformers, compute_energy,

multistep_optimizer, relax_harmonic, and geometric_neb expose the same switch.

Local nested checkouts of those repos are not copied into the image.

Local Docker image

Build context must be this capability package so models/util/simstack are fetched

from git rather than from whatever is checked out locally.

From this repository:

```bash

docker build \

--build-arg UV_GIT_SHAS="$(python resolve_uv_git_shas.py pyproject.docker)" \

--build-arg PACKAGE_VERSION=0.1.0 \

-t molecular-qm-psi4:latest .

```

From a simstack-model checkout, pass the subdirectory as context (not .):

```bash

docker build \

--build-arg UV_GIT_SHAS="$(python molecular_qm_psi4/resolve_uv_git_shas.py molecular_qm_psi4/pyproject.docker)" \

--build-arg PACKAGE_VERSION=0.1.0 \

-t molecular-qm-psi4:latest \

-f molecular_qm_psi4/Dockerfile molecular_qm_psi4

```

Container-only PySCF density artifacts

The capability provides two additional decorated node functions in

nodes/density_artifacts.py. Every declared input is an ODMantic Model:

• pyscf_density_calculation(QMInput, PySCFArtifactLocation) writes fixed-geometry

energy, gradient, density matrix and reloadable wavefunction arrays.

• pyscf_density_response(PySCFDensityResponseInput, PySCFArtifactLocation) reads

a checksummed paired-wavefunction shard, computes fitted PBE/PBE0 coefficients

and relaxed analytic PBE nuclear response, and writes numeric AO/angular metadata.

Both density nodes refuse execution outside Docker. Private scientific implementations

are in util/density_calculation.py, util/density_fit.py,

util/density_response.py and util/density_artifacts.py; clients call the

decorated nodes, never those utility functions. The capability has no

dependency on PyTorch or e3nn.

Results are small PySCFArtifact Models carrying kind, schema, logical host root,

relative path and SHA-256. Large arrays and full provenance stay in HDF5 files;

no wavefunctions or Hessians are returned as database arrays and no pickle is used.

Location/source requests distinguish logical host paths from native container

paths; returned references preserve the host path. Outputs are immutable unique

files, written by atomic rename. Input shard checksums are verified before

reconstruction.

Rebuild this image from the updated source, then register the new models/nodes:

```sh

docker build -t molecular-qm-psi4:latest .

```

Analytic response supports the previously validated all-electron PBE RKS/UKS

spherical s/p/d paths, with moving-grid and auxiliary-basis response and explicit CPKS

residual checks; unsupported configurations fail without a local or finite-

difference fallback.

Isolated backend tests (run in the scientific Linux environment) avoid the

repository's database-initializing legacy conftest:

```sh

python -m pytest --noconftest tests/test_density_fit.py tests/test_density_response.py tests/test_hessian_artifact.py

```

Cartesian Hessian output from the standard calculator

With QMInput.optimization=True and QMInput.frequencies=True,

pyscf_calculator reuses its existing optimization and Hessian child nodes and

returns hessian: FileStack. This is a numeric hessian.npz archive readable

with numpy.load(..., allow_pickle=False): schema version 1, hessian shaped

(n_atoms, n_atoms, 3, 3) in Hartree/Bohr^2, positions_A in Angstrom,

masses_amu using isotope-average masses, and atom-order elements.

The archive exports the Hessian already computed by the frequency workflow;

there is no second optimization or Hessian implementation. Standard FileStack

transfers deliver it to callers without requiring external-storage access in

the scientific container. The separate pyscf_optimization_hessian node is

retired. Register the updated calculator and rebuild the image before use.