Skip to content
MENOS

Don't just simulate the circuit. Plan how it should run.

MENOS is a quantum circuit simulation compiler and runtime. It analyzes each workload and selects a feasible execution plan from estimated cost and resource limits, as a native Qiskit BackendV2 and EstimatorV2.

Read the documentationSee how it plans

At a glance

  • 1.2.0Version
  • Apache-2.0License
  • ≥ 3.10Python
  • Linux x86-64 · Windows x64Verified on
backend_v2_bell.py · verified documentation example
"""Bell state through the Qiskit BackendV2 adapter."""​​from qiskit import QuantumCircuit​from menos.qiskit import MENOSBackend​​qc = QuantumCircuit(2, 2)​qc.h(0)​qc.cx(0, 1)​qc.measure([0, 1], [0, 1])​​backend = MENOSBackend()​result = backend.run(qc, shots=1000, seed_simulator=7).result()​counts = result.get_counts()​print(counts)​​# A Bell pair only ever yields 00 or 11, and every shot is accounted for.​assert set(counts) <= {"00", "11"}​assert sum(counts.values()) == 1000​

One fixed algorithm is the wrong default.

Instead of forcing every circuit through one rigid simulation engine, MENOS works as a compiler and runtime: analyze the circuit, price candidate strategies, run the cheapest feasible plan, and monitor it against strict resource limits. Architecture documentation

  • Circuit analysis & reduction

    Before simulation begins, MENOS analyzes the circuit graph, removes operations outside the causal past via light-cone reduction, and identifies independent qubit subgraphs.

  • Candidate strategy pricing

    Evaluates candidate execution strategies across dense, stabilizer, MPS, Pauli propagation, tensor network, and cut plans under a unified cost model.

  • Feasible plan selection

    Selects the cheapest feasible plan within memory and time budgets. Infeasible candidates are recorded with explicit refusal causes rather than being hidden.

  • Calibrated CPU & CUDA choices

    For dense simulation, the planner selects CUDA GPU execution only when estimated end-to-end seconds—including data transfer latency—is lower than CPU execution.

  • Strict exactness by default

    Every engine reachable from Python is exact. MENOS never silently switches to approximate results when an exact run cannot fit within budget; the job is refused, not degraded.

  • Safe monitoring & replanning

    Time budgets are monitored at safe boundaries. On overrun, execution halts cleanly, records the observed runtime floor, and re-invokes the planner to choose an alternative plan.

Plans first, then simulates

Planner illustration

A circuit enters on the left. The planner prices candidate strategies, such as dense, stabilizer, MPS and factorized, and sends the job down the cheapest feasible route.

Hover to nudge the nodes, or click a route to inspect it. This is an explanatory model, not a live execution run.

Planner · conceptual model
plan: direct_mps · selected

Analyze, cost, select, execute, and replan on overrun.

Every MENOS job follows the documented six-stage workflow. Select a stage to see what happens. If an engine overruns its time budget, execution halts cleanly at a safe boundary and the job replans from the observed lower bound.
Execution loop · conceptual
CIRCUIT IN →→ RESULT (with explain)replan on overrun01CircuitAnalysis02CandidateStrategies03Cost Estimation& Feasibility04Plan Selection05Execution06Monitoring &Replanning

Stage 1 of 6

Circuit Analysis

Extract circuit topology, causal light cone, and independent qubit groups.

MENOS converts the circuit into its intermediate representation (KIR), validates structure, drops operations outside the causal past of the requested output (light-cone reduction), and builds an interaction graph to identify independent qubit components.

Read Circuit Analysis in the docs ↗

Six documented execution strategies.

The planner evaluates candidate strategies against your circuit structure and requested output. No strategy is universally faster; each serves distinct workloads under strict resource constraints.

Candidate strategies

Statevector EngineOutput: Statevector, Counts, Expectation

Dense simulation

Holds all 2ⁿ state amplitudes and applies unitary gates directly. Exact, supports arbitrary gates, and is the only strategy that can produce a full statevector.

Documented selection criteria

Chosen when arbitrary universal gates or full statevectors are required. For dense execution, the planner uses a calibrated model to choose between CPU and CUDA GPU based on end-to-end seconds.

Dense simulation documentation ↗
Architecture capability

Automatic Factorization

Simulates non-interacting qubit groups independently and recombines them exactly.

During the circuit analysis phase, MENOS inspects the two-qubit interaction graph to discover connected components. Qubits that never share multi-qubit entangling operations are factorized into separate independent regions. Each region is planned and simulated on its own engine, and results are recombined with zero loss of exactness.

Factorization docs ↗

See what a planner would notice.

Build a small circuit and read two structural facts the documentation says MENOS uses: whether the circuit is Clifford-only, and which qubit groups never interact. This runs in your browser. It does not call MENOS or simulate anything.
Circuit composer · illustrative

