monoprop

because your operators deserve to propagate at escape velocity

monoprop is a high-performance C++ library with Python bindings for Majorana and Pauli propagation — a backend for classically simulating and variationally optimising quantum circuits. Rather than storing the full quantum state, it expands an operator in the Majorana basis and propagates it through a circuit, truncating terms that contribute little. It scales to large systems by partitioning the operator across cores and across nodes with MPI.

Warning

This package is under active development. This project follows Semantic Versioning. While in 0.x.y, breaking changes may occur in minor releases. Pin your version if you depend on it. If you have feedback, please open an issue.

Benchmarks

Check out the comparison of monoprop against other open-source Pauli propagation engines in [benches/third_party]!

📖 Full documentation: https://docs.algorithmiq.fi/monoprop

Installation

pip install monoprop      # or: uv add monoprop

The prebuilt PyPI wheels are single-process (built without MPI). For multi-rank runs, or to build the C++ library and executables, build from source (see below).

Quick example

Back-propagate a Majorana observable through a one-gate circuit:

from monoprop import MajoranaPropagator, ExpGate, Circuit, MajoranaOperator

# Observable m_0 m_1 m_2 m_4, evolved under one Majorana rotation exp(-i θ/2 · M_γ),
# generated by M_γ = i*m_4 m_5.
observable = MajoranaOperator({(0, 1, 2, 4): 1.0}, num_modes=8)
gate = ExpGate(MajoranaOperator({(4, 5): 1j}, num_modes=8))  # Hermitian generator: weight-2 => imaginary coeff
circuit = Circuit(gates=[gate], parameters=[0.5])  # one angle value per gate

mp = MajoranaPropagator.from_circuit(circuit, observable, cutoff=16)
print(mp.evolved_operator())  # the gate splits the monomial into two terms

Qubit (Pauli) operators are simulated with PauliPropagator. Here we back-propagate Z ⊗ Z through one exp(-i θ/2 · X_0) rotation:

from monoprop import PauliPropagator, ExpGate, Circuit, PauliOperator, Pauli

observable = PauliOperator({"ZZ": 1.0}, num_qubits=2)  # num_qubits lives on the observable
gate = ExpGate(PauliOperator({Pauli("X", 0): 1.0}, num_qubits=2))  # exp(-i θ/2 · X_0)
circuit = Circuit(gates=[gate], parameters=[0.5])  # one angle value per gate

mp = PauliPropagator.from_circuit(circuit, observable, cutoff=16)  # construct + evolve
print(mp.evolved_operator())  # the gate splits Z ⊗ Z into two terms

See the getting-started guide for fermionic operators and more.

Building from source

A from-source build gives you the editable Python bindings and the standalone C++ library and executables. MPI is off by default in every build path; enable it explicitly.

Python bindings (via uv):

uv sync --all-extras -v
# with MPI:
uv sync --all-extras -v --config-settings=cmake.define.monoprop_ENABLE_MPI=ON

C++ library and executables (via CMake presets — the same ones CI configures with):

cmake --preset release-gcc        # release-gcc-mpi to enable MPI
cmake --build --preset release-gcc

Full instructions — prerequisites, MPI options, and running the example executable — are in the building guide.

Running the tests

uv run python -m pytest -m "not mpi"   # Python tests (serial)
just test-py-mpi                       # Python tests under MPI
ctest --preset release-gcc             # C++ unit tests (release-gcc-mpi for MPI)
just test-cpp-wide                     # C++ unit tests with a 64-bit TermIndex

See the building guide for the with/without-MPI details and the rank matrix.

Development environment

The repository ships a DevContainer that installs every dependency (including the MPI toolchain and pre-commit hooks) and configures the editor. To use it you need:

1. A working Docker installation (Docker Desktop on macOS/Windows, Docker Engine on Linux).
2. Visual Studio Code with the Dev Containers extension.

Clone the repository and open the folder in VS Code; it will build the container and run the setup automatically (this takes a few minutes the first time):

git clone https://github.com/Algorithmiq/monoprop.git

Without a DevContainer, install the prerequisites from the building guide by hand.

Contributing

Please read CONTRIBUTING.md before opening a pull request. All contributions require accepting the Individual CLA through CLA Assistant. If you are contributing on behalf of your employer, contact cla@algorithmiq.fi to arrange a Corporate CLA.

Documentation

The documentation is built with Fumadocs and hosted at https://docs.algorithmiq.fi/monoprop. The Python API reference is generated from docstrings (griffe) and the tutorials are executed from the notebooks in docs/notebooks/. Building the documentation locally requires npm, the Node.js package manager. Once that is available, you can run:

just build-docs   # output: docs/out/
just serve-docs   # live-reloading dev server

Keeping documentation up to date

Any PR that changes behavior, public APIs, build/test commands, or repository paths must update the relevant docs in the same change:

1. AGENTS.md for agent/developer workflow instructions.
2. README.md for top-level usage and contributor guidance.
3. docs/ pages for user-facing and in-depth technical documentation.

Citation

If you use monoprop in your research, please cite:

@ARTICLE{Miller2025-aj,
  title         = "{Simulation of Fermionic circuits using Majorana Propagation}",
  author        = "Miller, Aaron and Holmes, Zoë and Salehi, Özlem and
                   Chakraborty, Rahul and Nykänen, Anton and Zimborás, Zoltán
                   and Glos, Adam and García-Pérez, Guillermo",
  journal       = "arXiv [quant-ph]",
  year          =  2025,
  eprint        = "2503.18939",
  archivePrefix = "arXiv",
  primaryClass  = "quant-ph",
  url           = "https://arxiv.org/abs/2503.18939"
}

License

monoprop is released under the Apache License 2.0.