Skip to content

Examples

This section is the tutorial path through the example scripts. It is designed for race engineers and Students who want practical onboarding.

What you will learn from the examples

After finishing all example pages, you should be able to:

  • set up a complete lap-time run from scratch,
  • choose between point-mass and single-track model for a study goal,
  • interpret key plots and KPI outputs correctly,
  • understand where model assumptions limit interpretation.
  1. Synthetic Track Walkthrough
  2. Spa Walkthrough
  3. Transient Solver Walkthrough
  4. Sensitivity Walkthrough

Reason:

  • Synthetic tracks isolate single effects and simplify debugging.
  • Spa introduces full-track interactions and realistic complexity.
  • Transient examples introduce state/control trajectories beyond quasi-static envelopes.
  • Sensitivity examples connect parameter changes to lap-time and energy outcomes.

Mapping scripts to engineering questions

  • examples/synthetic_track_scenarios.py
  • "Is my model setup physically consistent on canonical test geometries?"
  • examples/spa/spa_lap_single_track.py
  • "What does the single-track model predict on a realistic circuit?"
  • examples/spa/spa_lap_point_mass.py
  • "What is the low-complexity baseline on the same circuit?"
  • examples/spa/spa_model_comparison.py
  • "What do I gain from additional model fidelity?"
  • examples/spa/spa_performance_envelope.py
  • "How does the speed-dependent G-G envelope differ by model complexity?"
  • examples/backend_benchmarks.py
  • "Which compute backend should I use for my workload?"
  • examples/transient/transient_point_mass_lap.py
  • "How does transient minimum-time launch behavior look for point-mass dynamics?"
  • examples/transient/transient_single_track_lap.py
  • "How do steering-rate and yaw dynamics affect a maneuver-heavy transient lap?"
  • examples/sensitivity/synthetic_single_track_sensitivity.py
  • "How sensitive are lap time and energy to key parameters on a canonical track via the Sensitivity API?"
  • examples/sensitivity/spa_single_track_sensitivity.py
  • "Which parameters matter most for lap time and energy on Spa via the Sensitivity API?"

What the example suite covers well

  • End-to-end solver use on real and synthetic tracks.
  • Side-by-side transient and quasi-static solver usage through the same public API.
  • KPI and plot export workflows.
  • Direct model-complexity comparison.
  • Practical interpretation of speed/acceleration/yaw diagnostics.
  • Parameter sensitivity interpretation for lap time and energy objectives.

What the example suite does not claim

  • It is not a final validation against fully instrumented race telemetry.
  • It does not include a full transient driver + powertrain control stack.
  • It does not replace model-calibration work on real vehicle data.

Output structure

All scripts export into examples/output/ with consistent folder logic (examples/output/spa/ for Spa-specific workflows and examples/output/transient/ for transient-specific workflows). Typical artifacts:

  • kpis.json
  • speed traces
  • G-G diagram
  • yaw moment vs. lateral acceleration
  • tire-load and power traces

Because output format is standardized, comparisons across scripts are straightforward.

Before applying results to decisions

Use this quick quality gate:

  1. Check whether the selected model can represent your target effect.
  2. Confirm basic sanity checks on synthetic tracks.
  3. Check if KPI magnitudes are plausible for your vehicle class.
  4. Document assumptions used in the run.