Simulate the driver. Model the vehicle. Generate telemetry.
DriveTwin is an experimental stateful simulation framework for exploring how drivers, vehicles, environments, and telemetry can be modeled as an evolving system.
- Python 3.10 or newer
- Git
DriveTwin currently uses only Python's standard library for its core simulation framework.
No external Python packages are required for the current simulation engine.
git clone https://github.com/harisrana-dev/DriveTwin.git
cd DriveTwinpython -m venv .venv
.venv\Scripts\Activate.ps1If PowerShell prevents script execution, the environment can also be activated using:
.venv\Scripts\activate.batpython3 -m venv .venv
source .venv/bin/activateThe Python packages are located inside the backend/ directory.
Before running any module, change into the backend directory:
cd backendThis is important because the simulation imports packages such as:
digital_twin
simulation
analytics
from the backend package root.
The standard execution pattern is therefore:
DriveTwin/
│
├── README.md
├── requirements.txt
├── .gitignore
│
└── backend/
├── digital_twin/
├── simulation/
├── analytics/
└── tests/
Then:
cd backend
python -m <module>Runs a short deterministic simulation without waiting for real-time delays.
cd backend
python -m digital_twin.runtime.demo --fast --ticks 5This executes five simulation ticks and displays a concise summary of the simulation results.
Runs the simulation continuously with approximately one real-time tick per second.
cd backend
python -m simulation.continuous_loopThe simulation creates multiple vehicles and continuously prints:
- vehicle telemetry
- speed
- RPM
- gear
- fuel level
- engine temperature
- engine load
- battery voltage
- odometer
- brake health
- tyre health
- driver behavior analytics
- vehicle health analytics
- fuel efficiency
- detected events
Press:
Ctrl+C
to stop the simulation gracefully.
Runs a 30-tick driving behavior demonstration.
cd backend
python -m tests.demo_drivingDriveTwin currently uses executable validation scripts rather than a formal test runner.
cd backend
python -m digital_twin.validate_full_telemetry_pipelinecd backend
python -m tests.validate_vehicle_controllercd backend
python -m tests.inspect_one_tickcd backend
python -m tests.inspect_ten_ticksThe project does not currently contain a formal pytest or unittest test suite.
The validation scripts inside backend/tests/ are executable Python modules that use:
if __name__ == "__main__":and can be run directly using the commands documented above.
There is currently no:
pytest.iniconftest.py- configured test runner
The existing validation scripts are intended to verify and inspect simulation behavior during active development.
DriveTwin is a Python-based simulation framework for modeling the interaction between a driver and a vehicle over time.
Instead of generating isolated random telemetry values, the simulation maintains a persistent vehicle state that evolves from one simulation tick to the next.
A simplified simulation loop looks like this:
┌───────────────┐
│ Driver │
│ Behavior │
└───────┬───────┘
│
▼
┌───────────────┐
│ Decision │
│ Intent │
└───────┬───────┘
│
▼
┌───────────────┐
│ Vehicle │
│ Actuation │
└───────┬───────┘
│
▼
┌───────────────┐
│ Physics │
│ State Evolution│
└───────┬───────┘
│
▼
┌───────────────┐
│ Vehicle State │
│ Speed • RPM │
│ Fuel • Health │
└───────┬───────┘
│
▼
┌───────────────┐
│ Virtual Sensors│
└───────┬───────┘
│
▼
┌───────────────┐
│ Telemetry │
└───────────────┘
The goal is not to reproduce the exact behavior of a specific manufacturer's ECU or vehicle.
The goal is to build a consistent, explainable, stateful environment for experimenting with automotive systems and telemetry.
A real vehicle does not become a completely different vehicle every second.
Its current state is influenced by its previous state.
For example:
Tick N
│
├── Speed: 42 km/h
├── RPM: 2,100
├── Gear: 3
├── Fuel: 78%
│
▼
Driver applies throttle
│
▼
Vehicle controller computes actuation
│
▼
Physics updates the vehicle
│
▼
Tick N + 1
│
├── Speed: 47 km/h
├── RPM: 2,450
├── Gear: 3
├── Fuel: 77.98%
This creates a continuous chain of cause and effect:
Previous State → Decision → Actuation → Physics → New State
That state can then be observed through virtual sensors and converted into telemetry.
Drivers are modeled using behavioral profiles.
Current profiles include:
CAUTIOUSSTANDARDAGGRESSIVEECO_FOCUSED
A driver profile influences the type of driving intent generated by the Decision Layer.
Driver
│
├── Behaviour Profile
├── Experience Level
├── Fatigue
└── Operational State
│
▼
Driving Intent
The Driver entity stores the driver's state.
The Decision Layer determines what the driver intends to do.
The Decision Layer translates the current situation into a driving intent.
It considers information such as:
- current vehicle speed
- speed limit
- driver behavior profile
- driver fatigue
- continuous driving time
- break requirements
- weather
- road conditions
The result is a structured intent such as:
ACCELERATE
DECELERATE
MAINTAIN_SPEED
BRAKE
IDLE
Conceptually:
Driver
+
Vehicle State
+
Environment
+
Trip Context
│
▼
┌──────────────────────┐
│ Driver Behaviour │
│ Engine │
└──────────┬───────────┘
│
▼
Driver Intent
The Vehicle Controller converts a driver's intent into physical actuation.
For example:
Driver Intent
│
▼
┌──────────────────────┐
│ Vehicle Controller │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Vehicle Actuation │
│ │
│ Throttle │
│ Brake │
│ Gear │
└──────────────────────┘
This separates:
What the driver wants to do
from:
What the vehicle actually receives as an input
The Physics Engine applies actuation to the vehicle's current state.
It is responsible for evolving values such as:
- speed
- acceleration
- RPM
- gear
- fuel consumption
- engine temperature
- distance traveled
- engine hours
- component wear
- vehicle health
The physics model is intentionally simplified and explainable.
It is designed for simulation and experimentation rather than manufacturer-grade vehicle modeling.
Current Vehicle State
│
+
│
Actuation Input
│
+
│
Environment
│
▼
┌─────────────────────┐
│ Physics Engine │
└──────────┬──────────┘
│
▼
Updated Vehicle
State
Each simulated vehicle maintains its own operating state.
Vehicle
│
├── Specification
│ ├── Manufacturer
│ ├── Model
│ ├── Year
│ ├── Fuel Type
│ └── Transmission
│
├── Operating State
│ ├── Speed
│ ├── RPM
│ ├── Gear
│ ├── Fuel Level
│ ├── Engine Temperature
│ └── Engine Load
│
├── Health State
│ ├── Engine Health
│ ├── Brake Wear
│ └── Tyre Wear
│
└── Lifetime State
├── Odometer
└── Engine Hours
The important distinction is:
Vehicle
│
└── Owns the state
Physics Engine
│
└── Evolves the state
The Vehicle entity itself does not decide how its speed or RPM changes.
The Physics Engine is responsible for that evolution.
The simulation can provide environmental context to the vehicle and decision system.
Current environmental dimensions include:
- weather
- road conditions
- simulation time
For example:
Same Driver
+
Same Vehicle
+
Different Environment
│
▼
Different Decisions
│
▼
Different Actuation
│
▼
Different Vehicle State
This allows simulation scenarios such as:
Aggressive Driver
+
Dry Road
│
▼
Different Result
Aggressive Driver
+
Wet Road
│
▼
Different Result
DriveTwin separates the internal simulation state from the data that an external system consumes.
┌──────────────────────┐
│ Vehicle State │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Virtual Sensors │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Sensor Readings │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Telemetry Generator │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Telemetry Packet │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Telemetry Pipeline │
└──────────┬───────────┘
│
▼
┌──────────────────────┐
│ Telemetry Stream │
└──────────────────────┘
This boundary is important.
The simulation does not need to know what consumes the data.
The generated telemetry can theoretically be consumed by:
- analytics engines
- dashboards
- databases
- anomaly detection systems
- machine learning pipelines
- fleet intelligence platforms
DriveTwin advances through discrete simulation ticks.
A tick represents a small interval of simulated time.
┌─────────────────────────────┐
│ TICK N │
└──────────────┬──────────────┘
│
▼
Advance Simulation Clock
│
▼
Update Environment
│
▼
Evaluate Driver State
│
▼
Generate Driver Intent
│
▼
Compute Actuation
│
▼
Apply Physics
│
▼
Update Vehicle State
│
▼
Read Virtual Sensors
│
▼
Generate Telemetry
│
▼
Publish Telemetry
│
▼
┌─────────────────────────────┐
│ TICK N + 1 │
└─────────────────────────────┘
The simulation runtime is responsible for coordinating the progression of the simulation.
The individual domain components remain responsible for their own behavior.
The current architecture is organized into several independent layers.
┌─────────────────────────────────────────────┐
│ Simulation Runtime │
│ Clock • Tick Context • Scheduling │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Domain Entities │
│ Vehicle • Driver • Trip • Environment │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Decision Layer │
│ Driver Behavior → Driving Intent │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Control Layer │
│ Intent → Vehicle Actuation │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Physics Layer │
│ Actuation → Vehicle State Evolution │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Sensor Layer │
│ Vehicle State → Sensor Data │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ Telemetry Layer │
│ Sensor Data → Telemetry Stream │
└─────────────────────────────────────────────┘
The project also contains supporting layers for:
- fleet management
- trip management
- driver management
- vehicle management
- maintenance
- dispatch
- events
- configuration
- reusable profiles
DriveTwin/
│
├── README.md
├── requirements.txt
├── .gitignore
│
└── backend/
│
├── digital_twin/
│ │
│ ├── common/
│ │ ├── config/
│ │ ├── controller/
│ │ ├── decision/
│ │ ├── entities/
│ │ ├── events/
│ │ ├── managers/
│ │ ├── physics/
│ │ ├── profiles/
│ │ ├── runtime/
│ │ ├── sensors/
│ │ ├── telemetry/
│ │ └── utils/
│ │
│ ├── validate_full_telemetry_pipeline.py
│ └── ...
│
├── simulation/
│ ├── entity_bridge.py
│ └── simulation_runner.py
│
├── analytics/
│ └── ...
│
└── tests/
├── analytics/
├── demo_driving.py
├── inspect_one_tick.py
├── inspect_ten_ticks.py
└── validate_vehicle_controller.py
The core digital_twin package is organized as follows:
digital_twin/
│
├── common/
│ ├── enums.py
│ ├── exceptions.py
│ └── interfaces.py
│
├── config/
│ ├── constants.py
│ ├── defaults.py
│ └── simulation_config.py
│
├── controller/
│ ├── brake_controller.py
│ ├── controller_limits.py
│ ├── gear_logic.py
│ ├── throttle_controller.py
│ ├── transmission_controller.py
│ ├── vehicle_actuation.py
│ └── vehicle_controller.py
│
├── decision/
│ ├── braking_policy.py
│ ├── decision_context.py
│ ├── driver_behaviour_engine.py
│ ├── driver_intent.py
│ ├── fatigue_model.py
│ ├── personalities.py
│ ├── speed_policy.py
│ └── throttle_policy.py
│
├── entities/
│ ├── cargo.py
│ ├── driver.py
│ ├── environment.py
│ ├── fleet.py
│ ├── route.py
│ ├── shift.py
│ ├── trip.py
│ └── vehicle.py
│
├── events/
│ ├── events.py
│ ├── event_bus.py
│ └── event_handlers.py
│
├── managers/
│ ├── dispatch_manager.py
│ ├── driver_manager.py
│ ├── environment_manager.py
│ ├── fleet_manager.py
│ ├── maintenance_manager.py
│ ├── trip_manager.py
│ └── vehicle_manager.py
│
├── physics/
│ ├── dynamics.py
│ ├── fuel_model.py
│ ├── kinematics.py
│ ├── physics_constants.py
│ ├── physics_engine.py
│ ├── powertrain.py
│ ├── resistance_model.py
│ ├── thermal_model.py
│ └── wear_model.py
│
├── profiles/
│ ├── driver_profiles.py
│ ├── fleet_profiles.py
│ ├── route_profiles.py
│ └── vehicle_profiles.py
│
├── runtime/
│ ├── continuous_runtime.py
│ ├── demo.py
│ ├── digital_twin_runtime.py
│ ├── driving_scenario.py
│ ├── scheduler.py
│ ├── simulation_clock.py
│ └── tick_context.py
│
├── sensors/
│ ├── pid_mapper.py
│ ├── sensor_constants.py
│ ├── sensor_models.py
│ ├── sensor_provider.py
│ ├── sensor_registry.py
│ └── virtual_sensor_provider.py
│
├── telemetry/
│ ├── telemetry_generator.py
│ ├── telemetry_packet.py
│ ├── telemetry_pipeline.py
│ └── telemetry_stream.py
│
└── utils/
├── helpers.py
└── random_utils.py
A simplified representation of the simulation pipeline:
# 1. The driver and environment provide context
decision_context = DecisionContext(
driver=driver,
vehicle=vehicle,
environment=environment,
)
# 2. The Decision Layer produces an intent
intent = driver_behaviour_engine.decide(decision_context)
# 3. The Controller converts intent into actuation
actuation = vehicle_controller.compute_actuation(
intent=intent,
vehicle=vehicle,
)
# 4. The Physics Engine evolves the vehicle state
physics_result = physics_engine.update(
vehicle=vehicle,
actuation=actuation,
environment=environment,
)
# 5. Virtual sensors observe the resulting state
readings = sensor_provider.update_all(
vehicle,
tick_context,
)
# 6. Telemetry is generated
packet = telemetry_generator.generate(
vehicle,
readings,
tick_context,
)
# 7. The telemetry pipeline publishes the result
telemetry_pipeline.process(packet)The core idea is:
Intent
↓
Actuation
↓
Physics
↓
Vehicle State
↓
Sensors
↓
Telemetry
DriveTwin can orchestrate multiple simulated vehicles.
Each vehicle maintains its own state and simulation context.
┌────────────────────┐
│ Simulation Clock │
└─────────┬──────────┘
│
┌───────────────────┼───────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Vehicle 1 │ │ Vehicle 2 │ │ Vehicle 3 │
│ │ │ │ │ │
│ Driver │ │ Driver │ │ Driver │
│ Decisions │ │ Decisions │ │ Decisions │
│ Physics │ │ Physics │ │ Physics │
│ Sensors │ │ Sensors │ │ Sensors │
│ Telemetry │ │ Telemetry │ │ Telemetry │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────────┼───────────────────┘
│
▼
┌────────────────────┐
│ Telemetry Stream │
└────────────────────┘
The current system is designed to explore how a simulation can scale from a single vehicle to a small simulated fleet.
The main executable entry points are:
| Entry Point | Command | Purpose |
|---|---|---|
| Accelerated Demo | python -m digital_twin.runtime.demo --fast --ticks 5 |
Short deterministic simulation |
| Driving Demo | python -m tests.demo_driving |
30-tick driving behavior demonstration |
| Continuous Simulation | python -m simulation.continuous_loop |
Continuous multi-vehicle simulation |
| Telemetry Validation | python -m digital_twin.validate_full_telemetry_pipeline |
Validate the telemetry pipeline |
| Controller Validation | python -m tests.validate_vehicle_controller |
Validate vehicle actuation and controller behavior |
All commands should be executed from the backend/ directory.
DriveTwin and DriveVitals are separate projects with different responsibilities.
┌─────────────────────────────┐
│ DriveTwin │
│ │
│ Simulated Driver │
│ Simulated Vehicle │
│ Environment │
│ Vehicle Physics │
│ Virtual Sensors │
│ Telemetry Generation │
└──────────────┬──────────────┘
│
│ Telemetry
▼
┌─────────────────────────────┐
│ DriveVitals │
│ │
│ Driver Analytics │
│ Vehicle Analytics │
│ Fleet Intelligence │
│ Historical Trends │
│ Insights │
│ Dashboard │
└─────────────────────────────┘
The distinction is intentional.
How does a simulated vehicle and driver system evolve over time?
What can we learn from vehicle and driver data?
DriveTwin can therefore act as a controlled data source for testing analytics systems.
For example:
DriveTwin
│
├── Aggressive Driver
├── Eco Driver
├── Wet Road
├── Heavy Load
└── Long Trip
│
▼
Telemetry
│
▼
DriveVitals
│
▼
Driver & Vehicle
Analytics
This separation allows the simulation system and the analytics system to evolve independently.
- a stateful vehicle simulation framework
- an experimental automotive software project
- a controlled environment for generating telemetry
- a way to model driver-vehicle interactions
- a platform for experimenting with simulation architecture
- a potential data source for analytics systems
- a manufacturer-grade vehicle simulator
- a replacement for an actual ECU
- a complete physical digital replica of a specific production vehicle
- a full traffic simulator
- a production fleet management platform
The purpose of the project is to create a useful abstraction of vehicle operation that is:
Stateful. Explainable. Modular. Experimentable.
The current state of a vehicle should be influenced by its previous state.
State N
+
Decision
+
Actuation
+
Physics
↓
State N + 1
Different layers should have different jobs.
Driver
→ decides
Controller
→ translates intent into actuation
Physics
→ evolves vehicle state
Sensors
→ observe vehicle state
Telemetry
→ transports structured data
Simulation behavior should be traceable.
When a vehicle accelerates, it should be possible to understand:
Why did the driver intend to accelerate?
↓
Why was throttle applied?
↓
How did physics update the vehicle?
↓
How did the resulting state become telemetry?
The simulation should allow components to evolve independently.
For example:
New Driver Model
│
▼
Same Controller
New Physics Model
│
▼
Same Sensor Layer
Real Telemetry Source
│
▼
Same Analytics Consumer
DriveTwin is currently a standard-library-only Python project.
The recommended development workflow is:
Clone Repository
↓
Create Virtual Environment
↓
Activate Environment
↓
cd backend
↓
Run Demo
↓
Inspect Simulation
↓
Modify Simulation Components
↓
Run Validation Scripts
A typical first run is:
python -m digital_twin.runtime.demo --fast --ticks 5followed by:
python -m simulation.continuous_loopExperimental Project — Active Development
DriveTwin is an evolving engineering and research project.
The current foundation focuses on:
- stateful vehicle simulation
- driver behavior modeling
- decision-making
- vehicle actuation
- physics-based state evolution
- virtual sensors
- telemetry generation
- multi-vehicle orchestration
Future exploration may include:
- richer vehicle dynamics
- configurable driving scenarios
- route-aware simulation
- traffic modeling
- scenario replay
- simulation recording
- what-if experimentation
- larger fleet simulations
- real-world OBD-II telemetry integration
- integration with analytics and machine learning systems
DriveTwin sits at the intersection of:
Automotive Systems
+
Software Architecture
+
Simulation
+
Telemetry
+
Digital Twin Concepts
The project explores questions such as:
How should a vehicle be represented as a persistent software entity?
How can driver decisions influence vehicle state?
How can a simulation produce structured telemetry?
How can controlled simulation scenarios support analytics development?
How can a simulated vehicle system evolve independently from the system analyzing its data?