Improve blended braking response when using advanced brake cylinders and dynamic brake ramp up

Author: SteelFill

Source/Documentation/Manual/physics.rst

@@ -3343,6 +3343,7 @@ the following parameters will adjust the behaviour of air brakes:
 .. index::
    single: DynamicBrakeHasAutoBailOff
    single: ORTSDynamicBrakesHasPartialBailOff
+   single: ORTSDynamicBlendingRetainedPressure
    single: ORTSTrainDynamicBlendingTable
    single: ORTSDynamicBrakeReplacementWithEngineBrake 
    single: ORTSDynamicBrakeReplacementWithEngineBrakeAtSpeed
@@ -3353,6 +3354,10 @@ the following parameters will adjust the behaviour of air brakes:
   air brakes are released while dynamic brakes satisfy the train brake demand.
   If dynamic braking is not sufficient, air brakes will be partially applied
   so the combination air+dynamic provides the required brake demand.
+- ``Engine(ORTSDynamicBlendingRetainedPressure`` -- Sets the brake cylinder
+  pressure which, when used in combination with ORTSDynamicBrakesHasPartialBailOff,
+  will remain applied regardless of the blended dynamic brake force. This
+  pressure is also the minimum pressure at which the blended braking system will activate.
 
 Sometimes the train brake controller is capable to apply the dynamic
 brakes for the whole consist, usually as a first step before air brakes

Source/Orts.Simulation/Simulation/RollingStocks/MSTSLocomotive.cs

@@ -420,6 +420,7 @@ public float OdometerM
         public double? DynamicBrakeCommandStartTime;
         protected bool DynamicBrakeBlendingOverride; // true when DB lever >0% should always override the blending. When false, the bigger command is applied.
         protected bool DynamicBrakeBlendingForceMatch = true; // if true, dynamic brake blending tries to achieve the same braking force as the airbrake would have.
+        public float DynamicBrakeBlendingRetainedPressurePSI { get; private set; } = -1.0f; // the amount of pressure that will always be retained in the brake cylinders during blended braking
         protected bool DynamicBrakeControllerSetupLock; // if true if dynamic brake lever will lock until dynamic brake is available
 
         public float DynamicBrakeBlendingPercent { get; protected set; } = -1;
@@ -1177,6 +1178,7 @@ public override void Parse(string lowercasetoken, STFReader stf)
                     break;
                 case "engine(ortsdynamicblendingoverride": DynamicBrakeBlendingOverride = stf.ReadBoolBlock(false); break;
                 case "engine(ortsdynamicblendingforcematch": DynamicBrakeBlendingForceMatch = stf.ReadBoolBlock(false); break;
+                case "engine(ortsdynamicblendingretainedpressure": DynamicBrakeBlendingRetainedPressurePSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, null); break;
                 case "engine(vacuumbrakeshasvacuumpump": VacuumPumpFitted = stf.ReadBoolBlock(false); break;
                 case "engine(enginecontrollers(ortssteamheat": SteamHeatController.Parse(stf); break;
                 case "engine(name": stf.MustMatch("("); LocomotiveName = stf.ReadString(); break;
@@ -1334,6 +1336,7 @@ public override void Copy(MSTSWagon copy)
             DynamicBrakeCommandStartTime = locoCopy.DynamicBrakeCommandStartTime;
             DynamicBrakeBlendingOverride = locoCopy.DynamicBrakeBlendingOverride;
             DynamicBrakeBlendingForceMatch = locoCopy.DynamicBrakeBlendingForceMatch;
+            DynamicBrakeBlendingRetainedPressurePSI = locoCopy.DynamicBrakeBlendingRetainedPressurePSI;
             DynamicBrakeControllerSetupLock = locoCopy.DynamicBrakeControllerSetupLock;
 
             MainPressureUnit = locoCopy.MainPressureUnit;
@@ -2014,6 +2017,15 @@ protected void CorrectBrakingParams()
                 (MaxDynamicBrakeForceN / MaxContinuousForceN < 0.3f && MaxDynamicBrakeForceN == 20000))
                     MaxDynamicBrakeForceN = Math.Min (MaxContinuousForceN * 0.5f, 150000); // 20000 is suggested as standard value in the MSTS documentation, but in general it is a too low value
             }
+
+            // Define blending retained pressure if it was left undefined
+            if (DynamicBrakeBlendingRetainedPressurePSI < 0)
+            {
+                if (BrakeSystem is AirSinglePipe airSystem)
+                    DynamicBrakeBlendingRetainedPressurePSI = 2.0f * airSystem.BrakeCylinderSpringPressurePSI;
+                else
+                    DynamicBrakeBlendingRetainedPressurePSI = 0.0f;
+            }
         }
 
         /// <summary>
