Parallelism and distribution

monoprop scales the same way on one node and on many: it partitions the operator into disjoint pieces and applies each gate to every partition in lock-step, exchanging only the terms that cross a partition boundary. Two axes compose:

• Across cores (default): one single-threaded partition per physical core, within a single process. This is on automatically, and can be configured with environment variables (see below).
• Across nodes (opt-in): MPI ranks, each of which partitions further across its own cores. Distributing the operator and its graph across ranks lets you simulate and variationally optimise systems larger than one node's memory.

Operator partitioning (single node)Copy Anchor Link

By default monoprop splits the operator into one partition per physical core and gives each partition a pinned worker thread that runs it serially. Each partition keeps its own small, cache-resident term index; a gate is applied to all partitions at once, synchronised by a lightweight barrier, and anticommuting terms whose partner lives in another partition are resolved through a per-gate exchange.

A partition addresses its own terms with a 32-bit index, so one partition holds at most 2^32 (about 4.3 billion) terms. That is a few hundred gigabytes of resident operator in a single partition, so the ceiling is reached by running too few partitions rather than by problem size, and it is not a build option. An append that would cross it is refused before it happens — a RuntimeError naming the ceiling and the term counts, with the operator left as it was, rather than a silent wrap. The fix is more partitions or more MPI ranks — both divide the terms per partition — or a larger lower_atol (see Truncation and cutoffs).

Runtime environment variablesCopy Anchor Link

Which MPI rank owns a term is set separately; see Rank routing.

# Run 8 partitions instead of one-per-core:
export monoprop_NUM_THREADS=8

Placement reportCopy Anchor Link

Building a propagator writes one COMMPLACE line per rank to stderr, naming the CPUs the launcher gave that rank and whether co-located ranks got disjoint masks. It is report-only — no placement decision reads it — and there is no knob: redirect stderr to drop it.

COMMPLACE rank=0 node_rank=0 node_size=2 masks=private cpus=64 node_cpus=128 cpu_list=0-63

masks is private when the co-located ranks' affinity masks are pairwise disjoint, shared when two ranks can land on the same CPU, alone when this rank is the only one on its host (which is not evidence a multi-rank launcher bound correctly), and unknown when a mask did not fit the exchanged window.

Pinning each partition to a core is not configurable: leaving placement to the launcher measured propagate[hubbard] 2.90x slower, so the disabled arm is gone.

MPI distribution (multi-node)Copy Anchor Link

MPI partitions the operator and graph across ranks, composing with per-rank partitioning into one flat world of R × S partitions (R ranks, S partitions each). MPI communication is serialised through each rank's first partition, bracketed by the intra-rank barriers.

Rank routingCopy Anchor Link

A gate with generator $G$ maps $M \mapsto M \oplus G$. Ranks are assigned by a GF(2)-linear hash $h(M) = \bigoplus_{i \in \mathrm{supp}(M)} v_i$, keeping its low $d = \log_2 R$ bits $h_d$, so

Every query a rank sends for $G$ therefore goes to the single peer $r \oplus h_d(G)$, whatever $R$ is. XOR is an involution, so both ends derive the pairing without communicating, and the exchange runs point-to-point. Partitions within a rank keep the splitmix hash $q$, because shared-memory fanout is free:

• $R$ must be a power of two with $\log_2 R \le \min(2N, 64)$. Otherwise MajoranaPropagator and PauliPropagator raise at construction; use monoprop_ROUTING=splitmix for other rank counts. $R = 1$ is the dense case.
• The basis is drawn full rank, so ranks are balanced whenever the circuit's shifts $h_d(G)$ span all $d$ bits. If they span fewer, some ranks stay empty, and a COMMROUTE line on stderr says so.

A related scheme sums $k$-bit blocks modulo the rank count (Broers et al., 2026). That sum is not linear over XOR, so a gate's queries still reach several ranks rather than one.

Both variables, and the partition count, must match on every rank. A mismatch would deadlock the exchange, so it is checked collectively at startup and raised.

Single-node (MPI.COMM_SELF)Copy Anchor Link

from mpi4py import MPI
sim = MajoranaPropagator(..., comm=MPI.COMM_SELF)

Multi-node (MPI.COMM_WORLD)Copy Anchor Link

Replace the communicator and launch with mpiexec:

from mpi4py import MPI
sim = MajoranaPropagator(..., comm=MPI.COMM_WORLD)

mpiexec -n 8 uv run python your_script.py

A pure-MPI rank keeps its whole share in one partition unless monoprop_NUM_THREADS is set, so an MPI user who has not asked for threads gets one partition per rank.

Enabling MPICopy Anchor Link

MPI is off by default, so the prebuilt PyPI wheels run single-rank and the communicators above only distribute work after a from-source build with MPI enabled. See Building from source for the full build instructions.