AutoForge/src/AutoForge.Core/Simulation/DynamicsConfiguration.cs

496 lines
23 KiB
C#

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using AutoForge.Core.Vehicles;
namespace AutoForge.Core.Simulation;
public enum DynamicsScenarioPhaseKind
{
WarmIdle,
Accelerate,
Cruise,
Brake,
ReturnIdle
}
public sealed record EngineTorquePoint(double EngineSpeedRpm, double TorqueNewtonMeters);
public sealed class DynamicsModelParameters
{
public DynamicsModelParameters(
double stepSeconds,
double vehicleMassKilograms,
double wheelRadiusMeters,
double dragAreaSquareMeters,
double rollingResistanceCoefficient,
double airDensityKilogramsPerCubicMeter,
double gravityMetersPerSecondSquared,
double drivetrainEfficiency,
double maximumBrakeForceNewtons,
double idleSpeedRpm,
double maximumEngineSpeedRpm,
double warmIdleTargetRpm,
double launchSlipEndSpeedMetersPerSecond,
double idleFuelRateKilogramsPerSecond,
double fuelKilogramsPerJoule,
double ambientTemperatureCelsius,
double initialEngineTemperatureCelsius,
double equilibriumEngineTemperatureCelsius,
double thermalResponsePerSecond,
IReadOnlyList<EngineTorquePoint> engineTorqueCurve,
IReadOnlyList<double> forwardGearRatios,
IReadOnlyList<double> upshiftSpeedsRpm,
IReadOnlyList<double> downshiftSpeedsRpm,
double finalDriveRatio)
{
StepSeconds = RequireRange(stepSeconds, 0.01, 0.5, nameof(stepSeconds));
VehicleMassKilograms = RequireRange(vehicleMassKilograms, 100, 100_000, nameof(vehicleMassKilograms));
WheelRadiusMeters = RequireRange(wheelRadiusMeters, 0.05, 2, nameof(wheelRadiusMeters));
DragAreaSquareMeters = RequireRange(dragAreaSquareMeters, 0, 20, nameof(dragAreaSquareMeters));
RollingResistanceCoefficient = RequireRange(rollingResistanceCoefficient, 0, 0.2, nameof(rollingResistanceCoefficient));
AirDensityKilogramsPerCubicMeter = RequireRange(airDensityKilogramsPerCubicMeter, 0.1, 2, nameof(airDensityKilogramsPerCubicMeter));
GravityMetersPerSecondSquared = RequireRange(gravityMetersPerSecondSquared, 1, 20, nameof(gravityMetersPerSecondSquared));
DrivetrainEfficiency = RequireRange(drivetrainEfficiency, 0.1, 1, nameof(drivetrainEfficiency));
MaximumBrakeForceNewtons = RequireRange(maximumBrakeForceNewtons, 1, 1_000_000, nameof(maximumBrakeForceNewtons));
IdleSpeedRpm = RequireRange(idleSpeedRpm, 400, 2_000, nameof(idleSpeedRpm));
MaximumEngineSpeedRpm = RequireRange(maximumEngineSpeedRpm, 1_500, 12_000, nameof(maximumEngineSpeedRpm));
WarmIdleTargetRpm = RequireRange(warmIdleTargetRpm, IdleSpeedRpm, MaximumEngineSpeedRpm, nameof(warmIdleTargetRpm));
LaunchSlipEndSpeedMetersPerSecond = RequireRange(launchSlipEndSpeedMetersPerSecond, 0.1, 15, nameof(launchSlipEndSpeedMetersPerSecond));
IdleFuelRateKilogramsPerSecond = RequireRange(idleFuelRateKilogramsPerSecond, 0, 0.01, nameof(idleFuelRateKilogramsPerSecond));
FuelKilogramsPerJoule = RequireRange(fuelKilogramsPerJoule, 0, 0.001, nameof(fuelKilogramsPerJoule));
AmbientTemperatureCelsius = RequireRange(ambientTemperatureCelsius, -80, 80, nameof(ambientTemperatureCelsius));
InitialEngineTemperatureCelsius = RequireRange(initialEngineTemperatureCelsius, -80, 250, nameof(initialEngineTemperatureCelsius));
EquilibriumEngineTemperatureCelsius = RequireRange(equilibriumEngineTemperatureCelsius, -20, 250, nameof(equilibriumEngineTemperatureCelsius));
ThermalResponsePerSecond = RequireRange(thermalResponsePerSecond, 0, 1, nameof(thermalResponsePerSecond));
FinalDriveRatio = RequireRange(finalDriveRatio, 0.1, 20, nameof(finalDriveRatio));
EngineTorqueCurve = CopyCurve(engineTorqueCurve, MaximumEngineSpeedRpm);
ForwardGearRatios = CopyDescendingRatios(forwardGearRatios, nameof(forwardGearRatios));
UpshiftSpeedsRpm = CopyShiftThresholds(upshiftSpeedsRpm, ForwardGearRatios.Count, nameof(upshiftSpeedsRpm));
DownshiftSpeedsRpm = CopyShiftThresholds(downshiftSpeedsRpm, ForwardGearRatios.Count, nameof(downshiftSpeedsRpm));
for (var index = 0; index < UpshiftSpeedsRpm.Count; index++)
{
if (DownshiftSpeedsRpm[index] >= UpshiftSpeedsRpm[index] ||
UpshiftSpeedsRpm[index] > MaximumEngineSpeedRpm)
{
throw new ArgumentException(
"Each downshift speed must be below its upshift speed, and all upshift thresholds must be within the engine speed limit.",
nameof(downshiftSpeedsRpm));
}
}
if (WarmIdleTargetRpm < IdleSpeedRpm)
{
throw new ArgumentException("Warm-idle speed cannot be below engine idle speed.", nameof(warmIdleTargetRpm));
}
}
public double StepSeconds { get; }
public double VehicleMassKilograms { get; }
public double WheelRadiusMeters { get; }
public double DragAreaSquareMeters { get; }
public double RollingResistanceCoefficient { get; }
public double AirDensityKilogramsPerCubicMeter { get; }
public double GravityMetersPerSecondSquared { get; }
public double DrivetrainEfficiency { get; }
public double MaximumBrakeForceNewtons { get; }
public double IdleSpeedRpm { get; }
public double MaximumEngineSpeedRpm { get; }
public double WarmIdleTargetRpm { get; }
public double LaunchSlipEndSpeedMetersPerSecond { get; }
public double IdleFuelRateKilogramsPerSecond { get; }
public double FuelKilogramsPerJoule { get; }
public double AmbientTemperatureCelsius { get; }
public double InitialEngineTemperatureCelsius { get; }
public double EquilibriumEngineTemperatureCelsius { get; }
public double ThermalResponsePerSecond { get; }
public IReadOnlyList<EngineTorquePoint> EngineTorqueCurve { get; }
public IReadOnlyList<double> ForwardGearRatios { get; }
public IReadOnlyList<double> UpshiftSpeedsRpm { get; }
public IReadOnlyList<double> DownshiftSpeedsRpm { get; }
public double FinalDriveRatio { get; }
private static double RequireRange(double value, double minimum, double maximum, string name)
{
if (!double.IsFinite(value) || value < minimum || value > maximum)
{
throw new ArgumentOutOfRangeException(name, value, $"Value must be finite and between {minimum} and {maximum}.");
}
return value;
}
private static IReadOnlyList<EngineTorquePoint> CopyCurve(IReadOnlyList<EngineTorquePoint> values, double maximumRpm)
{
ArgumentNullException.ThrowIfNull(values);
var points = values.ToArray();
if (points.Length < 2 ||
points.Any(point => point is null ||
!double.IsFinite(point.EngineSpeedRpm) ||
!double.IsFinite(point.TorqueNewtonMeters) ||
point.EngineSpeedRpm < 0 ||
point.EngineSpeedRpm > maximumRpm ||
point.TorqueNewtonMeters <= 0) ||
points.Zip(points.Skip(1), (left, right) => left.EngineSpeedRpm < right.EngineSpeedRpm).Any(ordered => !ordered))
{
throw new ArgumentException("Torque curve points must be finite, positive, in range, unique and strictly increasing.", nameof(values));
}
return Array.AsReadOnly(points);
}
private static IReadOnlyList<double> CopyDescendingRatios(IReadOnlyList<double> values, string name)
{
ArgumentNullException.ThrowIfNull(values);
var ratios = values.ToArray();
if (ratios.Length is < 2 or > 12 ||
ratios.Any(ratio => !double.IsFinite(ratio) || ratio <= 0 || ratio > 20) ||
ratios.Zip(ratios.Skip(1), (left, right) => left > right).Any(descending => !descending))
{
throw new ArgumentException("Forward gear ratios must be finite, positive and strictly descending.", name);
}
return Array.AsReadOnly(ratios);
}
private static IReadOnlyList<double> CopyShiftThresholds(IReadOnlyList<double> values, int gearCount, string name)
{
ArgumentNullException.ThrowIfNull(values);
var thresholds = values.ToArray();
if (thresholds.Length != gearCount ||
thresholds.Any(value => !double.IsFinite(value) || value <= 0 || value > 20_000))
{
throw new ArgumentException("Each forward gear must have one finite positive shift threshold.", name);
}
return Array.AsReadOnly(thresholds);
}
}
public sealed class DynamicsInitialConditions
{
public DynamicsInitialConditions(
bool engineRunning,
double vehicleSpeedMetersPerSecond,
int gear,
double engineSpeedRpm,
double engineTemperatureCelsius,
double fuelConsumedKilograms,
double distanceMeters)
{
if (!double.IsFinite(vehicleSpeedMetersPerSecond) || vehicleSpeedMetersPerSecond is < 0 or > 150 ||
!double.IsFinite(engineSpeedRpm) || engineSpeedRpm < 0 ||
!double.IsFinite(engineTemperatureCelsius) || engineTemperatureCelsius is < -80 or > 250 ||
!double.IsFinite(fuelConsumedKilograms) || fuelConsumedKilograms < 0 ||
!double.IsFinite(distanceMeters) || distanceMeters < 0 ||
gear is < 0 or > 12)
{
throw new ArgumentException("Initial dynamics conditions must be finite and within their physical domains.");
}
if (!engineRunning && (engineSpeedRpm != 0 || gear != 0) ||
vehicleSpeedMetersPerSecond == 0 && gear > 0)
{
throw new ArgumentException("Engine-off conditions require zero rpm and neutral; a stationary vehicle cannot start in gear.");
}
EngineRunning = engineRunning;
VehicleSpeedMetersPerSecond = vehicleSpeedMetersPerSecond;
Gear = gear;
EngineSpeedRpm = engineSpeedRpm;
EngineTemperatureCelsius = engineTemperatureCelsius;
FuelConsumedKilograms = fuelConsumedKilograms;
DistanceMeters = distanceMeters;
}
public bool EngineRunning { get; }
public double VehicleSpeedMetersPerSecond { get; }
public int Gear { get; }
public double EngineSpeedRpm { get; }
public double EngineTemperatureCelsius { get; }
public double FuelConsumedKilograms { get; }
public double DistanceMeters { get; }
}
public sealed class DynamicsScenarioPhase
{
public DynamicsScenarioPhase(DynamicsScenarioPhaseKind kind, double targetSpeedMetersPerSecond, double durationSeconds)
{
if (!Enum.IsDefined(kind) ||
!double.IsFinite(targetSpeedMetersPerSecond) ||
targetSpeedMetersPerSecond < 0 ||
!double.IsFinite(durationSeconds) ||
durationSeconds <= 0 ||
durationSeconds > 86_400)
{
throw new ArgumentException("Scenario phase kind, target speed and duration must be valid and finite.");
}
Kind = kind;
TargetSpeedMetersPerSecond = targetSpeedMetersPerSecond;
DurationSeconds = durationSeconds;
}
public DynamicsScenarioPhaseKind Kind { get; }
public double TargetSpeedMetersPerSecond { get; }
public double DurationSeconds { get; }
}
public sealed class DynamicsConfiguration
{
private static readonly JsonSerializerOptions FingerprintOptions = new()
{
PropertyNamingPolicy = JsonNamingPolicy.CamelCase
};
public DynamicsConfiguration(
int formatVersion,
string profileIdentifier,
int profileRevision,
string vehicleIdentifier,
string engineModuleIdentifier,
string? engineCalibrationReference,
string transmissionModuleIdentifier,
string? transmissionCalibrationReference,
string modelIdentifier,
int modelVersion,
DynamicsModelParameters model,
DynamicsInitialConditions initialConditions,
IReadOnlyList<DynamicsScenarioPhase> scenario)
{
if (formatVersion != 1 || modelVersion != 1)
{
throw new ArgumentOutOfRangeException(nameof(formatVersion), "Only configuration format 1 and model version 1 are supported.");
}
ProfileIdentifier = RequireText(profileIdentifier, nameof(profileIdentifier));
if (profileRevision <= 0)
{
throw new ArgumentOutOfRangeException(nameof(profileRevision));
}
VehicleIdentifier = RequireText(vehicleIdentifier, nameof(vehicleIdentifier));
EngineModuleIdentifier = RequireText(engineModuleIdentifier, nameof(engineModuleIdentifier));
EngineCalibrationReference = OptionalText(engineCalibrationReference, nameof(engineCalibrationReference));
TransmissionModuleIdentifier = RequireText(transmissionModuleIdentifier, nameof(transmissionModuleIdentifier));
TransmissionCalibrationReference = OptionalText(transmissionCalibrationReference, nameof(transmissionCalibrationReference));
if (StringComparer.OrdinalIgnoreCase.Equals(EngineModuleIdentifier, TransmissionModuleIdentifier))
{
throw new ArgumentException("Engine and transmission module references must be distinct.");
}
ModelIdentifier = RequireText(modelIdentifier, nameof(modelIdentifier));
ModelVersion = modelVersion;
Model = model ?? throw new ArgumentNullException(nameof(model));
InitialConditions = initialConditions ?? throw new ArgumentNullException(nameof(initialConditions));
if (InitialConditions.EngineSpeedRpm > Model.MaximumEngineSpeedRpm ||
InitialConditions.EngineRunning && InitialConditions.EngineSpeedRpm < Model.IdleSpeedRpm ||
InitialConditions.EngineTemperatureCelsius != Model.InitialEngineTemperatureCelsius ||
InitialConditions.Gear > Model.ForwardGearRatios.Count)
{
throw new ArgumentException("Initial engine speed, gear, and temperature must be compatible with the selected model.");
}
if (InitialConditions.EngineRunning && InitialConditions.Gear > 0)
{
var expectedRpm = CoupledEngineSpeed(
InitialConditions.VehicleSpeedMetersPerSecond,
InitialConditions.Gear,
Model);
if (Math.Abs(InitialConditions.EngineSpeedRpm - expectedRpm) > 1e-8 ||
expectedRpm < Model.IdleSpeedRpm)
{
throw new ArgumentException(
"An initial in-gear condition must be locked to the configured wheel/gear ratio; launch slip is not an independent initial input.");
}
}
ArgumentNullException.ThrowIfNull(scenario);
var phases = scenario.ToArray();
if (phases.Length != 5 ||
phases.Any(phase => phase is null) ||
!phases.Select(phase => phase.Kind).SequenceEqual(
[
DynamicsScenarioPhaseKind.WarmIdle,
DynamicsScenarioPhaseKind.Accelerate,
DynamicsScenarioPhaseKind.Cruise,
DynamicsScenarioPhaseKind.Brake,
DynamicsScenarioPhaseKind.ReturnIdle
]) ||
phases[0].TargetSpeedMetersPerSecond != 0 ||
phases[1].TargetSpeedMetersPerSecond is <= 0 or > 150 ||
phases[2].TargetSpeedMetersPerSecond != phases[1].TargetSpeedMetersPerSecond ||
phases[3].TargetSpeedMetersPerSecond != 0 ||
phases[4].TargetSpeedMetersPerSecond != 0 ||
phases[2].DurationSeconds < 300 ||
phases[4].DurationSeconds < 10)
{
throw new ArgumentException("Scenario must define warm idle, acceleration, cruise, braking and return-idle phases in order.", nameof(scenario));
}
var maximumCoupledSpeed = Model.MaximumEngineSpeedRpm *
(2 * Math.PI * Model.WheelRadiusMeters) / 60 /
(Model.ForwardGearRatios[^1] * Model.FinalDriveRatio);
if (phases[1].TargetSpeedMetersPerSecond > maximumCoupledSpeed ||
InitialConditions.VehicleSpeedMetersPerSecond > maximumCoupledSpeed)
{
throw new ArgumentException(
$"Scenario target or initial speed exceeds the configured top-gear redline envelope of {maximumCoupledSpeed:F4} m/s.");
}
FormatVersion = formatVersion;
ProfileRevision = profileRevision;
Scenario = Array.AsReadOnly(phases);
ConfigurationIdentifier = CreateFingerprint();
}
public int FormatVersion { get; }
public string ProfileIdentifier { get; }
public int ProfileRevision { get; }
public string VehicleIdentifier { get; }
public string EngineModuleIdentifier { get; }
public string? EngineCalibrationReference { get; }
public string TransmissionModuleIdentifier { get; }
public string? TransmissionCalibrationReference { get; }
public string ModelIdentifier { get; }
public int ModelVersion { get; }
public DynamicsModelParameters Model { get; }
public DynamicsInitialConditions InitialConditions { get; }
public IReadOnlyList<DynamicsScenarioPhase> Scenario { get; }
[JsonIgnore] public string ConfigurationIdentifier { get; }
private static double CoupledEngineSpeed(double speedMetersPerSecond, int gear, DynamicsModelParameters model) =>
speedMetersPerSecond / (2 * Math.PI * model.WheelRadiusMeters) * 60 *
model.ForwardGearRatios[gear - 1] * model.FinalDriveRatio;
public void ValidateAgainst(VehicleProfile profile)
{
ArgumentNullException.ThrowIfNull(profile);
if (!Same(ProfileIdentifier, profile.ProfileIdentifier) ||
ProfileRevision != profile.Revision ||
!Same(VehicleIdentifier, profile.Vehicle.VehicleIdentifier))
{
throw new ArgumentException("Dynamics configuration does not bind to the exact selected profile identity and revision.", nameof(profile));
}
var engine = profile.Modules.FirstOrDefault(module =>
StringComparer.OrdinalIgnoreCase.Equals(module.InstanceIdentifier, EngineModuleIdentifier))
?? throw new ArgumentException(
$"Engine module reference '{EngineModuleIdentifier}' does not exist in profile '{profile.ProfileIdentifier}' revision {profile.Revision}.",
nameof(profile));
var transmission = profile.Modules.FirstOrDefault(module =>
StringComparer.OrdinalIgnoreCase.Equals(module.InstanceIdentifier, TransmissionModuleIdentifier))
?? throw new ArgumentException(
$"Transmission module reference '{TransmissionModuleIdentifier}' does not exist in profile '{profile.ProfileIdentifier}' revision {profile.Revision}.",
nameof(profile));
if (!SameOptional(EngineCalibrationReference, engine.CalibrationIdentifier) ||
!SameOptional(TransmissionCalibrationReference, transmission.CalibrationIdentifier))
{
throw new ArgumentException(
$"Dynamics calibration reference conflicts with profile '{profile.ProfileIdentifier}' revision {profile.Revision} for engine module '{EngineModuleIdentifier}' or transmission module '{TransmissionModuleIdentifier}'.",
nameof(profile));
}
if (InitialConditions.Gear > Model.ForwardGearRatios.Count ||
InitialConditions.EngineSpeedRpm > Model.MaximumEngineSpeedRpm)
{
throw new ArgumentException("Initial dynamics conditions are incompatible with the model's gear or speed range.", nameof(profile));
}
}
public static DynamicsConfiguration CreateWarmBaseline(VehicleProfile profile)
{
ArgumentNullException.ThrowIfNull(profile);
var engine = profile.Modules.FirstOrDefault(module =>
module.Role.Contains("engine", StringComparison.OrdinalIgnoreCase));
var transmission = profile.Modules.FirstOrDefault(module =>
module.Role.Contains("transmission", StringComparison.OrdinalIgnoreCase));
if (engine is null || transmission is null)
{
throw new ArgumentException("The synthetic dynamics example requires explicit engine and transmission modules.", nameof(profile));
}
var model = new DynamicsModelParameters(
stepSeconds: 0.1,
vehicleMassKilograms: 1_800,
wheelRadiusMeters: 0.34,
dragAreaSquareMeters: 0.68,
rollingResistanceCoefficient: 0.012,
airDensityKilogramsPerCubicMeter: 1.2,
gravityMetersPerSecondSquared: 9.80665,
drivetrainEfficiency: 0.9,
maximumBrakeForceNewtons: 10_000,
idleSpeedRpm: 650,
maximumEngineSpeedRpm: 5_000,
warmIdleTargetRpm: 650,
launchSlipEndSpeedMetersPerSecond: 2.5,
idleFuelRateKilogramsPerSecond: 0.00045,
fuelKilogramsPerJoule: 0.00000012,
ambientTemperatureCelsius: 20,
initialEngineTemperatureCelsius: 88,
equilibriumEngineTemperatureCelsius: 90,
thermalResponsePerSecond: 0.015,
engineTorqueCurve:
[
new(650, 240),
new(1_000, 300),
new(2_000, 360),
new(3_200, 350),
new(4_200, 300),
new(5_000, 180)
],
forwardGearRatios: [3.5, 2.2, 1.4, 0.9],
upshiftSpeedsRpm: [4_000, 4_000, 4_000, 4_000],
downshiftSpeedsRpm: [1_450, 1_450, 1_450, 1_450],
finalDriveRatio: 3.6);
return new DynamicsConfiguration(
1,
profile.ProfileIdentifier,
profile.Revision,
profile.Vehicle.VehicleIdentifier,
engine.InstanceIdentifier,
engine.CalibrationIdentifier,
transmission.InstanceIdentifier,
transmission.CalibrationIdentifier,
"autoforge.synthetic.longitudinal",
1,
model,
new DynamicsInitialConditions(false, 0, 0, 0, 88, 0, 0),
[
new(DynamicsScenarioPhaseKind.WarmIdle, 0, 10),
new(DynamicsScenarioPhaseKind.Accelerate, 20.1168, 60),
new(DynamicsScenarioPhaseKind.Cruise, 20.1168, 300),
new(DynamicsScenarioPhaseKind.Brake, 0, 60),
new(DynamicsScenarioPhaseKind.ReturnIdle, 0, 10)
]);
}
private string CreateFingerprint()
{
var json = JsonSerializer.SerializeToUtf8Bytes(this, FingerprintOptions);
var hash = SHA256.HashData(json);
return $"sha256:v1:{Convert.ToHexString(hash).ToLowerInvariant()}";
}
private static string RequireText(string value, string name)
{
ArgumentException.ThrowIfNullOrWhiteSpace(value, name);
if (!StringComparer.Ordinal.Equals(value, value.Trim()))
{
throw new ArgumentException("Configuration identifiers must not contain surrounding whitespace.", name);
}
return value;
}
private static string? OptionalText(string? value, string name) =>
value is null ? null : RequireText(value, name);
private static bool Same(string left, string right) =>
StringComparer.OrdinalIgnoreCase.Equals(left, right);
private static bool SameOptional(string? left, string? right) =>
left is null ? right is null : right is not null && Same(left, right);
}