Analysis

analysis

Simulation analysis tools.

KpiSummary dataclass

Summary metrics for a lap simulation.

Parameters:

Name	Type	Description	Default
lap_time	float	Total lap time [s].	required
avg_lateral_accel_g	float	Mean absolute lateral acceleration (g).	required
max_lateral_accel_g	float	Peak absolute lateral acceleration (g).	required
avg_longitudinal_accel_g	float	Mean absolute longitudinal acceleration (g).	required
max_longitudinal_accel_g	float	Peak absolute longitudinal acceleration (g).	required
energy	float	Integrated positive traction energy [kWh].	required

PerformanceEnvelopeConfig dataclass

Top-level config for performance-envelope generation.

Parameters:

Name	Type	Description	Default
physics	PerformanceEnvelopePhysics	Physical operating-point definitions for the envelope.	PerformanceEnvelopePhysics()
numerics	PerformanceEnvelopeNumerics	Numerical discretization controls for the envelope sweep.	PerformanceEnvelopeNumerics()
runtime	PerformanceEnvelopeRuntime	Runtime backend controls for model evaluation.	PerformanceEnvelopeRuntime()

validate

validate() -> None

Validate combined envelope settings.

Raises:

Type	Description
ConfigurationError	If any physical, numerical, or runtime setting is invalid.

PerformanceEnvelopeNumerics dataclass

Numerical discretization controls for envelope generation.

Parameters:

Name	Type	Description	Default
speed_samples	int	Number of speed support points used for the sweep.	DEFAULT_ENVELOPE_SPEED_SAMPLES
lateral_accel_samples	int	Number of lateral-demand support points used per speed sample.	DEFAULT_ENVELOPE_LATERAL_ACCEL_SAMPLES
lateral_accel_fraction_span	float	Symmetric lateral-demand span relative to available lateral limit. 1.0 means [-ay_max, ay_max].	DEFAULT_LATERAL_ACCEL_FRACTION_SPAN

validate

validate() -> None

Validate numerical envelope discretization settings.

Raises:

Type	Description
ConfigurationError	If sample counts or span values violate required bounds.

PerformanceEnvelopePhysics dataclass

Physical operating-point definitions for envelope generation.

Parameters:

Name	Type	Description	Default
speed_min	float	Lower speed bound for the envelope sweep [m/s].	DEFAULT_ENVELOPE_SPEED_MIN
speed_max	float	Upper speed bound for the envelope sweep [m/s].	DEFAULT_ENVELOPE_SPEED_MAX
grade	float	Constant road grade used for all envelope samples dz/ds [-].	DEFAULT_ENVELOPE_GRADE
banking	float	Constant road banking used for all envelope samples [rad].	DEFAULT_ENVELOPE_BANKING

validate

validate() -> None

Validate physical operating-point definitions.

Raises:

Type	Description
ConfigurationError	If speed bounds are invalid or non-finite values are provided.

PerformanceEnvelopeResult dataclass

Computed velocity-dependent G-G envelope arrays.

Parameters:

Name	Type	Description	Default
speed	ndarray	Speed support points [m/s], shape (n_speed,).	required
lateral_accel_limit	ndarray	Lateral acceleration limits at each speed [m/s^2], shape (n_speed,).	required
lateral_accel_fraction	ndarray	Normalized lateral-demand support points used for each speed sample, shape (n_lateral,).	required
lateral_accel	ndarray	Lateral-demand matrix [m/s^2], shape (n_speed, n_lateral).	required
max_longitudinal_accel	ndarray	Maximum net forward acceleration matrix [m/s^2], shape (n_speed, n_lateral).	required
min_longitudinal_accel	ndarray	Minimum net longitudinal acceleration matrix (negative for braking) [m/s^2], shape (n_speed, n_lateral).	required

__post_init__

__post_init__() -> None

Validate array shapes after initialization.

to_dataframe

to_dataframe() -> Any

Return a long-form pandas representation of the envelope.

Returns:

Type	Description
Any	Pandas DataFrame with columns speed, lateral_accel_limit,
Any	lateral_accel_fraction, lateral_accel,
Any	max_longitudinal_accel, and min_longitudinal_accel.

Raises:

Type	Description
ConfigurationError	If pandas is not installed in the active environment.

to_numpy

to_numpy() -> np.ndarray

Return a stacked NumPy tensor representation.

Returns:

Type	Description
ndarray	Tensor with shape (n_speed, n_lateral, 3) and channels ordered
ndarray	as (lateral_accel, max_longitudinal_accel, min_longitudinal_accel).

