FockMap 0.3.1

FockMap

A practical F# library for symbolic operator algebra on Fock space and fermion-to-qubit encodings.

Learn by doing: pick an encoding, map operators to Pauli strings, and compare results.

Why FockMap

If you're exploring quantum chemistry on qubits, you usually hit this question quickly: how do I map fermions to Pauli operators?

FockMap gives you one small, consistent API for that. You can:

• use built-in encodings (Jordan-Wigner, Bravyi-Kitaev, Parity, tree-based)
• compare them side-by-side
• define your own encoding with a few lines of F#

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

Available Encodings

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 8 (LTS), 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 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

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

Where to Start

• New to this topic? Start with Why Encodings?
• Want a progressive walkthrough? Try the Cookbook — 13 chapters covering every type and function
• Want a full worked example? Go to From Molecules to Qubits
• Prefer hands-on? Try Your First Encoding
• Need API details? Browse All types and functions

Documentation

• Site: johnazariah.github.io/encodings
• Cookbook: 13-chapter progressive tutorial — covers every type and function with runnable examples
• Tutorial: From Molecules to Qubits — end-to-end worked example
• Theory: Why Encodings? — mathematical foundations
• Labs: Your First Encoding — hands-on F# scripts
• Architecture: Architecture guide — module and pipeline overview
• API Reference: All types and functions — generated from source XML docs

Build docs locally (with logo/icon + Mermaid/MathJax runtime injection):

./scripts/build-docs.sh

How it Works (briefly)

FockMap exposes two fermionic encoding styles:

• Index-set encodings (Jordan-Wigner, Bravyi-Kitaev, Parity)
• Tree/path encodings (balanced binary and ternary trees, plus custom trees)

It also supports bosonic ladder-operator normal ordering via canonical commutation relations (CCR), alongside the fermionic CAR workflow.

For models with both statistics, use sector-tagged operators (fermion, boson) and constructMixedNormalOrdered to canonicalize mixed expressions.

For the full derivations and internals, jump to the Cookbook or the Architecture guide.

Examples

Runnable F# scripts in the examples/ directory:

Run any example with:

dotnet fsi examples/H2_Encoding.fsx

Testing

# Run all tests
dotnet test

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

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

The test suite covers encoding behavior, Pauli algebra laws, and cross-encoding consistency checks.

Coverage and test counts are tracked in CI.

Cross-Platform

This library runs on Windows, macOS, and Linux via .NET 8 (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 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.