Metadata-Version: 2.4
Name: monoprop
Version: 0.8.0
Summary: Majorana Propagation.
Author-Email: Algorithmiq Development Team <aurora@algorithmiq.fi>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/Algorithmiq/monoprop
Project-URL: Bug Tracker, https://github.com/Algorithmiq/monoprop/issues
Project-URL: Discussions, https://github.com/Algorithmiq/monoprop/discussions
Project-URL: Changelog, https://github.com/Algorithmiq/monoprop/releases
Requires-Python: <3.15,>=3.11
Requires-Dist: numpy>=2
Requires-Dist: msgpack>=1.0.0
Provides-Extra: mpi
Requires-Dist: mpi4py>=4.1.0; extra == "mpi"
Provides-Extra: qiskit
Requires-Dist: qiskit>=2.0.0; extra == "qiskit"
Description-Content-Type: text/markdown

# monoprop
> because your operators deserve to propagate at escape velocity

[![Documentation](https://github.com/Algorithmiq/monoprop/actions/workflows/docpages.yml/badge.svg)](https://docs.algorithmiq.fi/monoprop)
[![Test monoprop](https://github.com/Algorithmiq/monoprop/actions/workflows/test.yml/badge.svg)](https://github.com/Algorithmiq/monoprop/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/Algorithmiq/monoprop/graph/badge.svg?token=1GgmPnNUxk)](https://codecov.io/gh/Algorithmiq/monoprop)

`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](https://semver.org/). 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](https://github.com/Algorithmiq/monoprop/issues/new).

## Benchmarks

Check out the comparison of `monoprop` against other open-source Pauli propagation engines in [benches/third_party]!
![Runtime Benchmark](benches/third_party/pauli_prop/runtime.png)
![Memory Benchmark](benches/third_party/pauli_prop/memory.png)

📖 **Full documentation:** <https://docs.algorithmiq.fi/monoprop>

## Installation

```bash
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:

```python
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:

```python
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](https://docs.algorithmiq.fi/monoprop/getting-started.html)
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](https://github.com/astral-sh/uv)):

```bash
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):

```bash
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](https://docs.algorithmiq.fi/monoprop/docs/building).

## Running the tests

```bash
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](https://docs.algorithmiq.fi/monoprop/docs/building#running-the-tests)
for the with/without-MPI details and the rank matrix.

## Development environment

The repository ships a [DevContainer](https://containers.dev/) 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](https://docs.docker.com/get-docker/) installation
   (Docker Desktop on macOS/Windows, Docker Engine on Linux).
2. [Visual Studio Code](https://code.visualstudio.com/) with the
   [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers).

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):

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

Without a DevContainer, install the prerequisites from the
[building guide](https://docs.algorithmiq.fi/monoprop/docs/building#prerequisites)
by hand.

## Contributing

Please read [CONTRIBUTING.md](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](mailto:cla@algorithmiq.fi) to arrange a Corporate CLA.

## Documentation

The documentation is built with [Fumadocs](https://fumadocs.dev/) and hosted at
<https://docs.algorithmiq.fi/monoprop>. The Python API reference is generated from
docstrings ([griffe](https://mkdocstrings.github.io/griffe/)) and the tutorials are
executed from the notebooks in `docs/notebooks/`.  Building the documentation locally requires [npm](https://docs.npmjs.com/), the Node.js package manager. Once that is available, you can run:

```bash
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:

```bibtex
@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](LICENSE).
