Profile
Back to NewsBack
GitHub Trending 13 min
Reader Mode
mohammadrezwankhan/datacenter-twin-lab: Explore data center power continuity, energy ledgers & infrastructure assumptions through reproducible synthetic models.

mohammadrezwankhan/datacenter-twin-lab: Explore data center power continuity, energy ledgers & infrastructure assumptions through reproducible synthetic models.

13 hours ago

!Datacenter Twin Lab — project overview

Investigate synthetic datacenter power interruptions with a Python continuity model, explicit battery reserves, and inspectable energy ledgers.

Install and run · Canonical case · Python source · Evidence · Limits


!Datacenter Infrastructure Lab: original vector system illustration

Datacenter Twin Lab combines a deterministic Python continuity engine, a 24-lesson browser course (12 continuity + 12 Infrastructure Engineering), and 18 synthetic scenario presets. One EMT study and five power-dynamics studies are separate learning tracks. The four-module offline dashboard below is a companion, not the full course.

Open the 24-lesson course · Run the guided 1 MW experiment · Inspect verified inputs · Offline four-module companion

The companion's lesson configuration and schema describe that separate dashboard; they are not the source of the 24-lesson course catalog.

Previous animations

Open the previous-animation gallery · Local gallery

Earlier animated artwork, waveform demos, and original interactive experiences are linked alongside the current animations.

Begin with the canonical battery question

  1. Open the guided experiment, then predict how long 100 kWh will supply a fixed 1,000 kW IT load after an outage.
  2. Run the charging-disabled, failed-generator case: 100 kWh × 0.90 × 0.95 = 85.5 kWh delivered, or 307.8 seconds of ride-through.
  3. Compare the prediction with the energy ledger. The outage begins at 300 s elapsed, so battery depletion occurs at 607.8 s elapsed. Check the exact scenario or reproduce it in Python.
The figures are deterministic results of declared synthetic inputs, not facility calibration, certified uptime, or permission to control equipment. For the separate offline companion, open docs/index.html, choose Module 1, change a slider and export the reported configuration.

System topology and model boundaries

!Datacenter ups topology

Conceptual supply topology; no source-specific reliability calculation.

Motion is optional; the vector topology remains readable with reduced motion enabled.

Optional offline companion: four-module learning path

| Module | Investigation | Approximate time | |---|---|---:| | 1. Build an electrical load ledger | Distinguish IT power from facility overhead and from stored energy. | 12 min | | 2. Scale the population while holding efficiency | Identify which outputs scale with server count and which are ratios. | 15 min | | 3. Stress an ambient and efficiency assumption | Quantify a cooling-power sensitivity without inventing a reliability result. | 15 min | | 4. Connect the screen to continuity evidence | Prepare a bounded infrastructure comparison and choose the native follow-up study. | 18 min |

Who this is for: Datacenter engineers, infrastructure students, and researchers examining electrical continuity assumptions.

Continue into the implementation

Install from PyPI

The Python core requires Python 3.12 or later. The first PyPI release is 2.0.1.

pip install datacenter-twin

Explore or run the source

Python 3.12+ for the dependency-free native core; the existing React/Vite workspace has its own lockfile and optional API/study dependencies.

python -m pip install .
python -m datacenter_twin simulate --preset generator_failure
python -m unittest discover -s tests -v

These commands come from the audited source revision. Runtime requirements and the project's own validation limits are documented below; the standalone browser lab does not execute these commands.

The detailed project guide below remains the source for installation, supported features, licences, and scientific limits. This presentation change does not alter the Python model, browser calculations, numerical tolerances, or Engineering HOLD.

Project documentation, installation, attribution, and existing validation

Datacenter Twin Lab

_A reproducible synthetic continuity laboratory for datacenter power systems._

Start with one battery question

Read the 24 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.

v2.0.1</a> CI on main</a> Support me on Ko-fi</a>

v2.0.0 — Infrastructure Engineering adds twelve manuscript-derived lessons, 36 assessments, separate educational models and twelve original SVG scenes to the existing guide, twelve continuity lessons, eighteen presets, reports, EMT and five dynamics studies. Publication decision and attribution; engineering HOLD remains. The CI badge follows main; check the exact released commit's results before relying on them. See release readiness.

The three steps

The pictures below are screenshots of the actual guided interface. Their numbered captions name the corresponding action in the walkthrough.

Screenshot 01: predict an outage-relative ride-through and inspect the before, outage, and recovery setup</a>

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.

Screenshot 02: compare predicted and calculated ride-through, elapsed depletion time, and the energy ledger</a>

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.

Screenshot 03: inspect the completed run's source references, assumptions, hash, and reproducible output</a>

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

Continue with another part of the lab

The current source includes 18 named scenarios, four illustrative facility profiles, 24 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.

Explore faster electrical dynamics

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.

Reproduce the canonical case

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.

Reproduce the release evidence packet

v2.0.1 was published on 2026-10-26, packaging the later odd-record spectrum correction and clean dashboard staging. Its separate evidence index, patch receipt and hash-pinned quickstart identify the checked source and artifacts. The original release recipe below remains historical and unchanged.

The historical v2.0.0 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 v2.0.0
python scripts/build_evidence.py --output outputs/evidence --revision "$(git rev-parse HEAD)"
python scripts/build_evidence.py --verify outputs/evidence

The 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. The checked-in packet has no self-referential commit hash; the release's external evidence manifest records the exact build revision. The v1.0.0 packet remains historical and unchanged.

Also run the original CLI preset

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 markdown

Choose 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 v2.0.1 GitHub wheel with a pinned SHA-256, using uv or Python/pip. It includes the CLI, local dashboard, 24 course lessons, eighteen presets and research evidence, so no Git or Node setup is needed for that route. The distribution is now named datacenter-twin; use a fresh environment when switching from the historical datacenter-twin-lab wheels because both provide the same module and CLI. A Python 3.12+ source checkout remains available for development and running the full tests. Earlier release assets retain their original contents.

Checks and evidence

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, start with the contributor setup: create an isolated Python environment, install the locked API and frontend dependencies, build the dashboard, and run the core tests and CLI smoke check.

Then follow Rebuild and verify for the browser demo. That workflow installs the scientific dependencies, fetches the hash-checked runtime wheels before preparing the browser assets, runs the engine comparisons, and installs Chromium before the browser journeys. Run both workflows from the repository root and keep TWIN_PYTHON set to the same environment throughout.

Browser 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.

Support and project references

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:

Support me on Ko-fi</a>

For a task-based comparison with OpenDC and PyPSA, see Choosing a simulator.

Assumptions and limits

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 2.0.0 is the owner-selected product milestone; planning schema 1, electrical schema 2 and historical releases are preserved. Independent external reproduction remains outstanding; no facility validation, award or outside endorsement is claimed.

Reference handbook — source review of 19 November 2026

The documentation index and readable reference handbook connect the existing tutorials to implementation, equations, interfaces, worked examples, verification evidence, maintenance and recovery. The reviewed source is d8dc3773830a397409a7a9c00a6ffed33c46fb4b; the software citation remains version 2.0.1. This documentation addition does not announce a new software release.

Start with setup and reproducibility, worked labs, or the equation derivations. The dated verification ledger separates executed local checks, historical exact-source CI, unexecuted browser/build checks and pending integration. The twelve-month plan is a set of proposals with acceptance criteria, not a release commitment.

The offline companion, aggregate continuity engine, infrastructure screens, EMT circuit and power-dynamics studies retain their separate assumptions. In particular, a zero internal energy residual, a passing software comparison or an Engineering HOLD decision is not a facility measurement or independent engineering approval.

Chat with me