Click a cell to place H. Click the same gate again to remove it. Illustrative circuit, not MENOS output.

Examples

Structural reading

Gates
4 total · 1 CNOT · 2 non-Clifford
Clifford-only
No — T is not a Clifford gate, so the stabilizer engine does not apply to this circuit.
Independent groups
{q0, q1} {q2} {q3} — qubits that never share a CNOT can be simulated independently and recombined exactly (automatic factorization).

The real planner weighs cost in work units across all engines and your budgets. These two facts are inputs it can use, not its decision.

Three distinct experiments. Kept strictly separate.

Scientific benchmarks answer specific questions under controlled conditions. Below are the three separate benchmark studies from local reports. They are distinct experiments with different backends and circuits; they are not merged into a single dataset.

Disclaimer: these benchmarks were run on the developer's own machine. Results depend on hardware, drivers and configuration, and may differ on yours.

Experiment A: MENOS versus PennyLane Lightning GPU

Evaluation across register sizes from 4 to 21 qubits on identical circuits (5 repetitions, 1 warm-up, 1,024 shots). MENOS ran on the host CPU with 0 MB dedicated GPU VRAM, while PennyLane lightning.gpu used an NVIDIA RTX 3050 laptop GPU allocating 338.5 MB VRAM. MENOS performs strongly on Bernstein–Vazirani (up to 40.8x faster) and VQE (up to 11.0x faster), while PennyLane GPU gains advantage on deep 20Q QAOA and QFT circuits.

Bernstein-Vazirani @ 21 qubits

Replay of the measured medians. Bar speed is compressed; the times are real.

MENOShost CPU
0.00ms
PennyLane lightning.gpuNVIDIA RTX 3050 laptop GPU
0.0ms
Racing40.80x

Circuit: 72 gates, depth 14, identical on both backends. Click a point on the chart to race another size.

0.1 ms1.0 ms10 ms100 ms5Q9Q13Q17Q21QQubit register count (n)Execution latency (ms, log scale)
  • MENOS (Host CPU, median)
  • PennyLane lightning.gpu (RTX 3050)
Click any point to inspect
Bernstein-Vazirani @ 21 QubitsCircuit: 72 gates · depth 14 (identical on both backends)
MENOS Host CPU0.00 ms
PennyLane RTX 30500.00 ms
Speed Comparison40.80x
Faster BackendMENOS
View data table for Bernstein-Vazirani (5–21Q)
QubitsGatesDepthMENOS (ms)PL GPU (ms)Speed RatioFaster
5Q1660.214.1419.90xMENOS
9Q3080.455.2611.58xMENOS
13Q44100.405.7514.31xMENOS
17Q58120.607.7412.91xMENOS
21Q72140.9338.0740.80xMENOS

Hardware: Host x86_64 CPU (MENOS) vs NVIDIA GeForce RTX 3050 Laptop GPU (4 GB GDDR6 VRAM, lightning.gpu) (Ubuntu 24.04 LTS (WSL2), NVIDIA Driver 592.82, CUDA 13.1, cuStateVec cu12).

Methodology: Median of 5 repetitions, 1 warm-up run, 1,024 shots per configuration. Matched circuit definitions for both backends.

Scope: Evaluates single-node host execution (MENOS) against entry-level laptop GPU acceleration (RTX 3050). Datacenter GPUs (A100/H100) and GPU-accelerated MENOS were not part of this scope.

Budgets are constraints, not hints. Exactness is guaranteed.

What MENOS will and will not do with your memory, your runtime, and your GPU. Verified against the official documentation: CUDA execution applies to the dense engine on NVIDIA GPUs when calibrated models predict faster end-to-end runs. MENOS does not silently degrade to approximation.
Policy

Memory budgets

Every plan has a memory constraint (by default 50% of physical RAM). The planner performs pre-execution feasibility checks and refuses any candidate that would exceed the budget before allocating anything.

Read Memory budgets in docs ↗
Policy

Time budgets & replanning

Time budgets are strict constraints. Monitored runs check progress at safe boundaries. On overrun, MENOS halts cleanly, records the observed floor, and replans under the original planner.

Read Time budgets & replanning in docs ↗
Policy

Cost-based CPU & CUDA selection

The dense engine supports NVIDIA CUDA. The planner compares CPU and GPU execution using a calibrated model of end-to-end seconds including host-device data transfers and kernel launches. Ties go to the CPU.

Read Cost-based CPU & CUDA selection in docs ↗
Policy

Strict exactness by default

Every engine reachable from Python is exact. MENOS never silently switches to approximate methods when an exact run cannot fit within budget; the job is refused rather than degraded.

Read Strict exactness by default in docs ↗
Planning model

