# What is qc-rs?

**qc-rs** is a *quantum-chemistry toolkit*: software that solves the equations of quantum mechanics for
molecules and turns them into numbers you can interpret — total energies, equilibrium structures, atomic
charges, chemical bonding, reactivity, spectra, and much more. You drive it from **Python** (the `qc`
package); the heavy numerical work runs in a fast compiled **Rust** core (`qc_rs`).

:::{note} Who this manual is for
This is an **approachable, textbook-style** manual. It assumes you have seen a little chemistry and
calculus, but **not** that you already know quantum chemistry, high-performance computing, or even much
Python. New concepts are introduced from the ground up — with the theory (and the equations) behind them,
not just a recipe to copy. It should be usable by an undergraduate meeting electronic-structure theory for
the first time, and still useful to a graduate student running production calculations.
:::

## What you can compute

A quick tour of what qc-rs does (each has its own chapter later):

- **Self-consistent field (SCF)** — Hartree–Fock and Kohn–Sham density-functional theory (DFT), for
  closed- and open-shell molecules (RHF/UHF/ROHF), with many functionals.
- **Correlated methods** — the RI-MP2 family today; CASSCF / FCI / DMRG and excited states are planned.
- **Forces & geometry optimization** — analytic nuclear gradients, so you can relax a molecule to its
  equilibrium structure.
- **Molecular properties** — a large analysis suite: atomic charges and bond orders, QTAIM and ELF/LOL
  topology, non-covalent-interaction maps (NCI, IGM), aromaticity indices, conceptual-DFT reactivity, and
  real-space fields on a grid. This is *Multiwfn-class* wavefunction analysis, built into the toolkit.
- **Environment & corrections** — implicit solvation (PCM / SMD) and dispersion corrections (DFT-D3/D4).
- **Scale** — the same code runs on a laptop and on a supercomputer, using multiple CPU threads, many
  machines via **MPI**, or a **GPU**. You do not need to know any of that to get started —
  [Part IV](../30-hpc/index.md) teaches it from zero when you are ready.

## How qc-rs is built

qc-rs is deliberately split into two layers, and understanding the split explains a lot about how you use
it and why it is fast.

- **A compiled Rust core.** The numerically heavy work — building the integrals over basis functions,
  assembling and diagonalizing the Fock matrix, evaluating densities on a grid, computing gradients — is
  written in **Rust**, a modern compiled language that reaches C/Fortran speed while being memory-safe. It
  is organized as a set of focused libraries ("crates"): one for integrals, one for the SCF solver, one for
  grids, one for the exchange–correlation functionals, one for the property suite, one for gradients, and so
  on. Underneath, it links a highly-tuned **BLAS/LAPACK** library (OpenBLAS or Intel MKL) for the dense
  linear algebra and the **libxc** library for the DFT functionals.
- **A Python front end.** You never write Rust to *use* qc-rs. The `qc` package gives you an ergonomic,
  PySCF-style Python API; the Rust core is exposed to it as a single compiled extension module (`qc_rs`,
  which is why "installing qc-rs" means compiling that extension). Python is where you build molecules,
  orchestrate the workflow, and read results — where convenience matters more than raw speed.

The payoff is the best of both worlds: **Python's ease for the human, Rust's speed for the machine.** You
get an interactive, notebook-friendly interface backed by production-grade numerics, and — because the core
is compiled — the same code scales from a laptop to a supercomputer ([Part IV](../30-hpc/index.md)).

## How qc-rs is developed: AI-first ("vibe coding")

qc-rs is not only *usable* with AI coding assistants — it is largely *written* by them. Development is
**AI-first** — sometimes called **"vibe coding"** — and this is a deliberate, first-class methodology, not a
novelty. The Rust core, the Python API, the large property suite, and even *this manual* are authored with
assistants such as **Claude Code** and **Codex** under human direction and review. That is a big part of why
one project can cover so much ground so quickly. The guardrail that keeps it trustworthy is the
verification-first discipline (below): every method is checked against an independent reference, and numbers
are never accepted on faith.

**The exceptions are the external libraries qc-rs links** — established, hand-written C/Fortran foundations
it builds *on*, not *from* AI:

