The qc package

The `qc` package#

The curated reference for the public qc surface. Signatures show the common keyword arguments; rare numerical knobs are IOP keys.

Building a checkpoint#

qc.chk.new(atom, ao, *, ao_rep="spherical", charge=0, spin=1, unit="angstrom", ric=None, rijk=None, iop=None, backend=...): Create a checkpoint from a molecular input. atom is the mol-spec string; ao is a basis name or a per-atom dict; spin is the Gaussian multiplicity 2S+1; unit is "angstrom" (default) or "bohr"; ric/rijk are the RI auxiliary bases; iop is the fine-grained options dict. Returns a checkpoint.
qc.chk.load(path) / mychk.save(path): Restore / persist a checkpoint (HDF5 .qch5).
mychk.with_iop({...}): Return a new checkpoint with overlaid IOP keys.

Workflow verbs#

Each verb adds a pending step and returns a new checkpoint; .run() materializes results. Every verb has a functional form qc.verb(mychk, ...) and a method form mychk.verb(...) — identical.

verb	key arguments	adds
`guess(mychk, kind="sad", *, source=, occupation=, spin_break=)`	`sad`/`minao`/`harris`/`sap`/`gwh`/`core`/`read`	an initial-guess step
`ints(mychk, *, eri="4c-auto", dipole=False)`	the ERI strategy	an integral-materialization step
`scf(mychk, *, ref="auto", xc=None, grid="medium", algorithm="auto", conv_tol=, conv_preset=, max_cycle=, pcm=, dispersion=, stability=, smearing=, level_shift=, damping=, mom=, symmetry=, prop=)`	the SCF controls	an SCF step
`lct(mychk, *, method="mp2")`	`mp2`/`scs-mp2`/`sos-mp2` (real); `cc2`/CASPT2/NEVPT2 (mock)	a correlation step
`casscf` / `fci` / `dmrg` / `td`	—	mock method steps
`grad(mychk)` / `mychk.scf.gradient`	—	analytic nuclear gradient
`mychk.scf(...).opt(*, coordsys="tric", maxiter=100)`	geomeTRIC controls	a geometry-optimization step

.run(*, log=None, log_style="modern", plot=False, nthread=None, nmpi=1, hosts=None, comm=None, log_rank="root"): Execute pending steps. log streams the transcript ("stdout"/path/object); nthread/nmpi/hosts/comm set parallelism (Part IV).

Result accessors#

After .run() (details in Checkpoints):

mychk.scf.energy / .converged / .ncycle / .energy_elec / .energy_components / .gradient / .stability
mychk.lct.energy / .e_corr / .e_os / .e_ss
mychk.opt.converged / .energy / .e_traj / .gmax_traj / .grms_traj
mychk.natom / .symbols / .charge / .spin / .nelectron() / .coordinates() / .nuclear_energy()
mychk.log(format=) / .show() / .run_events()

`qc.prop` — molecular properties#

qc.prop.<group>.<leaf>(mychk) (≡ mychk.prop.<group>.<leaf>()), lazily computed and cached. The 14 groups:

group		group
`chrg`	atomic charges	`qtaim`	QTAIM topology / basins
`bond`	bond orders	`elf`	ELF/LOL basins
`mpol`	electric moments, polarizability	`arom`	aromaticity indices
`cdft`	reactivity, Fukui	`orb`	orbital analysis
`nbo`	NBO / IAO / IBO	`spin`	spin density, ⟨S²⟩
`esp`	electrostatic potential	`spec`	DOS, gap, band center
`mesh`	real-space grid fields (NCI/IGM)	`geom`	geometric analysis

scf(..., prop=True|preset|[refs]) computes a bundle eagerly. See the properties suite.

Other namespaces#

qc.iop — options registry: qc.iop.list(), qc.iop.describe(key), qc.iop.defaults() (reference).

qc.basis — basis data: qc.basis.baslib_filename (229 names), qc.basis.nwchem_format(inpdata, description=, ecp=) (reference).

qc.view — visualization: mychk.view3d(field|orbital|orbitals, ...), mychk.mo_cube(...), mychk.orbitals, mychk.plot_nci(), mychk.plot_convergence(), mychk.plot_field_plane(...), and .to_html() (Visualization).

Lower-level (rarely needed directly): qc.array (N-D arrays, eigh, elementwise/reduction ops), qc.mol (the molecular data model), qc.utils (e.g. qc.utils.quatdiag), qc.integrals (experimental libcint-backed shell/tensor helpers).

Optional modules (feature-gated, guarded by sentinels): qc.xc (libxc functionals; qc.XC_ENABLED), qc.pcm (PCM solvation context; qc.PCM_ENABLED), the Rust MPI-direct functions (qc.MPI_DIRECT_ENABLED), and the GPU path (qc.GPU_ENABLED).

Sentinels#

import qc
qc.XC_ENABLED, qc.PCM_ENABLED, qc.MPI_DIRECT_ENABLED, qc.GPU_ENABLED

Each is True only if the corresponding feature was compiled into your build. A default build has XC_ENABLED == PCM_ENABLED == MPI_DIRECT_ENABLED == True and GPU_ENABLED == False (the GPU path is opt-in; GPU chapter).

That is the public surface. From here, the guide chapters show each piece in context, and the reference sections give the exhaustive details.