# The `qc` package

The curated reference for the public `qc` surface. Signatures show the common keyword arguments; rare
numerical knobs are [IOP keys](../40-reference/iop.md).

## 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](../40-reference/mol-spec.md);
  `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](../30-hpc/index.md)).

## Result accessors

After `.run()` (details in [Checkpoints](../40-reference/checkpoints.md)):

```text
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](../20-guide/properties/index.md).

## Other namespaces

**`qc.iop`** — options registry: `qc.iop.list()`, `qc.iop.describe(key)`, `qc.iop.defaults()`
([reference](../40-reference/iop.md)).

**`qc.basis`** — basis data: `qc.basis.baslib_filename` (229 names), `qc.basis.nwchem_format(inpdata,
description=, ecp=)` ([reference](../40-reference/basis-list.md)).

**`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](../20-guide/visualization.md)).

**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

```python
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](../30-hpc/gpu-cuda.md)).

---

That is the public surface. From here, the [guide chapters](../20-guide/molecular-input.md) show each piece in
context, and the [reference](../40-reference/mol-spec.md) sections give the exhaustive details.