Track how a real engine ages.
Explore where a future engine could fail.
Vision · Applications · Roadmap · Technical track · Get involved
V-Twin is an engine modeling and simulation project with two goals: follow the condition and wear of a real engine, and test engine designs in a virtual sandbox before production.
Both applications will share a simulation core that connects operating conditions to mechanical and thermal loads, then to degradation over time. The aim is to make these relationships observable, explainable, and useful for engineering decisions.
Note
V-Twin has an initial development foundation: an installable Python numerical package, a headless runner with checkpointed resume and deterministic replay, a first slider-crank kinematics model, a protected local API, a Next.js dashboard that runs and compares the two demo cases, tests, quality checks, and a cross-platform CI workflow. Dynamics, friction/lubrication and wear models, data integrations, dashboards, and 3D remain planned work.
The first demonstrator will prioritize the design sandbox, with one reference engine and a focused reliability case. The real-engine twin remains a subsequent delivery goal. The scoped reference case, evidence gaps, and demonstration requirements are recorded in the product scope.
The scoped MVP uses parameter-based configuration, an interactive 3D view, graphs, and baseline-versus-variant comparison. A dashboard-only mode supports configuration, calculations, graphs, comparison, and export without loading 3D. Its first reliability topic is ring–liner wear associated with friction and lubrication. Audio is outside the product scope. The project has five team members; responsibilities and current GitHub availability are recorded in the team allocation. The next Epitech mentoring meeting is Monday, October 26, 2026; the first executable-demonstration date remains to be defined.
Frontend: Next.js (React) with TypeScript and shadcn/ui, built as a static export and served by the local API. The Vue/Vite scaffold was replaced on November 13, 2026.
Prerequisites: uv 0.13.1, Node 24.18.1, and npm 11.16.0. uv installs the pinned Python 3.13.16 runtime when needed. From the repository root:
uv sync --locked --extra api
npm --prefix web ci
npm --prefix web run build
uv run --locked --extra api vtwin serveOpen http://127.0.0.1:8000. The startup screen checks the local API; it does not simulate an engine. See the development guide for setup, dev mode, tests, reports, configuration, and CI.
Run the two demo kinematic cases without the interface with uv run --locked vtwin run examples/cases/kinematics-ref-2000rpm.json; the runner guide covers the contract, replay and resume.
The independent numerical smoke check is uv run --locked --extra api vtwin check-numerics. It compares an analytical ODE with its exact solution and does not validate engine wear.
The performance protocol defines the sandbox KPIs, user targets and measurement procedure. The tracking register keeps product baselines and technical budgets explicitly pending; an environment-inventory command is available for each target computer.
| Digital twin | Design sandbox | |
|---|---|---|
| Purpose | Follow the evolving condition of a specific real engine. | Explore an engine's behavior and potential weaknesses before production. |
| Inputs | Engine configuration, measurements, and operating history. | Design parameters, operating scenarios, environmental conditions, and controlled faults. |
| Planned capabilities | Synchronize observations with the model, estimate state and wear, and explain changes over time. | Compare configurations, explore demanding conditions, reproduce weaknesses, and assess corrective variants. |
| Evidence of success | Estimates agree with independent observations of the engine and the component being tracked. | The sandbox reproduces a known weakness and evaluates a correction against reference evidence. |
The twin will use an engine's measurements and operating history to maintain an estimate of its condition. It should help users understand how accumulated use affects the component being tracked, where the available data supports an estimate, and why a change or alert appears.
The planned workflow covers data import, quality checks, engine-specific calibration, state updates, historical replay, and a view of estimated wear with its uncertainty.
The sandbox will let users define engine configurations and run repeatable experiments under different loads, transients, environments, and physically supported faults.
The goal is to locate potential weak points, understand the conditions that trigger them, and compare a proposed correction against the original design using the same scenarios and metrics.
The planned flow brings measured operation and virtual experiments into the same modeling foundation:
flowchart TD
real["Real engine data<br/>Measurements and operating history"] --> core
virtual["Virtual test scenarios<br/>Configurations, loads, and faults"] --> core
core["Shared simulation core<br/>Mechanics, thermodynamics, and degradation"]
core --> twin["Digital twin<br/>Estimated condition and wear over time"]
core --> sandbox["Design sandbox<br/>Comparisons, weak points, and corrective variants"]
The working V1 architecture separates a Python/NumPy/SciPy engine, application services, a local HTTP API, and a Next.js (React)/TypeScript interface as the selected frontend target. It uses local batch execution followed by result exploration, with Windows, macOS, and Linux as target platforms. The solver and storage choices, alternatives, and evaluation gates are recorded in architecture decision records. Model execution and numerical results remain independent of the viewer. Our target is usable results within one minute for the nominal case; workload definition and measured feasibility remain follow-up work.
- Ground models in physical evidence. Document equations, units, parameter sources, assumptions, and the operating conditions each model supports.
- Keep measurements and estimates distinct. Make the origin of each output visible, including whether it is measured, estimated, or a load indicator.
- Make experiments reproducible. Preserve model versions, configurations, initial states, input histories, and numerical settings for each run.
- Validate on independent observations. Separate calibration data from evaluation data and report errors, uncertainty, and coverage.
A load indicator becomes a calibrated wear estimate only when the relationship is supported by measurements. Remaining-life prediction will require its own failure model and validation before becoming a product capability.
The roadmap contains 47 objectives across 7 milestones: 28 product objectives and 19 supporting objectives for technology evaluation, architecture, expert collaboration, and technical performance. Each objective has a deliverable, acceptance criteria, a priority, and explicit dependencies.
| Milestone | Focus | Completion target |
|---|---|---|
| M0 · Define the problem | Scope, reference engine, data, and validation protocols. | An accessible reference case and measurable success criteria for both applications. |
| M1 · Build the foundation | Architecture, data contracts, CI, and a runner without a graphical interface. | A versioned engine configuration can be simulated, recorded, and replayed reproducibly. |
| M2 · Model engine physics | Mechanics, gas exchange, combustion, thermal behavior, and relevant lubrication conditions. | Mechanical and thermal outputs meet defined tolerances against reference data. |
| M3 · Model wear | A first degradation mechanism, calibration, and uncertainty. | Wear estimates are evaluated against independent observations within a documented domain. |
| M4 · Connect the digital twin | Real data ingestion, engine-specific calibration, state history, and monitoring. | A real session can be imported and replayed with traceable state and wear estimates. |
| M5 · Build the sandbox | Scenarios, fault injection, parameter sweeps, and comparison reports. | A reproducible campaign identifies a supported weakness and compares corrective variants. |
| M6 · Validate and demonstrate | Independent benchmarks, a real-engine demonstration, and a design case study. | Both applications have reproducible demonstrations with documented results and limits. |
Milestones are driven by evidence and dependencies. Data collection should begin early; acquisition work and sandbox development can progress in parallel once their prerequisites are met.
Explore the plan: GitHub Project · Roadmap issues · Milestones
The project board requires access to the organization's private project. The roadmap issues and milestones are also linked directly above.
For the next review, use Prochain mentorat for the team or Prochain Mentorat mon travail for preparation tickets assigned to the signed-in member.
V-Twin follows four selected Epitech Technical Track objectives. Issues use cumulative labels to show which objectives they support:
| Objective | Issue label | Expected evidence |
|---|---|---|
| Mandatory 1 · Technology watch | track:tech-watch |
Comparative studies, POCs, benchmarks, justified adoption of a new technology, and documented sharing. |
| Mandatory 2 · Technical architecture | track:architecture |
Architecture and UML diagrams, technical documentation, configuration, quality reports, critical-module tests, error handling, logging, and initial security. |
| Selected complementary 1 · Experts | track:experts |
Focused external reviews, documented advice, and applied recommendations with verification. |
| Selected complementary 2 · Performance | track:performance |
Two to three primary KPIs, a reproducible baseline, load and resilience tests, and a measured before/after optimization. |
These are planned deliverables. Labels identify contributions to an objective; completion requires linked evidence. The team's proposed targets of four studies, two POCs, and two comparative benchmarks are explained in the track coverage and evidence plan.
Read the product scope and its M0.1 decision record for the first demonstrator, reference engine, and initial wear mechanism.
Contributions can help with engine modeling, instrumentation and datasets, numerical methods, model validation, and the tools that make results understandable. Use the roadmap issues to find an objective and review its dependencies and acceptance criteria before proposing work.
Follow the contribution workflow and run the documented checks before proposing a change.
For a modeling proposal, include the physical mechanism, assumptions, required inputs, expected outputs, and the evidence that could validate it.
V-Twin is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for the full text.
From operating history to wear estimates. From virtual experiments to better engine designs.