@@ -2022,24 +2034,38 @@ protected void CorrectBrakingParams()
         public void DynamicBrakeBlending(float elapsedClockSeconds)
         {
             // Local blending
-            if (Math.Abs(SpeedMpS) > DynamicBrakeSpeed1MpS && airPipeSystem != null && airPipeSystem.AutoCylPressurePSI > 0.1f
+            float autoDemandedPressurePSI = airPipeSystem.AutoCylPressurePSI * airPipeSystem.RelayValveRatio;
+
+            if (Math.Abs(SpeedMpS) > DynamicBrakeSpeed1MpS && airPipeSystem != null && autoDemandedPressurePSI > DynamicBrakeBlendingRetainedPressurePSI
                 && ThrottlePercent == 0 && !(DynamicBrakeController != null && DynamicBrakeBlendingOverride && DynamicBrakeController.SavedValue > 0))
             {
-                float maxCylPressurePSI = airPipeSystem.GetMaxCylPressurePSI();
-                float target = airPipeSystem.AutoCylPressurePSI * airPipeSystem.RelayValveRatio / maxCylPressurePSI;
+                float target = (autoDemandedPressurePSI - DynamicBrakeBlendingRetainedPressurePSI) /
+                    (airPipeSystem.ReferencePressurePSI - DynamicBrakeBlendingRetainedPressurePSI);
 
                 if (DynamicBrakeBlendingForceMatch)
                 {
-                    float diff = target * FrictionBrakeBlendingMaxForceN - DynamicBrakeForceN;
-                    float threshold = 100;
-                    if (diff > threshold && DynamicBrakePercent < 100)
-                        DynamicBrakeBlendingPercent = Math.Min(DynamicBrakePercent + 100 * elapsedClockSeconds, 100);
-                    else if (diff < -threshold && DynamicBrakePercent > 1)
-                        DynamicBrakeBlendingPercent = Math.Max(DynamicBrakePercent - 100 * elapsedClockSeconds, 1);
+                    if (DynamicBrake)
+                    {
+                        float diff = target * FrictionBrakeBlendingMaxForceN - DynamicBrakeForceN;
+                        float normDiff = diff / MaxDynamicBrakeForceN;
+
+                        if (Math.Abs(diff) > 100.0f)
+                        {
+                            // Limit rate of change to reduce overshoots
+                            if (diff > 0 && DynamicBrakeForceRampUpNpS > 0)
+                                normDiff = Math.Min(normDiff, DynamicBrakeForceRampUpNpS / MaxDynamicBrakeForceN);
+                            if (diff < 0 && DynamicBrakeForceRampDownNpS > 0)
+                                normDiff = Math.Max(normDiff, -DynamicBrakeForceRampDownNpS / MaxDynamicBrakeForceN);
+
+                            DynamicBrakeBlendingPercent = MathHelper.Clamp(DynamicBrakePercent + 100.0f * normDiff * elapsedClockSeconds, 1f, 100f);
+                        }
+                    }
+                    else // Don't increase dynamic brake setting until set-up has completed
+                        DynamicBrakeBlendingPercent = 1.0f;
                 }
                 else
                 {
-                    DynamicBrakeBlendingPercent = target * 100;
+                    DynamicBrakeBlendingPercent = MathHelper.Clamp(target * 100, 1f, 100f);
                 }
             }
             else

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/Brakes/MSTS/AirSinglePipe.cs

@@ -81,7 +81,7 @@ public enum BrakeValveType
         protected float ControlResPressurePSI = 64;
         protected float FullServPressurePSI = 50;
         protected float MaxCylPressurePSI;
-        protected float ReferencePressurePSI;
+        public float ReferencePressurePSI { get; protected set; }
         protected float MaxTripleValveCylPressurePSI;
         protected float AuxResVolumeM3;
         protected float AuxCylVolumeRatio;
@@ -143,7 +143,7 @@ public enum BrakeValveType
         protected float AcceleratedApplicationLimitPSIpS = 5.0f;
         protected float InitialApplicationThresholdPSI;
         protected float TripleValveSensitivityPSI;
-        protected float BrakeCylinderSpringPressurePSI;
+        public float BrakeCylinderSpringPressurePSI { get; protected set; }
         protected float ServiceMaxCylPressurePSI;
         protected float ServiceApplicationRatePSIpS;
         protected float TwoStageLowPressurePSI;
@@ -1721,25 +1721,21 @@ public override void Update(float elapsedClockSeconds)
                             if (loco.Train.DetermineDPLeadLocomotive(loco) is MSTSLocomotive lead && (lead.BailOff || (lead.EngineBrakeController != null && lead.EngineBrakeController.TrainBrakeControllerState == ControllerState.BailOff)))
                             {
                                 if (BrakeValve == BrakeValveType.Distributor)
-                                {
                                     ControlResPressurePSI = 0;
 
-                                    if (loco.AttachedTender?.BrakeSystem is AirSinglePipe tenderBrakes)
-                                        tenderBrakes.ControlResPressurePSI = 0;
-                                }
-                                else
+                                float dp = Math.Max(MaxReleaseRatePSIpS, loco.EngineBrakeReleaseRatePSIpS) * elapsedClockSeconds;
+                                AutoCylPressurePSI -= dp;
+                                if (AutoCylPressurePSI < 0)
+                                    AutoCylPressurePSI = 0;
+
+                                if (loco.AttachedTender?.BrakeSystem is AirSinglePipe tenderBrakes)
                                 {
-                                    float dp = Math.Max(MaxReleaseRatePSIpS, loco.EngineBrakeReleaseRatePSIpS) * elapsedClockSeconds;
-                                    AutoCylPressurePSI -= dp;
-                                    if (AutoCylPressurePSI < 0)
-                                        AutoCylPressurePSI = 0;
+                                    if (tenderBrakes.BrakeValve == BrakeValveType.Distributor)
+                                        tenderBrakes.ControlResPressurePSI = 0;
 
-                                    if (loco.AttachedTender?.BrakeSystem is AirSinglePipe tenderBrakes)
-                                    {
-                                        tenderBrakes.AutoCylPressurePSI -= dp;
-                                        if (tenderBrakes.AutoCylPressurePSI < 0)
-                                            tenderBrakes.AutoCylPressurePSI = 0;
-                                    }
+                                    tenderBrakes.AutoCylPressurePSI -= dp;
+                                    if (tenderBrakes.AutoCylPressurePSI < 0)
+                                        tenderBrakes.AutoCylPressurePSI = 0;
                                 }
                             }
                         }
@@ -1750,19 +1746,23 @@ public override void Update(float elapsedClockSeconds)
                         {
                             if (loco.DynamicBrakePartialBailOff)
                             {
-                                var requiredBrakeForceN = MathHelper.Max((AutoCylPressurePSI * RelayValveRatio - BrakeCylinderSpringPressurePSI)
-                                    / (ReferencePressurePSI - BrakeCylinderSpringPressurePSI), 0) * Car.FrictionBrakeBlendingMaxForceN;
-                                var localBrakeForceN = loco.DynamicBrakeForceN + MathHelper.Max((CylPressurePSI - BrakeCylinderSpringPressurePSI)
-                                    / (ReferencePressurePSI - BrakeCylinderSpringPressurePSI), 0) * Car.FrictionBrakeBlendingMaxForceN;
+                                var requiredBrakeForceN = (AutoCylPressurePSI * RelayValveRatio - loco.DynamicBrakeBlendingRetainedPressurePSI)
+                                    / (ReferencePressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI) * Car.FrictionBrakeBlendingMaxForceN;
+                                var localBrakeForceN = loco.DynamicBrakeForceN + (CylPressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI)
+                                    / (ReferencePressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI) * Car.FrictionBrakeBlendingMaxForceN;
                                 if (localBrakeForceN > requiredBrakeForceN - 0.15f * Car.FrictionBrakeBlendingMaxForceN)
                                 {
-                                    demandedPressurePSI = Math.Min(Math.Max((requiredBrakeForceN - loco.DynamicBrakeForceN) / Car.FrictionBrakeBlendingMaxForceN * ReferencePressurePSI
-                                        + BrakeCylinderSpringPressurePSI, 0), MaxCylPressurePSI);
+                                    demandedPressurePSI = MathHelper.Clamp((requiredBrakeForceN - loco.DynamicBrakeForceN) / Car.FrictionBrakeBlendingMaxForceN *
+                                        (ReferencePressurePSI - loco.DynamicBrakeBlendingRetainedPressurePSI) + loco.DynamicBrakeBlendingRetainedPressurePSI,
+                                        loco.DynamicBrakeBlendingRetainedPressurePSI, MaxCylPressurePSI);
                                     if (demandedPressurePSI > CylPressurePSI && demandedPressurePSI < CylPressurePSI + 4) // Allow some margin for unnecessary air brake application
                                     {
                                         demandedPressurePSI = CylPressurePSI;
                                     }
                                     demandedPressurePSI /= RelayValveRatio;
+
+                                    if (demandedPressurePSI > AutoCylPressurePSI)
+                                        demandedPressurePSI = AutoCylPressurePSI;
                                 }
                             }
                             else if (loco.DynamicBrakeAutoBailOff)