Metadata-Version: 2.4
Name: cubespec
Version: 0.1.4
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://doe.ai-systems.today
Project-URL: Repository, https://github.com/ai-systems-today/cubespec
Project-URL: Documentation, https://ai-systems-today.github.io/cubespec/
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://doe.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)](https://github.com/ai-systems-today/cubespec/blob/main/LICENSE)
[![Live demo](https://img.shields.io/badge/demo-doe.ai--systems.today-blue)](https://doe.ai-systems.today)
[![Docs](https://img.shields.io/badge/docs-ai--systems--today.github.io%2Fcubespec-blue)](https://ai-systems-today.github.io/cubespec/)
[![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/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22060115.svg)](https://doi.org/10.5281/zenodo.22060115)


Two front ends, one set of equations:

- 🌐 **Web dashboard** — React + TypeScript, runs in the browser, no install: <https://doe.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`](https://github.com/ai-systems-today/cubespec/blob/main/notebooks/17_doe_verification.ipynb)
> and the
> [`examples/supervisor_realistic_csp.csv`](https://github.com/ai-systems-today/cubespec/blob/main/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`](https://ai-systems-today.github.io/cubespec/appendix-further-work/)
> (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 / triangular / 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) | ✅ | ✅ |
| Variance decomposition + reliability β-index | ✅ | ✅ |
| Constrained optimisation on the surrogate | ✅ | ✅ |
| 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 (returns a BootstrapResult)
ci = bootstrap_mean_ci(Y[:, 2], B=1000, seed=1337, alpha=0.05)
print(f"95% CI: [{ci.lo:.2f}, {ci.hi:.2f}] MPa  (mean {ci.mean:.2f})")

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

## Quickstart — CLI

Six subcommands: `run`, `doe`, `sobol`, `reliability`, `optimise`, `report`.
The `examples/` CSVs below ship in the repository (clone it, or pass your own
CSP CSV); omit `--csp` entirely to use the built-in default CSP.

```bash
# 50k Monte-Carlo run + bootstrap CI on P9 → 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

# Variance decomposition + reliability β-index against a 30 MPa threshold
cubespec reliability --threshold 30 --n 20000 --output reliability.json

# Box-constrained optimum on the calibrated surrogate (maximise P9)
cubespec optimise --maximise --starts 8 --output optimise.json

# Branded thesis PDF report
cubespec report --pdf cubespec_report.pdf --n 10000 --threshold 30
```

Every flag, exit code and piping example: [CLI reference](https://ai-systems-today.github.io/cubespec/cli/).

---

## 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),
triangular (3-point / PERT) marginals, 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) (Resolution VII / IV / IV), generated by the
package's own `fracfact` implementation in `cubespec.doe` (a pure-Python
replacement for `pyDOE2.fracfact`, which is broken on recent Python
versions — pyDOE2 is not a dependency). 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://doe.ai-systems.today/thesis>.

---

## Notebooks

Seventeen Jupyter notebooks in
[`notebooks/`](https://github.com/ai-systems-today/cubespec/tree/main/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 |
| 17 | DOE verification (histograms + pairwise scatter matrix) |

All seventeen execute end-to-end in CI on every push to `main`
(see [`notebooks.yml`](https://github.com/ai-systems-today/cubespec/blob/main/.github/workflows/notebooks.yml)).

---

## Reproducibility

The thesis bundle is reproducible three ways:

1. **In-app Reproduce button** — open the dashboard at
   <https://doe.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 run --csp <your.csv> --seed 1337` (and the
   other subcommands) regenerate the same numbers from the seed; the CSP
   CSV exported by the dashboard is accepted verbatim.
3. **Parity contract** — `pytest tests/test_parity.py` matches the
   TypeScript fixtures bit-for-bit at `1e-9` tolerance.

---

## Documentation

📖 **Browsable docs site:** <https://ai-systems-today.github.io/cubespec/>
(built from `docs/` with MkDocs Material — `pip install -r
requirements-docs.txt && mkdocs serve` to preview locally).

**Mathematics** — every equation, derivation and DOE design choice:

- [DOE + Monte Carlo mathematics (English)](https://ai-systems-today.github.io/cubespec/doe-and-montecarlo-math-en/)
- [Μαθηματικά DOE + Monte Carlo (ελληνικά)](https://ai-systems-today.github.io/cubespec/doe-and-montecarlo-math-gr/)
- [Equation derivations](https://ai-systems-today.github.io/cubespec/reference/equation-derivations/) — step-by-step
- [DOE design rationale](https://ai-systems-today.github.io/cubespec/reference/doe-design-rationale/) — why factorial/LHS rather than one-at-a-time
- [Standards mapping](https://ai-systems-today.github.io/cubespec/reference/standards-mapping/) — EN 206 / EN 12390 / NIST terminology



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

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

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

- [CSP parameters](https://ai-systems-today.github.io/cubespec/csp-parameters/) — Cube Specification Parameters: meaning, units, ranges
- [Keys and units](https://ai-systems-today.github.io/cubespec/reference/keys-and-units/) — canonical parameter keys and SI units
- [CSV schemas](https://ai-systems-today.github.io/cubespec/reference/csv-schemas/) — CSV import/export schemas
- [Glossary (EN)](https://ai-systems-today.github.io/cubespec/reference/glossary-en/) / [Γλωσσάρι (GR)](https://ai-systems-today.github.io/cubespec/reference/glossary-gr/) — bilingual glossary
- [Overview](https://ai-systems-today.github.io/cubespec/manual/00-overview/) — high-level overview
- [Concept primer](https://ai-systems-today.github.io/cubespec/manual/concepts-doe-monte-carlo-sobol/) — 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 software and thesis bundle are
archived on Zenodo under the concept DOI
[10.5281/zenodo.22060115](https://doi.org/10.5281/zenodo.22060115)
(which always resolves to the latest version).

---

## Citation

Use [`CITATION.cff`](https://github.com/ai-systems-today/cubespec/blob/main/CITATION.cff) —
GitHub renders a *Cite this repository* button automatically. Cite the
concept DOI [10.5281/zenodo.22060115](https://doi.org/10.5281/zenodo.22060115)
for "all versions", or the version DOI of the release you used (v0.1.3 =
[10.5281/zenodo.22060116](https://doi.org/10.5281/zenodo.22060116)).

---

## License

MIT — see [`LICENSE`](https://github.com/ai-systems-today/cubespec/blob/main/LICENSE).