- **[libcint](https://github.com/sunqm/libcint)** (Dr. Qiming Sun) — the Gaussian-integral engine at the
  computational **heart** of every SCF. qc-rs wraps it rather than reimplementing the integral kernels.
- **[libxc](https://gitlab.com/libxc/libxc)** (Miguel A. L. Marques, Susi Lehtola, and collaborators) — the
  library of exchange–correlation functionals behind the DFT (`xc=`) methods.

Around these classics, qc-rs contributes the modern Rust toolkit — the workflow, the SCF and correlation
solvers, the analysis suite, the gradients, and the HPC machinery — mostly AI-authored, and thoroughly
verified.

## What makes qc-rs distinctive

Several design choices set qc-rs apart from a typical quantum-chemistry program:

- **A composable checkpoint/workflow model.** Instead of a monolithic "input file → output file" run, a
  calculation is a checkpoint you extend one step at a time — it remembers its electronic state and results
  and can be saved, restarted, and analyzed incrementally (the next section, and
  [Core concepts](concepts.md)).
- **Wavefunction analysis is first-class, not an afterthought.** Many programs stop at the energy and leave
  you to export a file into a *separate* analysis tool. qc-rs builds a large, **Multiwfn-class** property
  suite directly into the toolkit, so you go from an SCF straight to charges, bond orders, QTAIM, ELF,
  non-covalent-interaction maps, aromaticity, or conceptual-DFT reactivity without ever leaving Python.
- **Faithful, validated re-implementations in pure Rust.** Where a trusted reference exists, qc-rs ports it
  into Rust and reproduces its numbers — the integrals via libcint, the DFT-D3/D4 dispersion from the
  Grimme group's code, the PCM solvation from PCMSolver — each cross-checked against the original and
  credited. Analyses whose source is not license-compatible (e.g. Multiwfn's) are re-derived *clean-room*
  from the published papers and validated black-box against the reference.
- **HPC is built in, not bolted on.** CPU threads, MPI across many machines, and an optional NVIDIA-GPU
  path are part of the design — backed by a purpose-built scratch-memory allocator and one-sided (RMA)
  distributed primitives — so the same code runs on a laptop and on a cluster.

## Design philosophy & goals

qc-rs is guided by a few convictions:

- **Correctness first — and demonstrably so.** Every method is validated against a trusted reference
  (libcint, PySCF, or Multiwfn) to tight tolerances before it ships; **numbers are never guessed**. The
  code is equally careful about the traps that *silently* corrupt large calculations — for example the
  32-bit-integer ceilings inside BLAS/LAPACK and MPI — treating them as standing hazards, not surprises.
- **Speed without sacrificing safety.** Rust delivers C/Fortran performance with memory safety. Hot paths
  reuse one large scratch allocation instead of churning memory, route dense algebra through tuned
  BLAS/LAPACK, and keep `unsafe` confined to the narrow foreign-function boundary.
- **Self-contained, but standing on giants.** The aim is to do the *whole* job — input, SCF, correlation,
  gradients, properties, solvation, dispersion — in one place, while **faithfully building on the best
  reference implementations (with attribution)** rather than reinventing them poorly.
- **Open and familiar.** It is free software (**LGPL-3.0-or-later**), accepts a PySCF-style input you may
  already know, and exposes everything through one ergonomic Python API.

The goal, in a sentence: **a modern, fast, correct, and self-contained quantum-chemistry toolkit that takes
you from a molecule to deep, trustworthy analysis in one place — and scales from your laptop to a
supercomputer.**

## The big idea: checkpoints & workflows

Most of qc-rs is organized around one object, the **checkpoint**. You create a checkpoint from a molecular
input (geometry, basis set, charge, spin), then *add steps* to it — an SCF calculation, a property, a
geometry optimization — and finally call `.run()` to carry them out. The checkpoint remembers the current
electronic state and every result, so a calculation reads like a short, composable pipeline. We unpack this
model carefully in [Core concepts](concepts.md); for now, here is what it looks like.

## A first taste

```python
import qc

# Build a checkpoint: a water molecule in the cc-pVDZ basis set.
mychk = qc.chk.new(
    atom="O 0.0000 0.0000 0.1173; H 0.0000 0.7572 -0.4692; H 0.0000 -0.7572 -0.4692",
    ao="cc-pvdz",
    unit="angstrom",
)

# Add a restricted Hartree–Fock step and run it.
mychk = mychk.scf(ref="r").run()

print(mychk.scf.energy)      # -76.026772  (total RHF energy, in hartree)
print(mychk.scf.converged)   # True
```

That is a complete Hartree–Fock calculation of a water molecule. The [Quickstart](quickstart.md) walks
through it line by line and runs it for real.

:::{tip} A Python note
`qc.chk.new(atom=..., ao=..., unit=...)` uses **keyword arguments** — each value is labelled by name
(`atom=`, `ao=`), so the order does not matter and the call documents itself. You will see this style
throughout qc-rs.
:::

## How qc-rs relates to tools you may know

If you have used **PySCF**, the molecular-input style (`atom=`, basis names, `charge`/`spin`) will feel
familiar. If you have used **Multiwfn** for wavefunction analysis, you will recognize the property suite —
qc-rs implements those analyses directly (clean-room, from the original papers) so you can go from an SCF
straight to charges, bond orders, or an NCI plot without leaving Python. qc-rs is free software under the
**LGPL-3.0-or-later** license.

## How to read this manual

- **Part I — Getting started** (you are here): install qc-rs, set up your editor and tools, run your first
  calculation, and learn the checkpoint/workflow model.
- **[Part II — Foundations](../10-foundations/index.md)**: the quantum-chemistry theory the rest of the
  manual builds on — the many-electron problem, basis sets, Hartree–Fock, and DFT.
- **[Part III — User guide](../20-guide/molecular-input.md)**: the day-to-day calculations, feature by
  feature, ending with the [molecular-properties suite](../20-guide/properties/index.md).
- **[Part IV — Parallel computing & HPC](../30-hpc/index.md)**: threads, MPI, and GPUs, taught from zero.
- **[Part V — Reference](../40-reference/mol-spec.md)** and the **[API reference](../90-api/index.md)**: the
  precise details.

You can read Part I and Part II in order, then dip into the guide as needed. Ready? Let's
[install qc-rs and run something](installation-and-make-setup.md).