PerformanceEnvelopeRuntime dataclass

Runtime controls for envelope generation backend selection.

Parameters:

Name	Type	Description	Default
compute_backend	str	Numerical backend identifier (numpy, numba, or torch).	DEFAULT_COMPUTE_BACKEND
torch_device	str	Torch device identifier. For non-torch backends this must remain "cpu".	DEFAULT_TORCH_DEVICE
torch_compile	bool	Enable torch.compile when backend is torch.	DEFAULT_ENABLE_TORCH_COMPILE

validate

validate() -> None

Validate runtime controls and backend availability.

Raises:

Type	Description
ConfigurationError	If backend selection or backend-specific runtime settings are invalid.

SensitivityConfig dataclass

Top-level config for scalar sensitivity computation.

Parameters:

Name	Type	Description	Default
numerics	SensitivityNumerics	Numerical controls for finite-difference perturbations.	SensitivityNumerics()
runtime	SensitivityRuntime	Runtime controls for backend-method selection.	SensitivityRuntime()

validate

validate() -> None

Validate combined sensitivity settings.

Raises:

Type	Description
ConfigurationError	If runtime or numerical controls are inconsistent.

SensitivityNumerics dataclass

Numerical controls for sensitivity estimation.

Parameters:

Name	Type	Description	Default
finite_difference_scheme	str	Finite-difference scheme identifier (central or forward).	DEFAULT_FD_SCHEME
finite_difference_relative_step	float	Relative finite-difference step scale.	DEFAULT_FD_RELATIVE_STEP
finite_difference_absolute_step	float	Absolute finite-difference step floor.	DEFAULT_FD_ABSOLUTE_STEP

step_size

step_size(value: float) -> float

Return finite-difference perturbation size for a scalar value.

Parameters:

Name	Type	Description	Default
value	float	Baseline parameter value.	required

Returns:

Type	Description
float	Positive perturbation size.

validate

validate() -> None

Validate sensitivity numerical controls.

Raises:

Type	Description
ConfigurationError	If scheme or step controls violate required bounds.

SensitivityParameter dataclass

Single scalar parameter definition for sensitivity analysis.

Parameters:

Name	Type	Description	Default
name	str	Parameter identifier consumed by the objective callable.	required
value	float	Baseline scalar parameter value.	required
kind	str	Conceptual parameter category. physical is intended for measurable real-world quantities; numerical for solver controls.	'physical'
lower_bound	float | None	Optional lower bound for perturbation validity.	None
upper_bound	float | None	Optional upper bound for perturbation validity.	None

validate

validate() -> None

Validate parameter definition.

Raises:

Type	Description
ConfigurationError	If name, value, kind, or bounds violate required constraints.

SensitivityResult dataclass

Sensitivity result for a scalar objective around a baseline point.

Parameters:

Name	Type	Description	Default
objective_value	float	Baseline objective value at provided parameters.	required
sensitivities	dict[str, float]	Mapping from parameter name to local scalar sensitivity.	required
method	str	Backend method used for the returned sensitivities.	required
parameter_values	dict[str, float]	Baseline scalar values used for each parameter.	required
parameter_kinds	dict[str, str]	Parameter category map (physical/numerical).	required

__post_init__

__post_init__() -> None

Validate result payload consistency.

Raises:

Type	Description
ConfigurationError	If keys are mismatched or unsupported method/category identifiers are provided.

SensitivityRuntime dataclass

Runtime controls for selecting the sensitivity backend method.

Parameters:

Name	Type	Description	Default
method	str	Sensitivity backend (autodiff or finite_difference).	DEFAULT_SENSITIVITY_METHOD
torch_device	str	Torch device used for autodiff parameter tensors.	DEFAULT_TORCH_DEVICE
autodiff_fallback_to_finite_difference	bool	Whether autodiff backend errors should fall back to finite-difference evaluation.	DEFAULT_AUTODIFF_FALLBACK_TO_FD

validate

validate() -> None

Validate sensitivity runtime controls.

Raises:

Type	Description
ConfigurationError	If method/device selection is invalid or unavailable.

SensitivityStudyParameter dataclass

Parameter specification for high-level lap sensitivity studies.

Parameters:

Name	Type	Description	Default
name	str	Parameter identifier used in exported sensitivity tables.	required
target	str	Dot-path in the reconstructed model input mapping to the scalar value to be perturbed (for example vehicle.mass).	required
label	str | None	Optional human-readable label for plots/tables.	None
kind	str	Conceptual parameter category (physical or numerical).	'physical'
relative_variation	float	Relative variation used for local +/- prediction columns in tabular outputs.	DEFAULT_SENSITIVITY_STUDY_RELATIVE_VARIATION
lower_bound	float | None	Optional lower bound applied to local perturbations.	None
upper_bound	float | None	Optional upper bound applied to local perturbations.	None

