REPOSITORY OVERVIEW

Live repository statistics

★ 120Stars

⑂ 45Forks

◯ 10Open issues

◉ 120Watchers

README preview

AI-powered Digital Twins with Calibrated Uncertainty

Composable, physics-informed digital twins with calibrated uncertainty and leakage-free validation by default — lightweight, CPU-first.

Overview

Otwin builds AI-powered digital twins that stay physics-informed: you bring the physical model structure you know, Otwin estimates the rest from data, attaches calibrated uncertainty, and validates without leakage.

In engineering we have three modelling options:

Otwin works on the physics-informed side — from white-box to grey-box. The black-box end is where current latent-state world models live; Otwin is their observable-state, physics-grounded counterpart — the digital-twins-world-models intersection it targets.

Physical Models or World Models? Black-box models are accurate at interpolation — predicting inside the range of data they have seen — but pushed beyond that data (long horizons, or operating conditions never seen in training) they drift and break physical laws. The physical structure keeps long-range forecasts physically valid; the calibrated interval says how much to trust each one — a stated 90% interval is checked to really hold ~90% of the time.

Modeling approach: from white-box to grey-box

You choose how much first-principles structure you can write down. Everything after that choice is the same workflow.

Otwin builds white-box and grey-box digital twins: choose a model structure (first-principles or empirical), then one workflow — estimate, quantify uncertainty, validate.

If you can...	Model structure	Example
write the system's dynamics from physics	First-principles (port-Hamiltonian)	water tank, DC motor, pumped-hydro storage
only state a coarse trend it follows	Empirical law + estimated residual	battery State-of-Health, fatigue

The first-principles models describe a system as components that exchange energy through ports — so conservation and passivity hold by construction, not by hope. Battery State-of-Health sits at the empirical end: a degradation curve, not an energy-conserving system. Confusing the two is the most common conceptual error.

The Otwin workflow

Installation

Core (numpy + scipy only):

# For now, until first release:
pip install git+https://github.com/groundlens-dev/otwin.git@v2

With optional extras:

pip install "otwin[torch]"    # Learned first-principles model (PortHamiltonianNN)
pip install "otwin[gp]"       # GP-PHS (Gaussian-process uncertainty)
pip install "otwin[viz]"      # matplotlib + seaborn + plotly visualization
pip install "otwin[examples]" # Everything to run examples/ (cvxpy, pandas, sklearn, seaborn)
pip install "otwin[dev]"      # Testing / linting / typing / docs

Requirements:

Python ≥ 3.10
Runs on CPU (no GPU required)
Works on a laptop

Get started

import numpy as np
from otwin import DigitalTwin, evaluate
from otwin.systems import water_tank   # a ready-made first-principles model

# ── First-principles catalog ──────────────────────────────────────────────
# Available now:
#   water_tank          fluid system (draining tank)
#   mass_spring_damper  mechanical oscillator
# Build your own from energy H, interconnection J, dissipation R, input g:
#   from otwin.systems import PortHamiltonianSystem   # conservative/dissipative system
#   from otwin.systems import IrreversiblePHS         # adds entropy production
#
# Roadmap (named structures, not yet importable):
#   rc_circuit      electrical RLC          heat_exchanger  thermal mass
#   reactor         chemical reactor (CSTR) degradation     empirical fade law
# ──────────────────────────────────────────────────────────────────────────

# 1. Choose a model structure: a first-principles (port-Hamiltonian) system
twin = DigitalTwin(model=water_tank())

# 2. Forecast from an initial state x0 over a time grid t with inputs u
x0 = np.array([1.0])
t  = np.linspace(0, 10, 100)
u  = np.zeros((100, 1))
fc = twin.forecast(x0, t, u)
print(fc["x"].shape)            # (100, 1)

# 3. Validate with a leakage-free protocol + mandatory baselines
report = evaluate(twin, data, protocol="rolling_origin")
print(report)                   # skill score vs naive baseline, first

Calibrated uncertainty (ensembles / GP) and the full empirical-law workflow (empirical prior + estimated residual + conformal bands) are shown end-to-end in examples/battery_soh.

First-principles models: port-Hamiltonian

Black-box models (neural ODEs, LSTMs, generic regression) learn unstructured mappings. They interpolate well, but on long horizons or unseen operating conditions they drift, violate conservation laws, and produce unphysical behavior.

A port-Hamiltonian model fixes the structure. The system is described as components that exchange energy through ports:

$$\dot{x} = \bigl(J(x) - R(x)\bigr),\nabla H(x) + g(x),u, \qquad y = g(x)^{\top},\nabla H(x)$$

where:

$J(x) = -J(x)^{\top}$ (skew-symmetric $\rightarrow$ lossless interconnection)
$R(x) \succeq 0$ (positive semidefinite $\rightarrow$ dissipation)
$H(x)$ is the energy / storage function

