Metadata-Version: 2.4
Name: cubespec
Version: 0.1.2
Summary: Monte Carlo, DOE, RSM and Sobol sensitivity for the 150 mm concrete cube compressive test (CubeSpec / Sensitive-Spark thesis dashboard).
Author: Sensitive-Spark Thesis Project
License: MIT
Project-URL: Homepage, https://app.ai-systems.today
Project-URL: Repository, https://github.com/ai-systems-today/cubespec
Project-URL: Documentation, https://app.ai-systems.today
Project-URL: Issues, https://github.com/ai-systems-today/cubespec/issues
Keywords: monte-carlo,design-of-experiments,sobol,sensitivity-analysis,concrete,compressive-strength,rsm,uncertainty-quantification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: scipy>=1.10
Requires-Dist: pandas>=2.0
Requires-Dist: SALib>=1.4
Requires-Dist: reportlab>=4.0
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7; extra == "plot"
Provides-Extra: cli
Requires-Dist: typer>=0.9; extra == "cli"
Provides-Extra: calibration
Requires-Dist: scikit-learn>=1.3; extra == "calibration"
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: scikit-learn>=1.3; extra == "dev"
Requires-Dist: matplotlib>=3.7; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: mutmut>=2.4; extra == "dev"
Requires-Dist: bandit>=1.7; extra == "dev"
Dynamic: license-file

# cubespec

