A reproducible synthetic continuity laboratory for datacenter power systems.
Read the twelve course lessons · Reference results and sources · About the author
How long can a 1 MW IT load ride through a utility outage on 100 kWh of stored battery energy?
In the five-minute walkthrough, predict the battery's ride-through, deliberately run the scenario, then explain the result from its energy ledger. The example uses 100 kWh × 0.90 battery-discharge efficiency × 0.95 distribution efficiency = 85.5 kWh delivered to IT. At 1,000 kW, that is 307.8 seconds from the outage, which starts at 300 s elapsed. Battery depletion is therefore recorded at 607.8 s elapsed. Charging is disabled and the generator is failed.
Open the five-minute guided experiment → · Challenge yourself with 50 kWh · Read the exact inputs and equations
Halving the opening reserve to 50 kWh gives 42.75 kWh delivered to IT: 153.9 s from the outage and depletion at 453.9 s elapsed. Ride-through is a duration counted from the 300 s outage boundary; depletion is an elapsed event timestamp.
This is a teaching and research tool for datacenter engineers learning electrical continuity. It is a narrow, synthetic, uncalibrated model—not a production reliability analysis. Detailed model boundaries and validation status are below.
v1.0.0 packages the complete teaching workflow: guide, twelve lessons, eighteen presets, reports and reproducibility evidence. The CI badge follows main; check the exact released commit's results before relying on them. See release readiness.
The pictures below are screenshots of the actual guided interface. Their numbered captions name the corresponding action in the walkthrough.
01 · Predict. Choose the 100 kWh starting example or 50 kWh challenge. Enter seconds from the outage at 300 s—not an elapsed timestamp. No result is shown until you choose Run 1 MW scenario.
02 · Run. The result reports ride-through separately from depletion time, shows the equation, and breaks out requested, served, and unserved IT energy during the outage window.
03 · Explain. Export the complete JSON run, inspect its inputs and hash, or optionally request a Python comparison. Report and reserve-sensitivity tools are available after the completed result.
Watch the captioned 60-second tour in the evidence hub → · Tour transcript and reproduction notes
- Open the advanced energy workspace to inspect the full topology, replay events, change bounded assumptions, and export runs.
- Open the existing 50 MW outage case. It is a synthetic aggregate electrical case, not a GPU-throughput or grid-adequacy model.
- Start the 12-lesson course, or read its course notes.
- Visit the evidence hub for source records and reproducibility material.
- Browse the tutorials, scenario catalog, unit-aware glossary, and contribution ideas.
The current source includes 18 named scenarios, four illustrative facility profiles, the twelve lessons, and on-demand reports and sensitivity tools. Ratings, demand, event timing, rates, and efficiencies are explicit synthetic inputs. The roadmap separates capabilities in the release from work still planned or conditional.
Go beyond the outage timeline with the DC-link EMT lesson: configure an ideal RLC circuit, replay its voltage sag, inspect signed current and compare JavaScript with Python.
The power-dynamics studio adds five configurable Python studies: converter load steps, oscillation modes, a synthetic load spectrum, phase-model versus QSS response, and a modified nine-bus network. Color-coded diagrams, plots and JSON/CSV exports connect every result to its applied inputs. Its scientific runtime loads only when requested.
Read the EMT equations · Study catalog and reproduction commands. These additions are available on the current website and source; historical v1.0.0 assets remain unchanged.
The guide follows lesson 3's exact scenario recipe: it starts from the reference-site inputs, then assigns lesson ID/name and source metadata, disables charging, and sets the initial reserve to 100 or 50 kWh. The canonical case records those inputs and derives the results independently. A direct generator_failure preset run happens to produce the same 100 kWh numeric event time because the battery starts full, but its scenario ID, metadata, charging limit, input hash, and run ID are different.
The tracked release evidence index links the canonical scenario/run JSON, reports, manifest, and receipt. To regenerate and verify the packet from the tagged release source:
git clone https://github.com/mohammadrezwankhan/datacenter-twin-lab.git
cd datacenter-twin-lab
git checkout v1.0.0
python scripts/build_evidence.py --output outputs/evidence
python scripts/build_evidence.py --verify outputs/evidenceThe script requires a fresh output directory under outputs/ and prints the manifest digest. For an inspectable checked-in result, use the tracked evidence index and receipt.
If you want the separate base-preset example, these commands run it directly:
python -m datacenter_twin simulate --preset generator_failure
python -m datacenter_twin simulate --preset generator_failure --format html --output outputs/failure.html
python -m datacenter_twin sweep --preset generator_failure --parameter battery_initial_kwh --values 0 50 100 --format markdownChoose a new output path if it already exists, or explicitly add --force. The preset allows charging; at 50 kWh it gives 478.2675 s elapsed, rather than the guided lesson's 453.9 s elapsed with charging disabled. The sensitivity guide explains the distinction.
The quickstart installs the published v1.0.0 wheel with a pinned SHA-256, using uv or Python/pip. It includes the CLI, local dashboard, eighteen presets and research evidence, so no Git or Node setup is needed for that route. A Python 3.12+ source checkout remains available for development and running the full tests. Earlier alpha assets retain their original contents.
The workflow is configured to test each push to main and each pull request. Its matrix targets Python 3.12 and 3.14 on Windows and Linux; the Playwright Chromium browser journeys run on Ubuntu with Python 3.12. These are per-commit checks, not a blanket claim that every commit or this release has passed. Read the release scope page, evidence packet instructions, and benchmark method for what is measured and how to reproduce it.
The project uses deterministic quantities, unit-labelled outputs, explicit unknowns, stable input hashes, event logs, and energy ledgers. CI and local reproductions establish software behavior for these synthetic fixtures; they do not establish engineering performance or physical accuracy.
For local verification from the repository root:
python -m unittest discover -s tests -v
npm --prefix apps/web ci --ignore-scripts
npm --prefix apps/web run build
python scripts/prepare_browser_demo.py
npm --prefix apps/web run test:engine
npm --prefix apps/web run build:demo
npm --prefix apps/web run test:demoBrowser and wheel verification details are in the quickstart. The adding-a-scenario guide describes how to propose a small, independently checkable case. No test, benchmark run, automated audit, or maintainer-produced evidence packet counts as an independent external review.
Start with contribution guidance, beginner contribution ideas, support, or the roadmap. Participants follow the Code of Conduct. Use GitHub Discussions to share a reproducible result or review.
If you find this project useful, you can support continued open development on Ko-fi:
For a task-based comparison with OpenDC and PyPSA, see Choosing a simulator.
This is a deterministic, local-first teaching simulator for one aggregate IT load. The current model covers synthetic utility and generator availability, finite stored energy, conversion losses, distribution-path limits, shared-domain events, deterministic recovery, replay, and exact energy accounting. The 50 MW example scales electrical demand and battery energy; it does not predict GPU throughput, grid adequacy, equipment selection, or measured site behavior.
The model does not establish facility calibration, protection coordination, AC transients, cooling behavior, workload queues or throughput, generator ramp/cooldown/fuel dynamics, transfer and switching transients, impedance-based load sharing, harmonics, short-circuit or arc-flash studies, reliability probabilities, Tier or service-level claims, certification, physical controls, or physical safety. No facility measurements or validation dataset were used.
| You can use it to | Model boundary |
|---|---|
| Compare synthetic utility, generator, battery, and path failures | Assumed ratings and efficiencies; no facility calibration |
| Reproduce event times, energy ledgers, and sensitivity reports | Electrical continuity only; no AC transients, protection, cooling, or workload prediction |
| Learn, inspect, and share a calculation locally | No physical controls, certified uptime, or facility safety assessment |
The 1 MW reference fixture uses 1,000 kW IT demand, 1,800 s duration, 0.95 distribution efficiency, 100 kWh initial and maximum battery energy, 0.90 discharge efficiency, a 30 s generator start delay, 700 kW path capacities, and a fictional USD 0.10/kWh tariff. The 50 MW case scales demand and battery energy to 50,000 kW and 5,000 kWh while preserving those ratios. These are synthetic inputs, not selected-equipment ratings, live prices, a benchmark, a certification, legal-compliance evidence, or real-site calibration.
Schema-1 PUE and energy planning is separate from schema-2 electrical topology; neither model silently infers the other. Unknown costs and unavailable quantities remain explicit. The dated NVIDIA/model/AWS/Azure/OCI identifiers and one dated Azure East US retail meter are source-backed assumptions, not live feeds, account quotes, capacity allocations, or performance equivalence. Germany, Virginia, and India references are screening pointers, not complete jurisdiction packs or legal advice; India screening must consider the CEA's listed 2026 amendment.
The browser demo has no shared simulation backend or client analytics; its optional Python comparison loads on request. The API binds to loopback. No account, GPU, cloud resource, physical control, shared deployment, database, login, tenant isolation, persistent audit, FAT/SAT, or facility telemetry is introduced. Cooling, workload throughput, calibrated alarms, live telemetry, and predictive models remain planned or unvalidated. A 5,000-star aspiration has no validated timeline and is not evidence of model accuracy or adoption.
Local and CI checks cover the core/API suite, frontend format/type/build, installed-wheel verification, local dashboard journeys, browser/Python journeys, and browser/native equality for synthetic presets. Reference-case timing measures software execution on one local machine; it does not establish scale targets or physical accuracy. These checks are not an independent external review or formal security audit. See the external review protocol for the requested independent reconstruction.
The public source tree excludes private manuals, planning references, and private repository history. Do not add private manuals, extracted private text, credentials, customer traces, or licensed standards text.
Original code and synthetic fixtures use Apache-2.0. See NOTICE, synthetic provenance, and browser runtime licenses. SOURCE-MANIFEST.json identifies the original v0.2.0a0 snapshot, not later versions. Citation metadata accompanies the project; cite the exact release or commit used.
Earlier alpha and candidate assets remain historical and unchanged. Version 1.0.0 identifies the teaching-software release. Independent external reproduction remains outstanding; no facility validation, award or outside endorsement is claimed.