Synthetic Demonstration · Decision Support Only · Not validated against real plant data
"The synthetic model is a development and demonstration environment, not a calibrated representation of any specific cement plant." — PRD v1.1.1 §21.5, required standing statement (
src/labels.py:38)
A self-contained demonstration of the full path from a physics-reasoned synthetic cement plant simulation through data generation, ML models and constrained optimization to an operator-facing digital-twin dashboard. It exists to show the architecture and the interfaces working end to end before any real plant is involved.
What it is not. It is not connected to a plant, it does not read an instrument, and it writes no
setpoint. Every number it displays comes from its own simulation. configs/tag_mapping.yaml is
deliberately empty (sources: {}), and RealPlantDataProvider exists only as a documented stub whose
fourteen data methods raise NotImplementedError with an explanation of what each would need
(src/digital_twin/real_plant.py). Nothing here has been validated against real plant data.
Python 3.11+ (pyproject.toml).
pip install -r requirements.txt
python app.py # builds reports/task6_dashboard.html and opens it
python app.py --view B --skip-models # kiln twin only, no model layer (fast)
python app.py --view A --view G --theme light --no-browser
python -m pytest -q # test suiteUseful flags (python app.py --help): --out PATH, --view ID (repeatable, A–J or key),
--scenario NAME, --seed N, --advance MINUTES, --theme {dark,light}, --no-animate,
--replay, --skip-models, --no-browser.
The output is a single self-contained HTML file — no server, no external assets, no network calls.
Measured on one developer machine (not a specification): a warm full build ≈ 11.2 s dominated by
the model layer, --skip-models ≈ 0.35 s, one twin view rendered in ≈ 0.004 s, output ≈
25 KB.
A overview · B kiln twin · C kiln process · D clinker cooler · E mill twin ·
F mill separator · G energy · H AI prediction & anomaly · I what-if · J optimization.
H, I and J need the model layer, so they are unavailable under --skip-models.
app.py dashboard entry point (CLI above)
src/simulation/ seeded synthetic plant: dynamics, delays, disturbances, sensors
src/process_models/ kiln + mill mass/energy balances
src/data_generation/ dataset builders; src/data_processing/ quality report (FR-13)
src/features/ leakage-safe feature engineering
src/models/ Model A (prediction), src/anomaly_detection/ Model B
src/optimization/ Model C: constrained recommendation with envelope + OOD gates
src/digital_twin/ the DataProvider seam, view-models, layout, the real-plant stub
src/visualization/ rendering; src/schema.py the 62-row tag contract; src/labels.py fixed wording
configs/ all tunable constants (every presentation number tagged ASSUMPTION)
docs/ PRD, architecture notes, factory data requirements
tests/ pytest suite: physics conservation, causality, leakage, provider contract, UI
- The core simulation, data, model and optimization layers (Tasks #1–#5) are complete and covered by the test suite.
- The dashboard layer (Task #6) is substantially complete at the static-export level: all ten
A–J views have a validated view-model payload and a renderer — the animated SVG twin for
B/E, designed HTML screens for A, C, D, F, G, H, I, J — plus the Factory Presentation Mode
overlay (
--view P, PRD §29). What remains open is recorded indocs/PROJECT_STATE.md: the PRD §17 non-lettered views (Time-Series Explorer, Model Performance, Data Quality, Factory Data Requirements) and PRD §18.1 trend sparklines. - The dashboard is a static HTML export, not a live server:
app.pywrites one self-contained file. No refresh loop, no click interactivity — seedocs/DEMO_GUIDE.md§0.1. - The PRD §25 Colab notebook exists at
notebooks/00_cement_digital_twin_demo.ipynb: the twelve §25 cells in order plus the five §28 demos as single re-runnable cells in its section 11 — thin orchestration over the importablesrc/package (NFR-7). Seedocs/COLAB_NOTEBOOK_IMPLEMENTATION_REPORT.md. - Known architectural notes and deliberate non-fixes are listed in
docs/ARCHITECTURE.md.
Short version: supply data, then recalibrate, then retrain, then validate — in that order. The
substitutability seam is one class. DataProvider (src/digital_twin/provider.py) is a 15-method
abstract contract; SyntheticDataProvider implements it today and a real plant would be a second
implementation behind the same contract, so nothing above the provider changes (FR-14).
- Map your tags. Fill in
configs/tag_mapping.yamlwithcanonical_name: your_plant_tagper connection profile (csv/sql/opcua/historian/dcs/scada). The concrete tag list — 56 requestable tags across 8 process units, with units, roles and importance — isdocs/FACTORY_DATA_REQUIREMENTS.md, generated from the samesrc/schema.pythe simulator writes against. - Implement the adapter. Fill in the fourteen
RealPlantDataProvidermethods. Each one already documents what data it needs and what degrades without it;capabilities()lets every panel degrade rather than crash. - Assess quality. Re-run the FR-13 data-quality report against the real export. This is the only step of the transition this repository can perform today.
- Recalibrate. Every engineering constant, delay and loss fraction in the simulation is a
documented
ASSUMPTION(SIMULATION_ASSUMPTIONS.md, NFR-8). Recalibrating them needs plant measurements — notably fuel LHV lab results and step-test logs, neither of which any historian tag can substitute for. - Retrain and validate. Models A/B/C are fitted to the simulation. Retrain on plant data through the unchanged interfaces, then validate against held-out plant measurements — not against the simulation.
- Operator validation, then deployment. PRD §21.4 and §30. Out of scope for this build.
A populated tag mapping makes real data readable. It does not make a synthetically-trained model correct on that plant. Steps 3–6 are a project, not a config change.
- The system writes no setpoint and closes no loop. Outputs are labelled AI Recommendation
under Decision Support Only; "Automatic Control Command" is forbidden vocabulary and is asserted
against in code (
src/labels.py:29-33, FR-16, PRD §30). - Savings are reported as simulated: "Simulated saving from a synthetic model - not a guaranteed
real-world saving" (
src/labels.py:75). - Uncertainty is an ensemble spread plus a categorical
HIGH/MEDIUM/LOWquality. There is no confidence-percentage field anywhere in the payload (FR-23, AC-18). - Where evidence does not separate the readings — sensor drift being the standard case — the display reads "Evidence inconclusive", not a diagnosis.
- Operating points outside the training envelope are flagged
OUTSIDE_ENVELOPE, and "No safe recommendation found" is a valid outcome. Constraints are never relaxed to produce advice.
| File | What it covers |
|---|---|
docs/PRD_Synthetic_Cement_Digital_Twin.md |
The specification (v1.1.1): requirements, acceptance criteria, all engineering sections |
docs/ARCHITECTURE.md |
Layering, the provider seam, provenance channels, known notes and deliberate non-fixes |
docs/FACTORY_DATA_REQUIREMENTS.md |
The tag-level data request a factory would answer (AC-9) |
SIMULATION_ASSUMPTIONS.md |
Every engineering constant, its source, and what measurement would replace it |
MODEL_CARD.md |
Models A/B/C: data, features, metrics, and their validation limits |
Synthetic Demonstration · Decision Support Only · Not validated against real plant data