FockMap 0.8.0

FockMap

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 — 22-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.

Why FockMap

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

Internally, the library uses exact symbolic Pauli algebra (not floating-point matrix multiplication), so encoded operator manipulation stays fast and predictable.

Available Encodings

Fermionic Encodings

Bosonic Encodings

Bosonic modes are truncated to $d$ occupation levels. All bosonic encodings share the 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.

Installation

NuGet (recommended)

dotnet add package FockMap

From source

git clone https://github.com/johnazariah/encodings.git
cd encodings
dotnet build
dotnet test

Dev Container (for contributors)

This repository includes a full dev container configuration with .NET 10 (GA), F#, Python, LaTeX, and all required tooling pre-installed. To use it:

1. Install Docker and VS Code with the Dev Containers extension
2. Clone the repository and open it in VS Code
3. When prompted, click "Reopen in Container" (or run Dev Containers: Reopen in Container from the command palette)
4. The container builds, restores packages, compiles the project, and runs tests automatically

Everything is pre-configured, so you can start coding immediately.

Quick Start

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

Where to Start

• The Book: From Molecules to Quantum Circuits — 22 chapters, from molecular integrals to quantum circuits
• Interactive Labs: 9 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

Documentation

• Site: johnazariah.github.io/encodings — API cookbook, architecture guide, cross-platform notes
• Book: github.com/johnazariah/encodings-book — full narrative with labs and companion code

How it Works

FockMap implements the complete quantum simulation pipeline:

1. 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)
2. Hamiltonian Assembly — Combine encoded operators with molecular integrals to build a qubit Hamiltonian (PauliRegisterSequence)
3. Tapering — Detect Z₂ symmetries (diagonal or general via Clifford rotation), fix sectors, and remove redundant qubits
4. Trotterization — Decompose the Hamiltonian into Pauli rotations (first or second order), then into elementary gates (H, S, CNOT, Rz)
5. Circuit Output — Export gate sequences as OpenQASM 3.0, Q#, or JSON
6. 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.

Testing

dotnet test                                          # all tests
dotnet test --logger "console;verbosity=detailed"    # verbose
dotnet test --collect:"XPlat Code Coverage"          # with coverage

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

Cross-Platform

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.

Citation

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.

Contributing

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

License

MIT

Acknowledgements

This library is dedicated to Dr. Guang Hao Low for his guidance and inspiration in the field of quantum algorithms.