Power balance (provable by construction):

$$\frac{dH}{dt} = -,\nabla H^{\top} R,\nabla H + y^{\top}u ;\leq; y^{\top}u$$

With $u = 0$, energy is non-increasing. No energy-creating drift, by algebra.

When you estimate a PortHamiltonianNN from data, the network architecture enforces J skew and R PSD regardless of weights. The guarantee is structural — this is the white-box end of grey-box.

Empirical-law models: degradation

When a system only degrades — capacity fade, wear, fatigue — there is no energy function to conserve. otwin uses a transparent trend law as the model structure, estimates a bounded residual on top, and quantifies uncertainty with horizon-aware conformal intervals:

$$\widehat{\mathrm{SoH}}(n) = \mathrm{SoH}_0,e^{-a n} + g(n)$$

(empirical fade-law prior + estimated residual)

$$\bigl[,\ell(n),,u(n),\bigr] = \widehat{\mathrm{SoH}}(n) \pm z,\sigma(n), \qquad \sigma(n) = s_0 + s_1,(n - n_0)$$

(band that widens with the forecast horizon)

Same workflow as the first-principles end — only the model structure is lighter (grey-box leaning empirical). This is demonstrated end-to-end on the NASA battery fleet in examples/battery_soh (State-of-Health and Remaining-Useful-Life forecasting). A reusable empirical-law primitive (otwin.systems.degradation) is on the roadmap; today the structure lives in the worked example.

What you can model

First-principles (port-Hamiltonian / structured state-space) models:

Mechanical systems (mass-spring-damper, robotics, vehicles)
Electrical circuits (RLC, power systems)
Thermal systems (heat exchangers, buildings)
Chemical reactors (CSTR with thermodynamics, via irreversible PHS)
Fluid systems (tanks, pipelines)
Coupled multi-physics systems (via port composition)

Empirical-law models: aging and degradation (battery State-of-Health, fatigue, wear, corrosion).

Out of scope (this is the black-box end):

High-dimensional pixel / video world models
Systems with no usable state-space or trend structure
Workflows requiring a GPU-vendor stack (Omniverse, etc.)

Key features

First-principles core (white-box structure)

PortHamiltonianSystem: analytic PHS (energy, interconnection, dissipation)
IrreversiblePHS: entropy production with σ ≥ 0 (second-law guarantee)
PortHamiltonianNN: learned dynamics with enforced structure (J skew, R PSD)
Structure-preserving integrators: implicit-midpoint, discrete-gradient (optional)

Calibrated uncertainty

Deep ensembles for PortHamiltonianNN (real variance, not a constant)
GP-PHS (optional [gp]): Gaussian process with a structure-preserving kernel
Calibration diagnostics: PIT histograms, coverage curves, recalibration
Uncertainty is validated for coverage, not assumed

Leakage-free validation (by default)

Temporal splits (rolling-origin, holdout) — the default for forecasting
Mandatory baselines (persistence, drift, seasonal-naive)
Skill score (model error ÷ baseline error) as the headline metric
Metrics: RMSE, MAE, nRMSE, MASE, Theil's U, CRPS, PICP, MPIW
R² is not a headline metric (use MASE / Theil's U for forecasting)
Random splits are opt-in with a loud warning ("measures interpolation, not forecasting")

Composability (physical networks)

Port interconnection (connect twins through shared ports)
Modular: swap analytic ↔ learned ↔ hybrid model structures
Combine subsystems into multi-physics twins

Engineering quality

Fully typed (py.typed, mypy --strict clean)
Gating CI (tests / lint / type / coverage ≥ 85% all enforced, no swallowing)
CPU-first (every example runs in seconds on a laptop)
Dependency discipline (core = numpy + scipy; optional extras clearly separated)
Generated benchmarks (every number reproducible, never hand-typed)

Examples

See examples/ for full runnable code.

1. Water tank (first-principles, port-Hamiltonian)

ALGORITHMICALLY RELATED

Similar Open-Source Projects

Selected from shared topics, language and repository description—not editorial ratings.

awsdocs /

aws-doc-sdk-examples

★ 10.4K

Welcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.

Recently updatedPopularActive repository

JavaApache-2.0#aws#cpp#documentation#dotnet

⑂ 5.8K forks◯ 146 issuesUpdated today

View details View on GitHub ↗

NELSONZHAO /

zhihu

★ 3.5K

This repo contains the source code in my personal column (https://zhuanlan.zhihu.com/zhaoyeyu), implemented using Python 3.6. Including Natural Language Processing and Computer Vision projects, such as text generation, machine translation, deep convolution GAN and other actual combat code.

Recently updatedActive repositoryHas homepage

Jupyter NotebookNo license#autoencoder#convolutional-neural-networks#deep-learning#gan

⑂ 2.1K forks◯ 32 issuesUpdated 1 day ago

Project homepage ↗