qufold 0.1.0

Fermionic Hamiltonian downfolding (CFU/DUCC/PUCC/CCSD) and projective quantum eigensolvers (PQE), input-file driven.

qufold

Fermionic Hamiltonian downfolding + projective quantum eigensolvers, driven by a single Q-Chem-style input file.

qufold builds compact, accurate effective active-space Hamiltonians from a full electronic-structure problem, so that the expensive part of a quantum simulation (qubitized QPE, FCI, a projective eigensolver) runs on a small, strongly-correlated active space instead of the full orbital set. Its flagship method is CFU — Closed-Form Unitary downfolding — which applies a sequence of exact single-generator unitary similarity transforms to the Hamiltonian before projecting the external orbitals onto Hartree–Fock. "Closed-form" means each rotation e^{-θA} H e^{θA} is evaluated exactly (no Baker–Campbell–Hausdorff truncation), so every step is rigorously unitary and norm-preserving.

You write one text file and run one command:

qufold examples/cfu/h4_cfu.in

The architecture is deliberately layered so the physics is auditable and the performance is swappable: every method is written once against a small operator-algebra interface (commutator, multiply, similarity_transform, rotate_single, hf_expectation, gradient, optimal_theta) and then runs unchanged on three interchangeable backends — a transparent reference implementation, a fast compiled C++ kernel, and a GPU Majorana kernel.

---

Status

qufold is research software under active development (alpha). The CFU pipeline is implemented end-to-end and validated; the remaining methods and the fast backends are scaffolded behind the same fixed contracts and land incrementally. The table below is an honest map of what runs today.

Methods × backends

Method	openfermion (reference)	cpu (C++ kernel)	gpu (Majorana)
cfu — Closed-Form Unitary	✅ implemented	🚧 scaffolded	🚧 scaffolded
ducc — Double Unitary CC	🚧 scaffolded	🚧 scaffolded	🚧 scaffolded
pucc — Projective UCC	🚧 scaffolded	🚧 scaffolded	🚧 scaffolded
ccsd_downfold — non-unitary CCSD	🚧 scaffolded	🚧 scaffolded	🚧 scaffolded
pqe — Projective Quantum Eigensolver	🚧 scaffolded	🚧 scaffolded	🚧 scaffolded

Legend: ✅ implemented = runs and is validated; 🚧 scaffolded = the contract, registry entry, and keywords exist, but the implementation is not yet wired in. Requesting a scaffolded backend fails over gracefully to the openfermion reference backend (with a warning) rather than crashing; requesting a scaffolded method raises a clear "not yet implemented" error.

Why is the reference backend the one that is "done"? It is the auditable truth: each primitive maps one-to-one to the math via OpenFermion/NumPy. The cpu (pybind11 fermionic kernel, ~7–10× faster on normal-ordered commutators/products) and gpu (CuPy bit-packed Majorana kernel — operators stored as 128-bit bitmasks, products are XOR + popcount) backends are validated against it before they are marked implemented.

Validation snapshot

• CFU on H4 recovers ~87 % of the CASSCF→FCI correlation gap on the reference backend, with downfold → FCI reproducing PySCF CASCI to ~2e-8 Ha on the K=0 (no-transform) checkpoint — i.e. the downfold itself is exact and the recovery comes from the unitary transforms.

---

Install

qufold works out of the box with only the reference backend's dependencies (NumPy, SciPy, OpenFermion, PySCF):

pip install qufold                 # reference (openfermion) backend
pip install "qufold[cpu]"          # + compile the bundled C++ fermionic kernel
pip install "qufold[gpu]"          # + GPU Majorana backend (needs CuPy/CUDA)
pip install "qufold[pqe]"          # + QForte bridge for the PQE methods
pip install "qufold[dev]"          # + tests / docs / build tooling

From source (development):

git clone https://github.com/mjangrou/qufold
cd qufold
pip install -e ".[dev]"

