Release v0.2.4

Author: SidRichardsQuantum

.github/workflows/ci.yml

@@ -35,14 +35,75 @@ jobs:
         run: |
           ruff check .
 
+      - name: Format check (ruff)
+        run: |
+          ruff format --check src tests scripts
+
       - name: Run tests
         run: |
           pytest -q
 
+  docs-build:
+    name: Docs build / Python 3.12
+    runs-on: ubuntu-latest
+    needs: test-base
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Upgrade packaging tooling
+        run: |
+          python -m pip install --upgrade pip
+
+      - name: Install package + docs deps
+        run: |
+          python -m pip install -e ".[docs]"
+
+      - name: Build docs with warnings as errors
+        run: |
+          python -m sphinx -W -b html docs docs/_build/html
+
+  notebook-smoke:
+    name: Notebook smoke / Python 3.12
+    runs-on: ubuntu-latest
+    needs: test-base
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Upgrade packaging tooling
+        run: |
+          python -m pip install --upgrade pip
+
+      - name: Install package + notebook smoke deps
+        run: |
+          python -m pip install -e ".[dev,notebooks]"
+
+      - name: Execute smoke notebook
+        run: |
+          pytest --nbmake notebooks/Binary.ipynb
+
   package-validation:
     name: Package validation / Python 3.12
     runs-on: ubuntu-latest
-    needs: test-base
+    needs:
+      - test-base
+      - docs-build
+      - notebook-smoke
 
     steps:
       - name: Checkout

.gitignore

@@ -38,6 +38,7 @@ ENV/
 # Jupyter
 # -----------------------
 .ipynb_checkpoints/
+notebooks/notebooks/
 
 # -----------------------
 # Lint / format caches

README.md

@@ -64,6 +64,7 @@ Notebook client:
 
 - `notebooks/Binary.ipynb`
 - `notebooks/examples/02_Real_Example.ipynb`
+- `notebooks/examples/04_Larger_Real_Data_Example.ipynb`
 
 ---
 
@@ -98,6 +99,7 @@ Notebook client:
 
 - `notebooks/QAOA.ipynb`
 - `notebooks/examples/03_Real_Example.ipynb`
+- `notebooks/examples/04_Larger_Real_Data_Example.ipynb`
 
 ---
 
@@ -123,6 +125,7 @@ Notebook clients:
 
 - `notebooks/Fractional.ipynb`
 - `notebooks/examples/01_Real_example.ipynb`
+- `notebooks/examples/04_Larger_Real_Data_Example.ipynb`
 
 ---
 
@@ -211,14 +214,16 @@ src/
 
 scripts/
 ├── generate_comparison_results.py  # Synthetic baselines and repeatability CSVs
-└── generate_ansatz_comparison.py   # Compact ansatz comparison CSV
+├── generate_ansatz_comparison.py   # Compact ansatz comparison CSV
+└── generate_larger_real_data_example.py  # 12-stock real-data example artifacts
 
 results/
 ├── synthetic_comparison.csv
 ├── real_data_comparison.csv
 ├── generated_comparison_summary.csv
 ├── generated_repeatability_trials.csv
 ├── real_data_method_comparison.csv
+├── larger_real_data_comparison.csv
 └── ansatz_comparison.csv
 
 notebooks/
@@ -231,7 +236,8 @@ notebooks/
 ├── examples/
 │   ├── 01_Real_example.ipynb
 │   ├── 02_Real_Example.ipynb
-│   └── 03_Real_Example.ipynb
+│   ├── 03_Real_Example.ipynb
+│   └── 04_Larger_Real_Data_Example.ipynb
 └── images/
 
 tests/

RESULTS.md

@@ -9,6 +9,7 @@ Machine-readable copies of the comparison tables are committed under `results/`:
 - `results/generated_comparison_summary.csv`
 - `results/generated_repeatability_trials.csv`
 - `results/real_data_method_comparison.csv`
+- `results/larger_real_data_comparison.csv`
 - `results/ansatz_comparison.csv`
 
 For repeatable synthetic benchmark summaries, regenerate a compact comparison CSV with:
@@ -180,6 +181,32 @@ Binary rows use equal-weight selected portfolios for reported return and risk, w
 ![Real data method comparison fractional objective](notebooks/images/Real_Data_Method_Comparison_Fractional_Objective.png)
 ![Real data method comparison feasibility](notebooks/images/Real_Data_Method_Comparison_Feasibility.png)
 
+### Larger Real-Data Universe
+
+`scripts/generate_larger_real_data_example.py` writes `results/larger_real_data_comparison.csv`, regenerates `notebooks/examples/04_Larger_Real_Data_Example.ipynb`, and saves figures for a 12-stock 2024 market-data window. The binary and QAOA methods use one qubit per asset, so this example is deliberately a scalability/stress example rather than a claim of production scale or quantum advantage.
+
+Regenerate it with:
+
+```bash
+python scripts/generate_larger_real_data_example.py
+```
+
+| Method | Objective family | K | Selection or weights | Return | Risk | Best objective | Feasible rate |
+| --- | --- | ---: | --- | ---: | ---: | ---: | ---: |
+| Classical exhaustive search | binary QUBO | 5 | AAPL, NVDA, JPM, JNJ, PG | 0.341060 | 0.128919 | -0.043287 | 1.000000 |
+| Binary VQE best feasible | binary QUBO | 5 | NVDA, XOM, JNJ, PG, HD | 0.257295 | 0.120824 | 0.173363 | 0.777344 |
+| QAOA X best feasible | binary QUBO | 5 | AAPL, META, JPM, PG, UNH | 0.248903 | 0.117525 | 0.136708 | 0.343750 |
+| QAOA XY best feasible | binary QUBO | 5 | MSFT, NVDA, GOOGL, JPM, UNH | 0.346208 | 0.172098 | 1.230733 | 1.000000 |
+| Classical exact Markowitz | fractional simplex |  | simplex weights | 0.580921 | 0.226857 | -0.375066 | 1.000000 |
+| Fractional VQE | fractional simplex |  | simplex weights | 0.549605 | 0.217478 | -0.360419 | 1.000000 |
+
+![Larger real-data risk return](notebooks/examples/images/Larger_Real_Data_Risk_Return.png)
+![Larger real-data binary objective](notebooks/examples/images/Larger_Real_Data_Binary_Objective.png)
+![Larger real-data fractional objective](notebooks/examples/images/Larger_Real_Data_Fractional_Objective.png)
+![Larger real-data feasibility](notebooks/examples/images/Larger_Real_Data_Feasibility.png)
+![Larger real-data asset returns](notebooks/examples/images/Larger_Real_Data_Asset_Returns.png)
+![Larger real-data fractional allocation pies](notebooks/examples/images/Larger_Real_Data_Fractional_Weights.png)
+
 ### Real Fractional Frontier
 
 | Method | λ | Return | Risk |
@@ -245,5 +272,6 @@ Then open the notebook clients:
 - `notebooks/examples/01_Real_example.ipynb`
 - `notebooks/examples/02_Real_Example.ipynb`
 - `notebooks/examples/03_Real_Example.ipynb`
+- `notebooks/examples/04_Larger_Real_Data_Example.ipynb`
 
 The notebooks should save updated plots under `notebooks/images/` and `notebooks/examples/images/`.