{"id":47827861,"url":"https://github.com/fedorshind/emrg","last_synced_at":"2026-04-18T13:07:16.397Z","repository":{"id":338063835,"uuid":"1152199961","full_name":"FedorShind/EMRG","owner":"FedorShind","description":"Error Mitigation Recipe Generator -- Automatic quantum error mitigation for NISQ circuits.  EMRG analyzes your quantum circuit and generates ready-to-run, explained Mitiq-powered error mitigation code. No manual tuning required.","archived":false,"fork":false,"pushed_at":"2026-04-03T18:14:02.000Z","size":147,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-03T20:52:37.074Z","etag":null,"topics":["error-mitigation","mitiq","python","qasm","qiskit","quantum-computing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FedorShind.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T14:17:35.000Z","updated_at":"2026-04-03T18:09:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FedorShind/EMRG","commit_stats":null,"previous_names":["fedorshind/emrg"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/FedorShind/EMRG","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedorShind%2FEMRG","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedorShind%2FEMRG/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedorShind%2FEMRG/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedorShind%2FEMRG/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FedorShind","download_url":"https://codeload.github.com/FedorShind/EMRG/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FedorShind%2FEMRG/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31969845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["error-mitigation","mitiq","python","qasm","qiskit","quantum-computing"],"created_at":"2026-04-03T20:02:09.731Z","updated_at":"2026-04-18T13:07:16.390Z","avatar_url":"https://github.com/FedorShind.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EMRG\n\n[![CI](https://github.com/FedorShind/EMRG/actions/workflows/ci.yml/badge.svg)](https://github.com/FedorShind/EMRG/actions/workflows/ci.yml)\n[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/FedorShind/EMRG/blob/main/docs/tutorials/vqe_h2_mitigation.ipynb)\n\n**Error Mitigation Recipe Generator** -- Automatic quantum error mitigation for NISQ circuits.\n\nEMRG analyzes a quantum circuit and generates ready-to-run [Mitiq](https://mitiq.readthedocs.io/) error mitigation code. It selects between ZNE, PEC, and CDR, tunes the parameters, and explains each decision. No manual configuration required.\n\n\u003e **v0.3.0** -- ZNE + PEC + CDR + Preview. [Roadmap](#roadmap) below.\n\n---\n\n## Why EMRG?\n\nZNE, PEC, and CDR can boost fidelity 2--10x on noisy hardware, but each has different requirements and tradeoffs. Choosing the right technique for a given circuit means evaluating depth, gate composition, non-Clifford fraction, noise model availability, and sampling overhead. EMRG automates this: give it a circuit, get back runnable mitigation code with rationale for every parameter choice.\n\n## How It Works\n```\nQuantum Circuit --\u003e [Analyze] --\u003e [Technique Selection] --\u003e [Code Generator] --\u003e Mitigated Code\n                                     PEC / CDR / ZNE\n```\n\n1. **Parse \u0026 Validate** -- Load a Qiskit `QuantumCircuit` or QASM file.\n2. **Extract Features** -- Depth, gate counts, noise factor, non-Clifford fraction, PEC overhead, layer heterogeneity.\n3. **Select Technique** -- First match wins: PEC \u003e CDR \u003e ZNE, based on circuit characteristics.\n4. **Generate Code** -- Runnable Python with Mitiq imports, configuration, and inline rationale.\n\n### Heuristic Rules (v0.3)\n\n| Circuit Profile | Technique | Configuration | Rationale |\n|---|---|---|---|\n| Depth ≤ 30 + noise model + overhead \u003c 1000 | **PEC** | Depolarizing representations | Unbiased error cancellation when overhead is manageable |\n| Non-Clifford fraction \u003e 20% + depth 10--40 | **CDR** | 8--16 training circuits, linear fit | Clifford substitution + regression outperforms ZNE on non-Clifford-heavy circuits |\n| Depth \u003c 20, low multi-qubit gates | ZNE `LinearFactory` | `[1.0, 1.5, 2.0]` | Conservative for shallow circuits |\n| Depth 20--50 | ZNE `RichardsonFactory` | `[1.0, 1.5, 2.0, 2.5]` | Better extrapolation for moderate noise |\n| Depth \u003e 50 or high noise | ZNE `PolyFactory` (deg 2--3) | `[1.0, 1.5, 2.0, 2.5, 3.0]` | Handles non-linear noise scaling |\n\n## Quick Start\n\n### Installation\n```\npip install emrg\n```\n\nFor preview mode (noisy simulation comparison):\n```\npip install emrg[preview]\n```\n\nOr from source:\n```\ngit clone https://github.com/FedorShind/EMRG.git\ncd EMRG\npip install -e \".[dev]\"\n```\n\nOr try it without installing: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/FedorShind/EMRG/blob/main/docs/tutorials/vqe_h2_mitigation.ipynb)\n\n### CLI Usage\n```\n# Generate mitigation recipe from a QASM file\nemrg generate circuit.qasm\n\n# With verbose explanation\nemrg generate circuit.qasm --explain\n\n# Save to file\nemrg generate circuit.qasm -o mitigated.py\n\n# Force a specific technique\nemrg generate circuit.qasm --technique pec --noise-model\nemrg generate circuit.qasm --technique cdr\n\n# Preview: simulate and compare before/after mitigation\nemrg generate circuit.qasm --preview\n\n# Preview with custom noise level and observable\nemrg generate circuit.qasm --preview --noise-level 0.03 --observable ZZ\n\n# Analyze circuit features\nemrg analyze circuit.qasm\n\n# JSON output (for scripting)\nemrg analyze circuit.qasm --json\n```\n\n### Python API\n```python\nfrom qiskit import QuantumCircuit\nfrom emrg import generate_recipe\n\n# Create a circuit\nqc = QuantumCircuit(2, 2)\nqc.h(0)\nqc.cx(0, 1)\nqc.measure([0, 1], [0, 1])\n\n# Generate mitigation recipe (one-liner)\nresult = generate_recipe(qc)\nprint(result)             # Ready-to-run Python script\nprint(result.rationale)   # Why these parameters were chosen\nprint(result.features)    # Circuit analysis details\n\n# With PEC (requires noise model availability)\nresult = generate_recipe(qc, noise_model_available=True)\n\n# Force CDR (requires cirq: pip install emrg[preview])\nresult = generate_recipe(qc, technique=\"cdr\")\n\n# With preview simulation\nresult = generate_recipe(qc, preview=True, noise_level=0.01)\nprint(result.preview)     # Simulation comparison results\n```\n\n### Example Output\n```\n# =============================================================\n# EMRG v0.3.0 -- Error Mitigation Recipe\n# Circuit: 2 qubits, depth 3, 1 multi-qubit gates\n# Noise estimate: 0.011 (low)\n# =============================================================\n#\n# Recommendation: LinearFactory + fold_global\n#\n# =============================================================\n\nfrom mitiq.zne import execute_with_zne\nfrom mitiq.zne.inference import LinearFactory\nfrom mitiq.zne.scaling import fold_global\n\nfactory = LinearFactory(scale_factors=[1.0, 1.5, 2.0])\n\ndef execute(circuit):\n    \"\"\"Execute a circuit and return an expectation value (float).\"\"\"\n    # Replace with your actual backend\n    raise NotImplementedError(\"Replace this with your executor.\")\n\nmitigated_value = execute_with_zne(\n    circuit,\n    execute,\n    factory=factory,\n    scale_noise=fold_global,\n)\n\nprint(f\"Mitigated expectation value: {mitigated_value}\")\n```\n\n## Preview Mode\n\n`--preview` runs a noisy simulation, applies the recommended mitigation, and displays a before/after comparison. This validates the recipe before spending real hardware shots.\n```\nemrg generate circuit.qasm --preview\n```\n```\n┌─────────────────────────────────────────────────┐\n│  EMRG Preview -- Simulation Comparison         │\n├─────────────────────────────────────────────────┤\n│  Circuit:    2 qubits, depth 3                 │\n│  Noise:      depolarizing p=0.01               │\n│  Observable: \u003cZ\u003e on qubit 0                    │\n│  Technique:  ZNE                               │\n├─────────────────────────────────────────────────┤\n│  Ideal:      -1.0000                           │\n│  Noisy:      -0.9761  (error: 0.0239)          │\n│  Mitigated:  -1.0003  (error: 0.0003)          │\n│                                                │\n│  Error reduction: 77.5x                        │\n└─────────────────────────────────────────────────┘\n```\n\nUses Cirq's `DensityMatrixSimulator` with per-gate depolarizing noise. Circuits above 10 qubits are skipped (density matrix cost scales as O(4^n)). PEC preview uses 200 samples; CDR uses the recipe's training circuit count. Both produce approximate results that vary between runs.\n\nRequires `pip install emrg[preview]`.\n\n## Project Structure\n```\nEMRG/\n├── src/emrg/\n│   ├── __init__.py      # Public API and generate_recipe()\n│   ├── _version.py      # Single source of truth for version\n│   ├── analyzer.py      # Circuit feature extraction\n│   ├── heuristics.py    # Rule-based decision engine\n│   ├── codegen.py       # Template-based code generation\n│   ├── preview.py       # Simulation preview engine\n│   ├── cli.py           # Click CLI interface\n│   └── py.typed         # PEP 561 type marker\n├── tests/               # 366+ tests, 99% coverage\n├── docs/\n│   ├── examples/        # Example circuits (Python + QASM)\n│   └── tutorials/       # Jupyter notebooks (VQE, QAOA)\n├── benchmarks/          # Automated benchmark suite\n└── pyproject.toml       # Package configuration\n```\n\n## Benchmarks\n\nCollected by [`benchmarks/run_benchmark.py`](benchmarks/run_benchmark.py) on EMRG v0.3.0.\n\n\u003e **Environment:** Python 3.12, Windows 11 | Qiskit 2.3.0, Mitiq 0.48.1\n\n### Tool Performance\n\n`generate_recipe()` uses pure Qiskit introspection (no simulation), so it completes in sub-millisecond time even for large circuits. Median of 100 runs:\n\n| Circuit | Qubits | Depth | Gates | Multi-Q | Het | Technique / Config | Time | Memory |\n|---|---|---|---|---|---|---|---|---|\n| Bell state | 2 | 3 | 2 | 1 | 0.00 | `LinearFactory` + fold_global | 0.09 ms | 9.4 KB |\n| Bell state (PEC) | 2 | 3 | 2 | 1 | 0.00 | PEC | 0.09 ms | 9.4 KB |\n| GHZ-5 | 5 | 6 | 5 | 4 | 0.50 | `LinearFactory` + fold_global | 0.14 ms | 15.2 KB |\n| GHZ-10 | 10 | 11 | 10 | 9 | 0.50 | `LinearFactory` + fold_global | 0.24 ms | 24.9 KB |\n| Random 10q, 3 layers | 10 | 7 | 45 | 15 | 0.83 | `LinearFactory` + fold_global | 0.39 ms | 21.2 KB |\n| VQE 10q, 4 layers | 10 | 20 | 76 | 36 | 1.50 | CDR (16 training) | 0.64 ms | 43.8 KB |\n| Hetero 4q, 8 layers | 4 | 17 | 42 | 10 | 1.00 | CDR (12 training) | 0.40 ms | 34.6 KB |\n| T-gate 4q | 4 | 7 | 12 | 3 | 0.50 | `LinearFactory` + fold_global | 0.15 ms | 16.7 KB |\n| Rz-rot 4q, 4 layers | 4 | 14 | 28 | 12 | 0.50 | CDR (12 training) | 0.29 ms | 29.3 KB |\n| Random 20q, 6 layers | 20 | 13 | 180 | 60 | 0.91 | CDR (16 training) | 1.06 ms | 49.0 KB |\n| Random 30q, 10 layers | 30 | 21 | 450 | 150 | 0.94 | CDR (16 training) | 2.41 ms | 116.3 KB |\n| Random 50q, 15 layers | 50 | 31 | 1125 | 375 | 0.96 | CDR (16 training) | 5.81 ms | 282.0 KB |\n\nA 50-qubit, 1125-gate circuit is analyzed and produces a full mitigation recipe in under 6 ms. Circuits with non-Clifford rotations are automatically routed to CDR.\n\n### ZNE Fidelity\n\nEnd-to-end ZNE on Cirq `DensityMatrixSimulator` with per-gate depolarizing noise, comparing ⟨Z⟩ on qubit 0:\n\n| Circuit | Qubits | Depth | Noise | Technique / Config | Ideal | Noisy | Mitigated | Error Reduction |\n|---|---|---|---|---|---|---|---|---|\n| X-flip, 2q | 2 | 3 | p=0.01 | `LinearFactory` + fold_global | -1.0000 | -0.9761 | -1.0003 | **77x** |\n| X-flip, 3q | 3 | 4 | p=0.01 | `LinearFactory` + fold_global | -1.0000 | -0.9761 | -1.0003 | **77x** |\n| X-flip, 2q | 2 | 3 | p=0.05 | `LinearFactory` + fold_global | -1.0000 | -0.8836 | -0.9906 | **12x** |\n| X-flip, 3q | 3 | 4 | p=0.05 | `LinearFactory` + fold_global | -1.0000 | -0.8836 | -0.9906 | **12x** |\n| VQE 4q, 2 layers | 4 | 8 | p=0.01 | `LinearFactory` + fold_global | 0.0850 | 0.0775 | 0.0794 | **1.4x** |\n| VQE 4q, 4 layers | 4 | 14 | p=0.01 | `LinearFactory` + fold_global | -0.1915 | -0.1766 | -0.1850 | **2.3x** |\n| VQE 4q, 2 layers | 4 | 8 | p=0.05 | `LinearFactory` + fold_global | 0.0850 | 0.0523 | 0.0586 | **1.2x** |\n\n### PEC vs ZNE: Head-to-Head\n\nSame circuits, same noise, both techniques. PEC uses 1000 samples for benchmark accuracy; its results have inherent variance from stochastic sampling. ZNE is deterministic.\n\n**Single-qubit observable ⟨Z⟩:**\n\n| Circuit | Noise | ZNE Error | ZNE Reduction | PEC Error | PEC Reduction | Better |\n|---|---|---|---|---|---|---|\n| VQE 4q, 2 layers | p=0.01 | 0.0055 | 1.4x | 0.0007 | **10.4x** | PEC |\n| VQE 4q, 2 layers | p=0.03 | 0.0162 | 1.3x | 0.0138 | **1.5x** | PEC |\n| VQE 4q, 2 layers | p=0.05 | 0.0264 | 1.2x | 0.0176 | **1.9x** | PEC |\n| X-flip, 3q | p=0.03 | 0.0024 | **28.9x** | 0.0245 | 2.9x | ZNE |\n\n**Multi-qubit observable ⟨ZZ⟩:**\n\n| Circuit | Noise | ZNE Error | ZNE Reduction | PEC Error | PEC Reduction | Better |\n|---|---|---|---|---|---|---|\n| VQE 4q, 2 layers | p=0.01 | 0.0021 | **5.7x** | 0.0064 | 1.9x | ZNE |\n| VQE 4q, 2 layers | p=0.03 | 0.0102 | **3.4x** | 0.0173 | 2.0x | ZNE |\n| VQE 4q, 2 layers | p=0.05 | 0.0216 | 2.5x | 0.0147 | **3.6x** | PEC |\n\nZNE excels on structured circuits where noise scales predictably with folding (X-flip: 28.9x). PEC excels on irregular circuits at higher noise, where ZNE's extrapolation assumptions break down. On ⟨ZZ⟩, PEC overtakes ZNE as noise increases: 3.6x vs 2.5x at p=0.05. EMRG recommends PEC for shallow, noisy circuits with an available noise model, and ZNE otherwise.\n\n### Layerwise Folding\n\n`fold_gates_at_random` targets the noisiest gates in circuits with uneven layer structure, instead of folding uniformly. Benchmarks show mixed results; the heuristic thresholds are being refined.\n\n| Circuit | Qubits | Depth | Het | Noise | Global | Layerwise | Winner |\n|---|---|---|---|---|---|---|---|\n| VQE 10q, 3 reps | 10 | 13 | 2.50 | p=0.01 | 0.9x | **12.6x** | layerwise |\n| VQE 10q, 3 reps | 10 | 13 | 2.50 | p=0.03 | 1.1x | 1.1x | -- |\n| QAOA 10q | 10 | 14 | 2.50 | p=0.01 | **4.2x** | 0.2x | global |\n| QAOA 10q | 10 | 14 | 2.50 | p=0.03 | **5.9x** | 0.7x | global |\n| Extreme 10q | 10 | 13 | 2.50 | p=0.01 | 0.5x | 0.4x | -- |\n| Extreme 10q | 10 | 13 | 2.50 | p=0.03 | 0.5x | 0.1x | global |\n\n`fold_global` is more reliable at this scale because `fold_gates_at_random` adds stochastic variation to the extrapolation fit. Layerwise folding shows occasional strong results (12.6x on VQE at low noise) but is not consistent enough to be the default. EMRG defaults to `fold_global` and uses layerwise folding conservatively for high-heterogeneity circuits.\n\n### CDR vs ZNE\n\nCDR replaces non-Clifford gates with Clifford substitutes to create classically simulable training circuits, then fits a regression model to correct the noisy result. Compared to ZNE on circuits with non-Clifford gates:\n\n| Circuit | Noise | ZNE Error | ZNE Reduction | CDR Error | CDR Reduction | Better |\n|---|---|---|---|---|---|---|\n| Rz-rot 4q | p=0.01 | 0.0253 | 2.8x | ~0.0000 | **\u003e1000x** | CDR |\n| Rz-rot 4q | p=0.03 | 0.0866 | 2.3x | ~0.0000 | **\u003e1000x** | CDR |\n| VQE 4q, 2 layers | p=0.01 | 0.0055 | 1.4x | 0.0036 | **2.1x** | CDR |\n| VQE 4q, 2 layers | p=0.03 | 0.0162 | 1.3x | 0.0108 | **1.9x** | CDR |\n\nCDR recovers near-ideal expectation values on rotation-heavy circuits and consistently outperforms ZNE on VQE circuits at both low and moderate noise. EMRG auto-selects CDR when the non-Clifford gate fraction exceeds 20% and depth is between 10 and 40.\n\n### Reproduce\n```\npip install -e \".[dev]\" qiskit-aer\npython benchmarks/run_benchmark.py\n```\n\n## Roadmap\n\n### Phase 1 -- MVP (complete)\n\n- [x] Project structure and packaging\n- [x] Circuit analyzer (feature extraction)\n- [x] Heuristic engine (ZNE: Linear + Richardson + Poly)\n- [x] Code generator (template-based)\n- [x] CLI with `generate` and `analyze` commands\n- [x] Public Python API (`generate_recipe()`)\n- [x] Example circuits (Python + QASM) and documentation\n\n### Phase 2 -- Multi-technique support (current)\n\n- [x] Probabilistic Error Cancellation (PEC) support\n- [x] Multi-technique selection (ZNE vs PEC)\n- [x] PEC code generation template\n- [x] `--technique` override and `--noise-model` CLI flags\n- [x] Layerwise Richardson integration\n- [x] `--preview` mode (noisy simulation + before/after comparison)\n- [x] Expanded tutorials (VQE, QAOA)\n- [x] 366+ tests, 99% coverage, zero lint warnings\n- [x] Clifford Data Regression (CDR) support\n- [ ] Composite recipes -- combine ZNE + PEC for circuits that benefit from both\n- [ ] Real hardware benchmarks (IBM Quantum devices)\n\n### Phase 3 -- Multi-framework support\n\n- [ ] Cirq, PennyLane, and Amazon Braket input support\n- [ ] Noise model import from Qiskit Aer / real device calibration data\n- [ ] Configurable heuristics via YAML/JSON\n- [ ] Jupyter widget for interactive recipe exploration\n- [ ] Web/Colab interface\n\n### Phase 4 -- Data-driven selection\n\n- [ ] Train on benchmark data to predict optimal mitigation strategy\n- [ ] Circuit similarity search against known-good configurations\n- [ ] Auto-tuning via internal `--preview` iterations before output\n- [ ] Cost-aware optimization within user-specified shot budgets\n\n### Phase 5 -- Ecosystem integration\n\n- [ ] Qiskit Runtime integration\n- [ ] Mitiq Calibration API integration\n- [ ] VS Code extension for inline circuit analysis\n- [ ] CI/CD integration for quantum testing pipelines\n\n## Tech Stack\n\n* **Python 3.11+**\n* **Qiskit** \u003e= 1.0 -- circuit representation and introspection\n* **Mitiq** \u003e= 0.48 -- error mitigation primitives\n* **Click** \u003e= 8.0 -- CLI framework\n* **Cirq** \u003e= 1.0 -- simulation backend (optional, for preview and CDR)\n\n## Contributing\n\nOpen an issue or PR on [GitHub](https://github.com/FedorShind/EMRG).\n\n## License\n\n[MIT](LICENSE)\n\n## Acknowledgments\n\nBuilt on [Mitiq](https://mitiq.readthedocs.io/) by [Unitary Foundation](https://unitary.foundation/).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffedorshind%2Femrg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffedorshind%2Femrg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffedorshind%2Femrg/lists"}