API documentation
The crate-level API docs are generated by rustdoc and published alongside this
book.
Browse the API documentation →
Generated by rustdoc and published alongside this book.
That link is only present when the most recent CI run on main succeeded.
cargo doc does not link, but it does run build scripts, and
ferric-integrals' build script compiles a C++ shim needing libint2.hpp — so
the API docs are built by the CI workflow (which already builds and caches
libint2) and handed to the docs workflow as an artifact. If CI was red, the
book still publishes and this link 404s; generate the docs locally in that
case.
Generating locally
cargo doc --workspace --no-deps --open
Drop --no-deps to include dependency documentation as well (much slower, and
much larger).
If that fails with "Only one may be documented at once since they output to
the same path", add --exclude ferric-python. The pyo3 crate's lib is
deliberately named ferric — that is what makes Python's import ferric work
— which collides with the ferric facade crate. Excluding it costs nothing:
it is a cdylib, and its surface is documented in
Python bindings.
Entry points
The most useful starting points, by crate:
| Crate | Start at |
|---|---|
ferric_core | Molecule, BasisSet, Shell |
ferric_scf | solve_rhf, solve_uhf, solve_rohf |
ferric_mp2 | ri_mp2, oo_ri_mp2 |
ferric_cc | ccsd_closed_shell, ccsd_t_closed_shell |
ferric_rpa | pdep_polarizability_static, RPA correlation drivers |
ferric_gw | run_gw, run_evgw |
ferric_dft | KsXc, functional construction via libxc |
ferric_tensors | the einsum! macro |
On reading the docs
The doc comments in this codebase carry more than signatures. Where a design decision was hard-won — a convergence hazard, a memory-accounting subtlety, a parallelization that would be unsafe — the reasoning is recorded at the point of use, including cases where an apparently obvious optimization was rejected and why.
Those notes are often the most useful part of the documentation for anyone modifying the code, and they are deliberately kept next to the code rather than in prose docs that drift.