Digital Twins is a Python package providing state-of-the-art algorithms for building digital twins through data assimilation. It combines simulation models with real-world observations to create accurate, real-time representations of physical systems.
A digital twin is a virtual representation of a physical system that updates in real-time using sensor data. This package provides the mathematical foundation and algorithms needed to:
- Simulate dynamic systems using continuous, discrete-time, and event-based models
- Assimilate real-world data to correct model predictions
- Estimate hidden states and parameters from noisy observations
- Visualize uncertainty and spatial distributions
- Kalman Filters: Standard, Extended (EKF), and Ensemble (EnKF) implementations
- Particle Filters: Bootstrap filter with systematic resampling for nonlinear/non-Gaussian systems
- Continuous Models: ODE solvers (Euler, RK4) for systems like the Lorenz attractor
- Discrete-Time Models: Including cellular automata and difference equations
- DEVS Models: Discrete Event System Specification for event-driven simulations
- Uncertainty visualization (confidence ellipses, particle clouds)
- Spatial distribution plots for grid-based simulations
- Real-time animation support via Jupyter widgets
pip install digital-twins-dddsgit clone https://github.com/bulentsoykan/digital-twins.git
cd digital-twins
pip install -e .pip install -e .[dev] # Includes testing and development toolsimport numpy as np
from digital_twins import KalmanFilter
# Initialize with uncertain initial state
mu0 = np.array([0.0, 0.0]) # [position, velocity]
Sigma0 = np.eye(2) * 100 # High initial uncertainty
kf = KalmanFilter(mu0, Sigma0)
# System dynamics (constant velocity model)
dt = 1.0
A = np.array([[1.0, dt], [0.0, 1.0]]) # State transition
Q = np.eye(2) * 0.1 # Process noise
C = np.array([[1.0, 0.0]]) # Observe position only
R = np.array([[1.0]]) # Measurement noise
# Simulate one step
kf.predict(A, Q) # Predict next state
measurement = np.array([5.0]) # Receive sensor data
kf.update(measurement, C, R) # Correct with measurement
print(f"Estimated state: {kf.mu}")
print(f"Uncertainty: {kf.Sigma}")from digital_twins import BootstrapParticleFilter
# Initialize 1000 particles
N_particles = 1000
initial_particles = np.random.randn(N_particles, 2) # Random initial distribution
pf = BootstrapParticleFilter(N_particles, initial_particles)
# Nonlinear dynamics
def f(x, u):
return np.array([x[0] + 0.1*np.sin(x[1]), x[1] + 0.1])
def g(x):
return x[0]**2 # Nonlinear measurement
# Run filter
pf.predict(f, process_noise_std=np.array([0.1, 0.1]))
pf.update(y_md=2.5, g_func=g, sensor_noise_std=0.5)
mean_state, std_state = pf.estimate_state()
print(f"Estimated state: {mean_state} ± {std_state}")from digital_twins import ContinuousSimulator, LorenzSystem
# Create Lorenz attractor model
model = LorenzSystem(sigma=10.0, rho=28.0, beta=8.0/3.0)
simulator = ContinuousSimulator(model, method='rk4')
# Run simulation
initial_state = np.array([1.0, 1.0, 1.0])
t_history, x_history, y_history = simulator.simulate(
t_start=0.0,
t_end=50.0,
dt=0.01,
x0=initial_state
)
# x_history contains the chaotic trajectoryThe package includes comprehensive Jupyter notebooks demonstrating:
- Continuous Systems: Lorenz attractor visualization
- Discrete-Time Models: Cellular automata patterns
- DEVS Models: Traffic light coordination
- Kalman Filters: Interactive gain visualization
- Particle Filters: Bootstrap filter basics
- Advanced Topics: Joint state-parameter estimation, spatial tracking
# Install Jupyter if needed
pip install jupyter
# Navigate to notebooks directory
cd notebooks/
# Start Jupyter
jupyter notebookdigital-twins/
├── src/digital_twins/
│ ├── assimilation/ # Data assimilation algorithms
│ │ ├── kalman.py # Kalman filter variants
│ │ └── particle.py # Particle filters
│ ├── models/ # Simulation models
│ │ ├── continuous.py # ODE-based models
│ │ ├── discrete_time.py # Difference equations
│ │ └── devs.py # Event-driven models
│ └── visualization/ # Plotting utilities
├── notebooks/ # Interactive tutorials
├── tests/ # Unit tests
└── data/ # Example datasets
This package implements algorithms from modern data assimilation theory:
- Kalman Filtering: Optimal state estimation for linear Gaussian systems
- Extended Kalman Filter: First-order linearization for nonlinear systems
- Ensemble Kalman Filter: Sample-based covariance estimation
- Particle Filtering: Sequential Monte Carlo for arbitrary distributions
The mathematical formulations follow standard texts in data assimilation and state estimation.
Digital twins built with this package can be applied to:
- 🚗 Transportation: Traffic flow estimation and prediction
- 🔥 Wildfire Tracking: Real-time fire spread monitoring
- 🏭 Manufacturing: Production line optimization
- 🌊 Environmental Monitoring: Ocean/atmosphere modeling
- 📦 Supply Chain: Inventory and logistics optimization
- 🤖 Robotics: Sensor fusion and SLAM
We welcome contributions! Please see our GitHub repository for:
- Bug reports and feature requests
- Pull request guidelines
- Development setup instructions
Run the test suite:
pytest tests/With coverage:
pytest tests/ --cov=digital_twinsIf you use this package in your research, please cite:
@software{digital_twins,
author = {Soykan, Bulent},
title = {Digital Twins: Data-Driven Dynamic Simulation},
year = {2026},
url = {https://github.com/bulentsoykan/digital-twins}
}This project is licensed under the MIT License - see the LICENSE file for details.
Bulent Soykan
- Website: bulentsoykan.com
- GitHub: @bulentsoykan
- LinkedIn: Bulent Soykan
This package was developed as a companion to research in digital twin technology and data assimilation methods. Special thanks to the scientific computing and data assimilation communities for their foundational work.