> **Monte-Carlo, DOE, RSM and Sobol sensitivity for the 150 mm concrete
> cube compressive test** — Python companion to the
> [Sensitive-Spark dashboard](https://app.ai-systems.today), with
> a bit-for-bit parity contract against the TypeScript implementation.

[![CI](https://github.com/ai-systems-today/cubespec/actions/workflows/ci.yml/badge.svg)](https://github.com/ai-systems-today/cubespec/actions/workflows/ci.yml)
[![Notebooks](https://github.com/ai-systems-today/cubespec/actions/workflows/notebooks.yml/badge.svg)](https://github.com/ai-systems-today/cubespec/actions/workflows/notebooks.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Live demo](https://img.shields.io/badge/demo-sensitive--spark.lovable.app-blue)](https://app.ai-systems.today)
[![PyPI](https://img.shields.io/pypi/v/cubespec.svg)](https://pypi.org/project/cubespec/)
[![Python](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://pypi.org/project/cubespec/)
<!-- Enable after the first Zenodo release: -->
<!-- [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.PLACEHOLDER.svg)](https://doi.org/10.5281/zenodo.PLACEHOLDER) -->


Two front ends, one set of equations:

- 🌐 **Web dashboard** — React + TypeScript, runs in the browser, no install: <https://app.ai-systems.today>
- 🐍 **Python package** — `cubespec`, this repo. Notebook-, CLI- and library-friendly.

Both implementations share the same surrogate model and PRNG
(`mulberry32`), so the same seed gives the same numbers in either
environment, validated by `tests/test_parity.py` at `1e-9` tolerance.

> **Thesis narrative (revision 2026-05):** the thesis spine is **DOE
> construction and verification** — see
> [`notebooks/17_doe_verification.ipynb`](notebooks/17_doe_verification.ipynb)
> and the new
> [`examples/supervisor_realistic_csp.csv`](examples/supervisor_realistic_csp.csv)
> service-level preset. Surrogate, Sobol, RSM, bootstrap and reliability
> analyses are presented as **Further Work** in
> [`docs/appendix-further-work.md`](docs/appendix-further-work.md)
> (notebooks 11–16).

---

## What it does

Given the **Cube Specification Parameters** (CSP) — material density,
geometry (`dx, dy, dz`) and forces (`Fx, Fy, Fz`) — `cubespec` computes
the three dependent outputs P7 (deformation), P8 (strain), and **P9
(compressive strength)** through a calibrated surrogate, and quantifies
how uncertainty propagates through it.

| Capability | Web dashboard | Python (`cubespec`) |
|---|:---:|:---:|
| Live Monte-Carlo with convergence tracking | ✅ | ✅ |
| Independent / LHS / correlated MVN sampling | ✅ | ✅ |
| Full & fractional 2^(k-p) factorial DOE (1/2, 1/4, 1/8) | ✅ | ✅ |
| Main, 2-way & 3-way interaction effects | ✅ | ✅ |
| Quadratic Response-Surface fit + 2-D contours | ✅ | ✅ |
| Sobol S1 / ST sensitivity (Saltelli scheme) | ✅ | ✅ |
| Percentile bootstrap CI (B = 1000) | ✅ | ✅ |
| Residual diagnostics (RMSE, MAE, R², Q-Q) | ✅ | ✅ |
| CSV / JSON export | ✅ | ✅ |
| CLI | – | ✅ |
| Calibrated surrogate (poly-2 ridge + residuals) | ✅ | ✅ |

---

## Install

From PyPI (recommended):

```bash
pip install cubespec
```

With optional extras (plots, CLI, calibration):

```bash
pip install "cubespec[plot,cli,calibration]"
```

From a local clone (for development):

```bash
git clone https://github.com/ai-systems-today/cubespec.git
cd cubespec
pip install -e ".[plot,cli,dev]"
```

Bleeding edge, straight from `main`:

```bash
pip install "git+https://github.com/ai-systems-today/cubespec.git"
```


---

## Quickstart — Python API

```python
from cubespec import (
    DEFAULT_CSP, sample_independent, compute_outputs_batch,
    bootstrap_mean_ci, sobol_indices,
)

# 50 000-draw Monte-Carlo run on the default CSP
X = sample_independent(DEFAULT_CSP, n=50_000, seed=1337)
Y = compute_outputs_batch(X)               # columns: P7, P8, P9
print(f"P9 mean: {Y[:, 2].mean():.2f} MPa")
# → P9 mean: 44.20 MPa  (matches the dashboard at the same seed)

# 95 % bootstrap CI on the P9 mean
lo, hi = bootstrap_mean_ci(Y[:, 2], B=1000, seed=1337, alpha=0.05)
print(f"95% CI: [{lo:.2f}, {hi:.2f}] MPa")

# Sobol indices (Saltelli, base N = 1024)
print(sobol_indices(DEFAULT_CSP, n_base=1024))
```

## Quickstart — CLI

```bash
# 50k Monte-Carlo run + report JSON
cubespec run --csp examples/default_csp.csv --n 50000 --output report.json

# Fractional 2^(7-3) factorial design
cubespec doe --csp examples/default_csp.csv --design fractional-1/8 --output design.csv

# Sobol sensitivity (Saltelli, base N = 1024)
cubespec sobol --csp examples/default_csp.csv --n 1024 --output sobol.csv

# Re-run a saved bundle from the dashboard's Reproduce button
cubespec replay run.json
```

---

## Methods (1-page summary)

The surrogate is

```
σ = F / A          A = dx · dy             (engineering stress, MPa)
E ≈ 0.255 · ρ¹·⁵                            (concrete stiffness law)
ε = σ / E                                   (Hooke)
δ = ε · h          h = dz                   (axial deformation)
```

with the disturbance term `−0.5·(|Fy|+|Fz|)/A` subtracted from σ to give P9.

**Sampling.** Independent Gaussian, Latin Hypercube (Owen-shuffled), or
multivariate normal with a Cholesky factor of an editable correlation matrix.

**DOE.** Two-level full factorial (2⁷ = 128 runs) and fractional designs
2^(7-1) / 2^(7-2) / 2^(7-3) generated via pyDOE2 (Resolution VII / IV /
IV). Effects estimated as the contrast of mean responses at coded ±1
levels.

**RSM.** Quadratic OLS on `[1, xᵢ, xᵢxⱼ, xᵢ²]`; 2-D contour grids over
any factor pair, others held at the run mean.

**Sobol.** Saltelli A/B/AB matrices; S1 and ST estimated via SALib. The
default span is ±3σ around each parameter mean.

**Confidence.** Percentile bootstrap (B = 1000, seed 1337) on the P9 mean.

Full theory and references in the bilingual thesis at
<https://app.ai-systems.today/thesis>.

---

## Notebooks

Seventeen Jupyter notebooks in [`notebooks/`](notebooks/) walk through
the full curriculum end-to-end:

| # | Topic |
|---:|---|
| 01 | Quickstart |
| 02 | CSP I/O |
| 03 | Live controls |
| 04 | Sampling strategies |
| 05 | Correlation presets |
| 06 | Full factorial DOE |
| 07 | Fractional DOE |
| 08 | Multilevel DOE |
| 09 | DOE interactions |
| 10 | DOE with measurements |
| 11 | Sobol indices |
| 12 | Response Surface Methodology |
| 13 | Optimisation |
| 14 | Uncertainty & reliability |
| 15 | Calibrated vs analytic surrogate |
| 16 | Full report parity |

All seventeen execute end-to-end in CI on every push to `main`
(see [`notebooks.yml`](.github/workflows/notebooks.yml)).

---

## Reproducibility

The thesis bundle is reproducible three ways:

1. **In-app Reproduce button** — open the dashboard at
   <https://app.ai-systems.today>, go to the Report tab, click
   **Reproduce thesis bundle**. Downloads a ZIP with every figure (PNG)
   and table (CSV) plus the commit SHA.
2. **Python CLI** — `cubespec replay run.json` re-executes a saved
   dashboard run.
3. **Parity contract** — `pytest tests/test_parity.py` matches the
   TypeScript fixtures bit-for-bit at `1e-9` tolerance.

---

## Documentation

**Validation & reproducibility** — the proofs behind every R², parity
tolerance and convergence claim:

- [`docs/validation-report.md`](docs/validation-report.md) — 5-fold CV, R² ∈ [0.92, 0.97], measured-vs-predicted scatters
- [`docs/verification-and-validation.md`](docs/verification-and-validation.md) — V&V protocol, parity gates, cross-mode sanity check
- [`docs/dev/surrogate-contract.md`](docs/dev/surrogate-contract.md) — frozen `poly2_ridge.json` schema (the public API surface of `model.py` / `surrogate.py`)
- [`docs/dev/parity-protocol.md`](docs/dev/parity-protocol.md) — fixture format, tolerances, regeneration recipe
- [`docs/dev/rng-contract.md`](docs/dev/rng-contract.md) — Mulberry32 PRNG spec enforcing TS↔Python determinism
- [`docs/dev/state-shapes.md`](docs/dev/state-shapes.md) — TypeScript-facing state shapes (relevant for cross-runtime parity)
- [`docs/figures/validation_convergence.png`](docs/figures/validation_convergence.png) — convergence ribbon

**Reference** — keys, units, schemas and concepts:

- [`docs/csp-parameters.md`](docs/csp-parameters.md) — Cube Specification Parameters: meaning, units, ranges
- [`docs/reference/keys-and-units.md`](docs/reference/keys-and-units.md) — canonical parameter keys and SI units
- [`docs/reference/csv-schemas.md`](docs/reference/csv-schemas.md) — CSV import/export schemas
- [`docs/reference/glossary-en.md`](docs/reference/glossary-en.md) / [`glossary-gr.md`](docs/reference/glossary-gr.md) — bilingual glossary
- [`docs/manual/00-overview.md`](docs/manual/00-overview.md) — high-level overview
- [`docs/manual/concepts-doe-monte-carlo-sobol.md`](docs/manual/concepts-doe-monte-carlo-sobol.md) — concept primer (DOE, Monte Carlo, Sobol)

**For thesis reviewers** — code and validation are here on GitHub; the
full dashboard manual and tutorials live at
<https://doe.ai-systems.today>; the thesis text will be archived at
Zenodo (DOI minted with the first PyPI release).

---

## Citation

Use [`CITATION.cff`](CITATION.cff) — GitHub renders a *Cite this
repository* button automatically. A Zenodo DOI will be minted with the
first PyPI release.

---

## License

MIT — see [`LICENSE`](LICENSE).
