What is qc-rs?

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 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).

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 (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 (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).

  • 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; for now, here is what it looks like.

A first taste#

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

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.