validate

validate() -> None

Validate study-parameter definition.

Raises:

Type	Description
ConfigurationError	If target format, parameter category, bounds, or relative variation are invalid.

SensitivityStudyResult dataclass

Aggregated lap sensitivity outputs for multiple objectives.

Parameters:

Name	Type	Description	Default
study_label	str | None	Optional study label propagated into tabular exports.	required
objective_order	tuple[str, ...]	Objective identifier order used for outputs.	required
objective_units	dict[str, str]	Objective-unit mapping.	required
parameters	tuple[SensitivityStudyParameter, ...]	Ordered study parameters used in the run.	required
sensitivity_results	dict[str, SensitivityResult]	Per-objective scalar sensitivity outputs.	required

__post_init__

__post_init__() -> None

Validate structural consistency of study outputs.

Raises:

Type	Description
ConfigurationError	If objective or parameter mappings are inconsistent.

to_dataframe

to_dataframe() -> Any

Return long-form tabular sensitivity output.

Returns:

Type	Description
Any	Pandas DataFrame containing one row per
Any	(objective, parameter) pair.

Raises:

Type	Description
ConfigurationError	If pandas is not installed in the active environment.

to_pivot

to_pivot(value_column: str = 'sensitivity_pct_per_pct') -> Any

Return compact parameter x objective sensitivity table.

Parameters:

Name	Type	Description	Default
value_column	str	DataFrame value column used for the pivot table.	'sensitivity_pct_per_pct'

Returns:

Type	Description
Any	Pandas DataFrame with parameters as rows and objectives as columns.

Raises:

Type	Description
ConfigurationError	If value_column is not present in the long-form table.

build_performance_envelope_config

build_performance_envelope_config(physics: PerformanceEnvelopePhysics | None = None, numerics: PerformanceEnvelopeNumerics | None = None, runtime: PerformanceEnvelopeRuntime | None = None) -> PerformanceEnvelopeConfig

Build a validated performance-envelope config.

Parameters:

Name	Type	Description	Default
physics	PerformanceEnvelopePhysics | None	Optional physical operating-point definitions.	None
numerics	PerformanceEnvelopeNumerics | None	Optional numerical discretization controls.	None
runtime	PerformanceEnvelopeRuntime | None	Optional runtime backend controls.	None

Returns:

Type	Description
PerformanceEnvelopeConfig	Fully validated performance-envelope configuration.

Raises:

Type	Description
ConfigurationError	If assembled settings are inconsistent.

build_sensitivity_config

build_sensitivity_config(numerics: SensitivityNumerics | None = None, runtime: SensitivityRuntime | None = None) -> SensitivityConfig

Build a validated sensitivity configuration.

Parameters:

Name	Type	Description	Default
numerics	SensitivityNumerics | None	Optional numerical controls.	None
runtime	SensitivityRuntime | None	Optional runtime controls.	None

Returns:

Type	Description
SensitivityConfig	Validated sensitivity config.

compute_kpis

compute_kpis(result: LapResult) -> KpiSummary

Compute mandatory and energy KPIs from simulation output.

Parameters:

Name	Type	Description	Default
result	LapResult	Full lap simulation output arrays and integrated metrics.	required

Returns:

Type	Description
KpiSummary	Aggregated KPI summary containing lap time, acceleration metrics, and
KpiSummary	electrical-equivalent traction energy [kWh].

compute_performance_envelope

compute_performance_envelope(model: VehicleModel, config: PerformanceEnvelopeConfig | None = None, *, physics: PerformanceEnvelopePhysics | None = None, numerics: PerformanceEnvelopeNumerics | None = None, runtime: PerformanceEnvelopeRuntime | None = None) -> PerformanceEnvelopeResult

Compute a velocity-dependent G-G performance envelope for a vehicle model.

Either provide a full config object, or provide physics, numerics, and/or runtime components directly.

Parameters:

Name	Type	Description	Default
model	VehicleModel	Vehicle model backend implementing VehicleModel.	required
config	PerformanceEnvelopeConfig | None	Optional pre-built performance-envelope configuration.	None
physics	PerformanceEnvelopePhysics | None	Optional physical operating-point settings (only used when config is not provided).	None
numerics	PerformanceEnvelopeNumerics | None	Optional numerical envelope discretization controls (only used when config is not provided).	None
runtime	PerformanceEnvelopeRuntime | None	Optional backend runtime controls (only used when config is not provided).	None

