🚀 Initial scaffold: Quantum Error Mitigation Benchmarking Suite

- Pluggable mitigator interface (ZNE, PEC, CDR) with abstract base class
- Noise characterisation module (Days 1-3)
- Mitigation implementations skeleton (Days 4-6)
- Benchmarking pipeline (Days 7-8)
- Analysis + plotting modules (Days 9-10)
- arXiv-style LaTeX report template with BibTeX references
- CI/CD: flake8 + black linting, pytest + Codecov
- 17 passing skeleton tests
- Full README with architecture diagram, roadmap, and quickstart

Author: johngeorgea157-stack

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & Format Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install lint tools
+        run: |
+          pip install flake8 black
+
+      - name: Run flake8 (PEP8)
+        run: |
+          flake8 noise_characterisation/ mitigation/ benchmarks/ analysis/ \
+            --max-line-length=100 \
+            --exclude=__pycache__,*.ipynb_checkpoints \
+            --ignore=E402
+
+      - name: Run black (formatting check)
+        run: |
+          black --check --line-length=100 \
+            noise_characterisation/ mitigation/ benchmarks/ analysis/
+
+      - name: Validate imports
+        run: |
+          python -c "import numpy, scipy, matplotlib"
+          echo "Core imports OK"

.github/workflows/test.yml

@@ -0,0 +1,47 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Run Test Suite
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install pytest pytest-cov
+
+      - name: Run mitigation tests
+        run: |
+          pytest mitigation/tests/ -v --tb=short
+
+      - name: Run benchmark circuit tests
+        run: |
+          pytest benchmarks/tests/ -v --tb=short
+
+      - name: Run full suite with coverage
+        run: |
+          pytest mitigation/tests/ benchmarks/tests/ \
+            --cov=mitigation --cov=benchmarks --cov=analysis \
+            --cov-report=xml \
+            --cov-report=term-missing
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: false

.gitignore

@@ -0,0 +1,41 @@
+# Environments
+.env
+.venv
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+
+# Jupyter
+.ipynb_checkpoints
+
+# Data / Results
+data/raw/*.json
+data/raw/*.csv
+results/raw_data/*.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets
+apikey.json
+
+# Docs build artifacts
+docs/_build/
+report/*.aux
+report/*.log
+report/*.out
+report/*.synctex.gz
+
+# Personal notes
+learning.md
+
+# Roadmap file
+qc Month 1.docx

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John George Alexander
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.