The fast cpu backend ships its compiled kernel as package data (qufold/_vendor/*.so); public wheels carry a prebuilt kernel so most users never compile anything (see Distribution model below).

---

Quickstart

# 1. activate an environment with the deps (see Install)
# 2. run the bundled H4 CFU example
qufold examples/cfu/h4_cfu.in
# 3. read the result block printed to stdout (reference energy, downfolded
#    energy, recovery in mHa, generator count, trajectory)
# 4. or drive it programmatically:
python -c "import qufold; print(qufold.run_calculation('examples/cfu/h4_cfu.in').energy)"

The input file ($molecule / $rem)

A calculation is fully specified by one human-friendly, Q-Chem/Psi4-flavoured keyword file: a $molecule block (geometry + charge/multiplicity) and a $rem ("remarks") keyword block. Lines are keyword value; # starts a comment; sections are $section … $end.

$molecule
0 1                          # charge  spin-multiplicity
H   0.0000  0.0000  0.0000
H   0.0000  0.0000  0.7400
H   0.0000  0.0000  2.0000
H   0.0000  0.0000  2.7400
$end

$rem
method        cfu            # cfu | ducc | pucc | ccsd_downfold | pqe
backend       openfermion    # openfermion | cpu | gpu
basis         sto-3g
active_space  full           # avas | manual | full
orbital_opt   true           # CASSCF-optimize before downfolding
n_generators  40             # CFU: number of greedy-ADAPT steps K
generator_pool ccsd_screened # screened doubles (singles excluded by design)
pool_tol      1e-3
solve_fci     true           # exactly diagonalize the downfolded Hamiltonian
$end

Every keyword — its type, default, allowed values, and a one-paragraph help string — lives in qufold/input/keywords.py, the single source of truth from which the keyword reference (docs/keywords.md) is generated, so the manual can never drift from the code.

---

How it fits together

input file  ─►  Calculation  ─►  Problem (SCF / active space / CASSCF-OO)
            ─►  Method.run(backend)  ─►  Result  ─►  analysis (FCI, λ)  ─►  output

• qufold/input/ — parser + keyword registry (the manual-in-code).
• qufold/core/ — Problem builder (hamiltonian.py), CC amplitudes and the screened-doubles generator pool (amplitudes.py), FCI / LCU-1-norm analysis (analysis.py).
• qufold/methods/ — thin orchestration over backend primitives. Each method subclasses Method and sets name=<keyword>. CFU is the worked template (cfu.py).
• qufold/backends/ — the operator algebra. base.py is the contract; openfermion_backend.py is the reference impl; registry.py selects with graceful failover.
• qufold/downfold/ — the backend-independent Majorana-space projection (projector.downfold_to_active(H, problem)), exact for any body rank.
• qufold/drivers/driver.py — top-level orchestration (the CLI calls this; also the programmatic qufold.run_calculation).

Operators cross every API boundary as a plain dict FermionOp = { ((p,1),(q,0),…): complex } (OpenFermion term convention, 1 = creation, 0 = annihilation), so methods stay backend-agnostic even when a backend uses a faster internal representation (e.g. Majorana bitmasks).

---

Documentation

• docs/keywords.md — the full keyword reference (generated from qufold/input/keywords.py).
• docs/methods/ — the theory and contract for each method (CFU, DUCC, PUCC, CCSD downfolding, PQE).
• docs/tutorials/ — worked end-to-end examples.
• examples/ — ready-to-run input files (examples/cfu/h4_cfu.in, …).
• CONTRIBUTING.md — how to add a method, a keyword, or a backend.

---

Distribution model

qufold is developed in a private repository and released publicly as source-hidden binary wheels on PyPI for tagged versions. Every module — including the package __init__ files — is Cython-compiled to a platform .so and the original .py is excluded from the wheel, so the published package contains no readable Python source and no .pyc bytecode, only symbol-stripped machine code plus the compiled C++ kernel. pip install qufold then gives users the full functionality (and the fast cpu backend) without a compiler and without the source.

This is the strongest practical obfuscation for a pip package: recovering the original Python from a Cython .so is impractical (it is compiled C, not bytecode). It is not cryptographic secrecy — any runnable executable can in principle be reverse-engineered — but it defeats casual reading and decompilation.

The .github/workflows/wheels.yml pipeline builds these compiled wheels with cibuildwheel across Linux/macOS/Windows × CPython 3.10–3.13 on every vX.Y.Z tag and publishes them to PyPI via Trusted Publishing (no API token). Wheels only — no source distribution (sdist) is ever published, since an sdist would ship the source. (Trade-off: users on a platform/Python without a matching wheel cannot install; the wheel matrix is kept broad to cover common setups.) See setup.py for the build and .github/workflows/wheels.yml for the one-time PyPI Trusted-Publisher setup.

---

Citation

If qufold is useful in your work, please cite it (a CITATION.cff will ship with the first tagged release). Authors: Mohammad Reza Jangrouei, Artur F. Izmaylov.

License

MIT — see LICENSE.