FockMap 0.1.0

FockMap

A composable functional framework for encoding quantum operators on Fock space as qubit Pauli operators.

Map creation and annihilation operators to Pauli strings — using algebraic data types, pure functions, and zero dependencies.

The Problem

Quantum computers operate on qubits, but quantum chemistry deals with electrons (fermions). Fermions obey anti-commutation relations that qubits don't naturally respect:

$${a_i^\dagger, a_j} = \delta_{ij} I, \quad {a_i^\dagger, a_j^\dagger} = 0, \quad {a_i, a_j} = 0$$

Fermion-to-qubit encodings bridge this gap by mapping fermionic ladder operators ($a_j^\dagger$, $a_j$) to multi-qubit Pauli operators ($X$, $Y$, $Z$, $I$) while preserving the canonical anti-commutation relations (CAR). Different encodings make different tradeoffs between Pauli weight (how many qubits each operator touches) and locality.

This library provides a unified framework for five encoding schemes, plus the infrastructure to define custom encodings in a few lines of code.

Why FockMap?

FockMap works entirely with symbolic Pauli algebra — the Pauli group is a finite group, so multiplication is exact. There are no floating-point matrices, no numerical linear algebra, and no approximations. This means you can compute parity operators for $n = 100$ modes in seconds, not hours.

Available Encodings

All five encodings produce the same output type (PauliRegisterSequence), so encoded Hamiltonians are interoperable regardless of which encoding was used. All five have been verified to produce identical eigenspectra for the H₂ molecule to machine precision ($|\Delta\lambda| = 4.44 \times 10^{-16}$).

Installation

NuGet (recommended)

dotnet add package FockMap

From source

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

Dev Container (recommended for contributors)

This repository includes a full dev container configuration with .NET 10, 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 all 303 tests automatically

Everything is pre-configured — Ionide (F# IDE), Copilot, coverage tools, fsdocs, gh CLI, and dotnet-repl.

Quick Start

open Encodings

// Encode the creation operator a†₂ on 4 modes using Jordan-Wigner
let pauliJW = jordanWignerTerms Raise 2u 4u
// → ½(ZZXI) − ½i(ZZYI)

// Same operator under Bravyi-Kitaev (O(log n) weight)
let pauliBK = bravyiKitaevTerms Raise 2u 4u

// Or Parity encoding
let pauliP = parityTerms Raise 2u 4u

// Tree-based encodings
let pauliBBT = balancedBinaryTreeTerms Raise 2u 4u
let pauliBTT = ternaryTreeTerms Raise 2u 4u

Encode a Full Hamiltonian

open Encodings

// One-electron (h) and two-electron (g) integrals for H₂ in STO-3G basis
let h = Array2D.init 4 4 (fun i j -> (* your integrals *) 0.0)
let g = Array4D.init 4 4 4 4 (fun i j k l -> (* your integrals *) 0.0)

// Encode with any scheme
let hamiltonian = computeHamiltonianWith jordanWignerTerms h g 4u

Define a Custom Encoding in 5 Lines

open Encodings

// Build a custom tree and derive an encoding from it
let myTree = balancedBinaryTree 8
let myScheme = treeEncodingScheme myTree
let myEncode op j n = encodeOperator myScheme op j n

Architecture

FockMap provides two complementary encoding frameworks, each suited to different encoding strategies:

1. Index-Set Framework (Seeley-Richard-Love)

Encodings are defined by three functions over index sets:

• Update set $U(j)$: qubits whose occupation parity changes when mode $j$ is toggled
• Parity set $P(j)$: qubits that store the parity of modes $< j$
• Occupation set $F(j)$: qubits that encode the occupation of mode $j$

These sets plug into the Majorana operators $c_j$ and $d_j$:

$$c_j = X_{U(j) \cup {j}} \cdot Z_{P(j)}, \qquad d_j = Y_j \cdot X_{U(j)} \cdot Z_{(P(j) \oplus F(j)) \setminus {j}}$$

This framework implements Jordan-Wigner, Bravyi-Kitaev, and Parity.

2. Path-Based Framework (Jiang et al.)

Encodings are defined by tree structures where:

• Each leaf corresponds to a fermionic mode
• Each edge carries a Pauli label ($X$, $Y$, or $Z$)
• Root-to-leaf paths determine Majorana operator strings

This framework implements balanced binary and balanced ternary tree encodings, and supports arbitrary custom trees — any rooted tree you can define produces a valid encoding.

Type System

The library's operator algebra is built on three generic types:

These compose with:

• LadderOperatorUnit — Raise j ($a_j^\dagger$) or Lower j ($a_j$)
• PauliRegister — Multi-qubit Pauli string with phase (e.g., $iXZYI$)
• PauliRegisterSequence — Linear combination of Pauli strings

Source Modules

Examples

Runnable F# scripts in the examples/ directory:

Run any example with:

dotnet fsi examples/H2_Encoding.fsx

Documentation

Full documentation is available at johnazariah.github.io/encodings.

Theory

• Why Encodings? — The problem encodings solve
• Second Quantization — Fock space, creation/annihilation operators
• Pauli Algebra — Pauli matrices and multi-qubit strings
• Jordan-Wigner — The classic encoding, derived step by step
• Beyond Jordan-Wigner — BK, trees, and $O(\log n)$ scaling
• Bosonic Preview — Future extensions to bosonic modes

Labs (literate F# scripts)

• Your First Encoding — Encode an operator in 5 minutes
• H₂ Molecule — Full molecular Hamiltonian walkthrough
• Compare Encodings — Side-by-side weight analysis
• Custom Encoding — Define your own scheme
• Custom Tree — Build tree-based encodings
• Scaling Analysis — Pauli weight scaling with system size

Guides

• Architecture — Two-framework design explained
• Type System — The C/P/S algebra in depth
• Cross-Platform — Running on Windows, macOS, and Linux

Testing

# Run all 303 tests
dotnet test

# With detailed output
dotnet test --logger "console;verbosity=detailed"

# With coverage
dotnet test --collect:"XPlat Code Coverage"

The test suite includes:

• Unit tests for every encoding scheme and every algebraic operation
• Property-based tests via FsCheck for Pauli algebra laws
• Cross-encoding verification: all 5 encodings produce identical eigenspectra for H₂
• CAR verification: canonical anti-commutation relations checked symbolically

Current coverage: 78% line / 66% branch across 303 tests.

Cross-Platform

This library runs on Windows, macOS, and Linux via .NET 10 (LTS), 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. No native dependencies. No runtime downloads 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.