Returns:

Type	Description
PerformanceEnvelopeResult	Computed performance-envelope result containing speed support, lateral
PerformanceEnvelopeResult	limits, and longitudinal accel/decel limits over the sampled G-G domain.

Raises:

Type	Description
ConfigurationError	If configuration is invalid, incompatible options are provided, or backend-specific model API requirements are not met.

compute_sensitivities

compute_sensitivities(objective: SensitivityObjective, parameters: Sequence[SensitivityParameter] | Mapping[str, float], config: SensitivityConfig | None = None, *, numerics: SensitivityNumerics | None = None, runtime: SensitivityRuntime | None = None) -> SensitivityResult

Compute scalar-objective sensitivities for selected input parameters.

Either provide a full config object, or provide numerics and/or runtime components directly.

Parameters:

Name	Type	Description	Default
objective	SensitivityObjective	Objective function returning a scalar KPI value.	required
parameters	Sequence[SensitivityParameter] | Mapping[str, float]	Parameter definitions or a name -> value mapping.	required
config	SensitivityConfig | None	Optional validated sensitivity config.	None
numerics	SensitivityNumerics | None	Optional numerical controls (used only if config is not provided).	None
runtime	SensitivityRuntime | None	Optional runtime controls (used only if config is not provided).	None

Returns:

Type	Description
SensitivityResult	Baseline scalar objective and local sensitivities per parameter.

Raises:

Type	Description
ConfigurationError	If configuration or parameter definitions are invalid, or if objective outputs violate scalar/autodiff requirements.

export_standard_plots

export_standard_plots(result: LapResult, output_dir: str | Path) -> None

Export all standard analysis plots in PNG and PDF format.

Parameters:

Name	Type	Description	Default
result	LapResult	Simulation result used as plotting input.	required
output_dir	str | Path	Destination directory for all generated plots.	required

register_sensitivity_model_adapter

register_sensitivity_model_adapter(*, model_type: type[Any], model_factory: SensitivityModelFactory, model_inputs_getter: SensitivityModelInputsGetter) -> None

Register model reconstruction adapter for lap sensitivity studies.

Registered adapters enable :func:run_lap_sensitivity_study to rebuild a model for each parameter perturbation without mutating the passed model.

Parameters:

Name	Type	Description	Default
model_type	type[Any]	Model class handled by the adapter.	required
model_factory	SensitivityModelFactory	Callable rebuilding model instances from keyword inputs.	required
model_inputs_getter	SensitivityModelInputsGetter	Callable extracting reconstructable baseline model inputs from an existing model instance.	required

Raises:

Type	Description
ConfigurationError	If adapter inputs are malformed.

run_lap_sensitivity_study

run_lap_sensitivity_study(*, track: TrackData, model: Any, simulation_config: SimulationConfig, parameters: Sequence[SensitivityStudyParameter], objectives: Sequence[str] = DEFAULT_LAP_SENSITIVITY_OBJECTIVES, label: str | None = None, config: SensitivityConfig | None = None, numerics: SensitivityNumerics | None = None, runtime: SensitivityRuntime | None = None) -> SensitivityStudyResult

Run a local lap-KPI sensitivity study over selected scalar parameters.

The study API is model-agnostic. The model is rebuilt from the provided model instance for each parameter perturbation and objective evaluation.

Parameters:

Name	Type	Description	Default
track	TrackData	Track used for speed-profile evaluation.	required
model	Any	Baseline model instance used for adapter-based reconstruction.	required
simulation_config	SimulationConfig	Simulation setup. Must use compute_backend='torch'.	required
parameters	Sequence[SensitivityStudyParameter]	Parameter definitions with dot-path targets into the model input map reconstructed by the registered adapter.	required
objectives	Sequence[str]	Objective identifiers. Supported values are lap_time_s and energy_kwh.	DEFAULT_LAP_SENSITIVITY_OBJECTIVES
label	str | None	Optional study label used in exported tabular outputs.	None
config	SensitivityConfig | None	Optional full sensitivity config.	None
numerics	SensitivityNumerics | None	Optional sensitivity numerics (used if config is omitted).	None
runtime	SensitivityRuntime | None	Optional sensitivity runtime (used if config is omitted).	None

Returns:

Type	Description
SensitivityStudyResult	Multi-objective sensitivity-study result with tabular conversion helpers.

Raises:

Type	Description
ConfigurationError	If objective names are unsupported, parameter targets are invalid, or backend requirements are not satisfied.