A practical F# library for symbolic operator algebra on Fock space — fermionic and bosonic — with fermion-to-qubit encodings, qubit tapering, Trotterization, and circuit export.
The complete pipeline: molecular integrals → encoding → tapering → Trotter decomposition → OpenQASM / Q# / JSON circuit output.
📖 The Book: From Molecules to Quantum Circuits — 23-chapter guide with interactive labs, computed results (H₂ dissociation curve, H₂O bond angle scan), and companion code.
🍳 API Cookbook: 15 progressive chapters covering every type and function.
If you're exploring quantum chemistry on qubits, you usually hit this question quickly: how do I map fermions to Pauli operators? And increasingly: what about phonons and other bosonic modes?
FockMap gives you one small, consistent API for the complete quantum simulation pipeline:
- Encode fermionic or bosonic operators as Pauli strings (5 fermionic + 3 bosonic encodings)
- Taper qubits via Z₂ symmetry detection and Clifford rotation (diagonal + general)
- Trotterize a Pauli Hamiltonian into gate sequences (first and second order)
- Export circuits as OpenQASM 3.0, Q#, or JSON for any quantum platform
- Define custom encodings with a few lines of F#
- Compare encodings side-by-side — same eigenvalues, different circuit costs
| Feature | OpenFermion | Qiskit Nature | PennyLane | FockMap |
|---|---|---|---|---|
| Define a new encoding | ~200 lines Python | Not supported | Not supported | 3–5 lines F# |
| Tree → encoding pipeline | ❌ | ❌ | ❌ | ✅ |
| Qubit tapering (Z₂ + Clifford) | ❌ | Partial | ❌ | ✅ |
| Trotter decomposition | ❌ | ✅ | ✅ | ✅ (1st + 2nd order) |
| Circuit export (QASM, Q#, JSON) | ❌ | QASM only | ❌ | ✅ (all three) |
| Hamiltonian skeleton (PES scans) | ❌ | ❌ | ❌ | ✅ |
| Measurement grouping + shot estimates | ❌ | ✅ | ✅ | ✅ |
| QPE resource estimation | ❌ | ❌ | ❌ | ✅ |
| Bosonic operator algebra (CCR) | ❌ | ❌ | ✅ | ✅ |
| Bosonic-to-qubit encodings | ❌ | ❌ | ❌ | ✅ (Unary, Binary, Gray) |
| Mixed fermion–boson normal ordering | ❌ | ❌ | ❌ | ✅ |
| Type-safe operator algebra | ❌ | ❌ | ❌ | ✅ |
| Pure functional, zero mutation | ❌ | ❌ | ❌ | ✅ |
| Runtime dependencies | NumPy, SciPy | Many | NumPy, autograd, … | None |
Internally, the library uses exact symbolic Pauli algebra (not floating-point matrix multiplication), so encoded operator manipulation stays fast and predictable.
| Encoding | Worst-Case Pauli Weight | Framework | Function |
|---|---|---|---|
| Jordan-Wigner | Index-set | jordanWignerTerms |
|
| Bravyi-Kitaev | Index-set | bravyiKitaevTerms |
|
| Parity | Index-set | parityTerms |
|
| Balanced Binary Tree | Path-based | balancedBinaryTreeTerms |
|
| Balanced Ternary Tree | Path-based | ternaryTreeTerms |
|
| Vlasov (Complete Ternary) | Path-based | vlasovTreeTerms |
| Encoding | Qubits / Mode | Max Weight | Function |
|---|---|---|---|
| Unary (one-hot) | 2 | unaryBosonTerms |
|
| Standard Binary | binaryBosonTerms |
||
| Gray Code | grayCodeBosonTerms |
Bosonic modes are truncated to BosonicEncoderFn signature and return PauliRegisterSequence, just like their fermionic counterparts.
All encodings return the same output type (PauliRegisterSequence), so you can swap schemes without rewriting downstream code.
dotnet add package FockMapgit clone https://github.com/johnazariah/encodings.git
cd encodings
dotnet build
dotnet testThis repository includes a full dev container configuration with .NET 10 (GA), F#, Python, LaTeX, and all required tooling pre-installed. To use it:
- Install Docker and VS Code with the Dev Containers extension
- Clone the repository and open it in VS Code
- When prompted, click "Reopen in Container" (or run
Dev Containers: Reopen in Containerfrom the command palette) - The container builds, restores packages, compiles the project, and runs tests automatically
Everything is pre-configured, so you can start coding immediately.
open System.Numerics
open Encodings
// 1. Define molecular integrals (H₂ in STO-3G)
let integrals = Map [
("0,0", Complex(-1.2563, 0.0)); ("1,1", Complex(-1.2563, 0.0))
("2,2", Complex(-0.4719, 0.0)); ("3,3", Complex(-0.4719, 0.0))
// ... (two-body integrals)
]
let factory key = integrals |> Map.tryFind key
// 2. Encode → 15-term Pauli Hamiltonian
let ham = computeHamiltonianWith jordanWignerTerms factory 4u
// 3. Taper → remove symmetry-redundant qubits
let tapered = taper defaultTaperingOptions ham
// 4 → 2 qubits
// 4. Trotterize → gate sequence
let step = firstOrderTrotter 0.1 tapered.Hamiltonian
let gates = decomposeTrotterStep step
// 5. Export → OpenQASM 3.0
let qasm = toOpenQasm defaultOpenQasmOptions tapered.TaperedQubitCount gates
// Ready to run on IBM Quantum, IonQ, Rigetti, Amazon Braket
// Also available: Q# and JSON export
let qs = toQSharp defaultQSharpOptions tapered.TaperedQubitCount gates
let json = toCircuitJson tapered.TaperedQubitCount Map.empty gates- The Book: From Molecules to Quantum Circuits — 23 chapters, from molecular integrals to quantum circuits
- Interactive Labs: 10 F# scripts — run with
dotnet fsi - API Cookbook: 15-chapter tutorial — every type and function
- Architecture: How the library works
- API Reference: All types and functions
- Site: johnazariah.github.io/encodings — API cookbook, architecture guide, cross-platform notes
- Book: johnazariah.github.io/encodings-book — full narrative with labs and companion code
FockMap implements the complete quantum simulation pipeline:
- Encoding — Map fermionic/bosonic ladder operators to Pauli strings via index-set schemes (JW, BK, Parity) or path-based tree encodings (binary, ternary, Vlasov, custom)
- Hamiltonian Assembly — Combine encoded operators with molecular integrals to build a qubit Hamiltonian (
PauliRegisterSequence) - Tapering — Detect Z₂ symmetries (diagonal or general via Clifford rotation), fix sectors, and remove redundant qubits
- Trotterization — Decompose the Hamiltonian into Pauli rotations (first or second order), then into elementary gates (H, S, CNOT, Rz)
- Circuit Output — Export gate sequences as OpenQASM 3.0, Q#, or JSON
- Analysis — Measurement grouping, shot estimation, QPE resource estimation, cost comparison across encodings
Everything is symbolic and exact — no floating-point matrix multiplication, no approximation until the Trotter step.
For the full API walkthrough, see the Cookbook (18 chapters) or the Architecture guide.
dotnet test # all tests
dotnet test --logger "console;verbosity=detailed" # verbose
dotnet test --collect:"XPlat Code Coverage" # with coverageThe test suite covers encoding correctness, Pauli algebra laws, tapering, Trotterization, circuit output, and cross-encoding consistency. See the Test Register for a plain-English catalogue of all 700+ automated tests.
This library runs on Windows, macOS, and Linux via .NET 10, Microsoft's open-source, cross-platform runtime. It is written in F#, a functional-first language that is fully open-source under the F# Software Foundation and the .NET Foundation.
No platform-specific code and no native dependencies beyond the .NET SDK.
If you use this library in your research, please cite:
@software{fockmap2026,
author = {Azariah, John},
title = {FockMap: A Composable Framework for Quantum Operator Encodings},
year = {2026},
url = {https://github.com/johnazariah/encodings}
}A machine-readable citation file is available at CITATION.cff.
Contributions are welcome! See CONTRIBUTING.md for:
- How to report bugs and propose features
- Development setup instructions
- Coding conventions (pure functions, immutable data, XML docs)
- Pull request process
This library is dedicated to Dr. Guang Hao Low for his guidance and inspiration in the field of quantum algorithms.