How the Planner Chooses Between CPU and CUDA

MENOS does not assume GPU execution is always faster. GPU acceleration introduces fixed kernel dispatch latency and PCIe host-to-device and device-to-host transfer costs. For the dense engine, MENOS calibrates these constants on your local machine and calculates end-to-end execution time:

When the CPU is Preferred

  • Small circuits (< crossover): Launch and transfer overhead outweighs raw gate throughput.
  • Sampling counts from large states: The entire statevector must transfer back across PCIe to host memory.
  • Non-dense strategies: Stabilizer, MPS, Pauli propagation, and tensor network engines execute on host CPU.
  • Ties in cost model: If estimated times are equal, execution remains on the CPU.

When CUDA GPU is Selected

  • Dense simulation above crossover: High qubit counts (typically ≥ 14–16Q) where massive parallel streaming multiprocessors dominate latency.
  • Deep universal circuits: High gate density amortizes the fixed kernel launch and memory copy costs.
  • Calibrated cost model: The dense engine switches to CUDA only when estimated seconds (transfers included) is lower than CPU.
  • Bitwise identical: Results produced on CUDA hash identically to CPU statevectors.
Hardware requirement: Supported NVIDIA GPU with CUDA installation per official docs.CPU vs CUDA technical guide ↗

Install from PyPI, then run with Qiskit.

MENOS is on PyPI: pip install menos or uv add menos. Prebuilt wheels cover Linux x86-64 and Windows x64 (CPU-only); source and issues are on GitHub. It plugs into existing Qiskit workflows through standards-conforming BackendV2 and EstimatorV2 adapters.
  • Python 3.10 or newer
  • Linux x86-64 or Windows x64 (CPU wheels)
  • Qiskit, for the BackendV2 / EstimatorV2 adapters
  1. 1

    Install with pip

    MENOS is available on PyPI. Install it into your active Python environment.

    Install from PyPI with pip
    pip install menos​
  2. 2

    Or add with uv

    In a uv-managed project, add it as a dependency.

    Or add it to a project with uv
    uv add menos​
  3. 3

    Verify installation

    Prints the installed version if the package imported correctly.

    Verify installation
    python -c "import menos; print(menos.__version__)"​
  4. 4

    Qiskit BackendV2: Sampling & Counts

    Use MENOSBackend to execute standard QuantumCircuit objects. The planner selects the optimal feasible engine and samples exact results.

    What this checks
    Bell pair yields only 00 and 11 states across all 1,000 shots.
    backend_v2_bell.py · verified documentation example
    """Bell state through the Qiskit BackendV2 adapter."""​​from qiskit import QuantumCircuit​from menos.qiskit import MENOSBackend​​qc = QuantumCircuit(2, 2)​qc.h(0)​qc.cx(0, 1)​qc.measure([0, 1], [0, 1])​​backend = MENOSBackend()​result = backend.run(qc, shots=1000, seed_simulator=7).result()​counts = result.get_counts()​print(counts)​​# A Bell pair only ever yields 00 or 11, and every shot is accounted for.​assert set(counts) <= {"00", "11"}​assert sum(counts.values()) == 1000​
  5. 5

    Qiskit EstimatorV2: Expectation Values

    MENOSEstimator implements Qiskit's BaseEstimatorV2. Evaluates Primitive Unified Blocs (PUBs) with Pauli observables (SparsePauliOp) without sampling error.

    Zero variance
    Because engines are exact by default, returned standard deviations (stds) are strictly 0.0.
    estimator_v2_pub.py · verified documentation example
    """Expectation values through the Qiskit EstimatorV2 adapter."""​​from qiskit import QuantumCircuit​from qiskit.quantum_info import SparsePauliOp​from menos.qiskit import MENOSEstimator​​qc = QuantumCircuit(2)​qc.h(0)​qc.cx(0, 1)​​# Primitive Unified Bloc: (circuit, observables)​observables = [SparsePauliOp("ZZ"), SparsePauliOp("XX"), SparsePauliOp("ZI")]​estimator = MENOSEstimator()​job = estimator.run([(qc, observables)])​pub_result = job.result()[0]​​print("Expectation values:", pub_result.data.evs)​# Bell pair exact expectation values: ZZ=1.0, XX=1.0, ZI=0.0​assert list(pub_result.data.evs) == [1.0, 1.0, 0.0]​assert float(pub_result.data.stds.max()) == 0.0  # Exact by default​

All commands and code snippets are verified against the official Installation, Qiskit Integration, and EstimatorV2 documentation.

The documentation has the rest.

Installation guides, the planner and unified cost model, six execution strategies, CPU and CUDA evaluation, and the complete Python API reference.

Open the documentationInstallation guideGitHub ↗PyPI ↗