Cleanup, fixes, and documentation

Author: SteelFill

Source/Documentation/Manual/physics.rst

@@ -2976,11 +2976,23 @@ MaxAuxilaryChargingRate and EmergencyResChargingRate.
    single: ORTSEmergencyValveActuationRate
    single: ORTSEmergencyDumpValveRate
    single: ORTSEmergencyDumpValveTimer
+   single: ORTSEmergencyResQuickRelease
    single: ORTSMainResPipeAuxResCharging
    single: ORTSBrakeRelayValveRatio
    single: ORTSEngineBrakeRelayValveRatio
    single: ORTSBrakeRelayValveApplicationRate
    single: ORTSBrakeRelayValveReleaseRate
+   single: ORTSMaxTripleValveCylinderPressure
+   single: ORTSMaxServiceCylinderPressure
+   single: ORTSUniformChargingThreshold
+   single: ORTSUniformChargingRatio
+   single: ORTSQuickServiceLimit
+   single: ORTSQuickServiceApplicationRate
+   single: ORTSQuickServiceVentRate
+   single: ORTSAcceleratedApplicationFactor
+   single: ORTSAcceleratedApplicationMaxVentRate
+   single: ORTSInitialApplicationThreshold
+   single: ORTSCylinderSpringPressure
    single: ORTSMainResChargingRate
    single: ORTSEngineBrakeReleaseRate
    single: ORTSEngineBrakeApplicationRate
@@ -3012,11 +3024,14 @@ MaxAuxilaryChargingRate and EmergencyResChargingRate.
   brake actuation of the triple valve. If the pressure in the brake pipe
   decreases at a higher rate than specified, the triple valve will switch to
   emergency mode.
-- ``Wagon(ORTSEmergencyDumpValveRate)``-- Rate at which BP is locally discharged
+- ``Wagon(ORTSEmergencyDumpValveRate`` -- Rate at which BP is locally discharged
   at every wagon during an emergency brake application.
-- ``Wagon(ORTSEmergencyDumpValveTimer)``-- Timer for emergency dump valve to close
+- ``Wagon(ORTSEmergencyDumpValveTimer`` -- Timer for emergency dump valve to close
   after it is activated. If set to 0, it will close as soon as BP is discharged.
   Default value will prevent BP from being charged for 2 minutes.
+- ``Wagon(ORTSEmergencyResQuickRelease`` -- Set to 1 (default 0) to enable quick release,
+  in which emergency reservoir air is used to increase the brake pipe pressure
+  during release. Remains active until brake cylinder pressure drops below 5 psi.
 - ``Wagon(ORTSMainResPipeAuxResCharging`` -- Boolean value that indicates,
   for twin pipe systems, if the main reservoir pipe is used for charging the auxiliary
   reservoirs. If set to false, the main reservoir pipe will not be used
@@ -3037,6 +3052,40 @@ MaxAuxilaryChargingRate and EmergencyResChargingRate.
   by the triple valve. For example, UIC distributors set maximum cylinder pressure
   to 3.8 bar when brake pipe is below 3.5 bar, and further brake pipe discharging
   does not increase cylinder pressure.
+- ``Wagon(ORTSMaxServiceCylinderPressure`` -- Sets the maximum cylinder pressure
+  demanded during service applications. During emergency applications,
+  brake cylinder pressure is instead limited by ``ORTSMaxTripleValveCylinderPressure``.
+- ``Wagon(ORTSUniformChargingThreshold`` -- The pressure difference between the brake
+  pipe and auxiliary reservoir at which uniform charging activates during release
+  (default 3 psi), usually used to reduce the rate of auxiliary reservoir charging.
+- ``Wagon(ORTSUniformChargingRatio`` -- Factor used to divide auxiliary reservoir
+  charging rate by when uniform charging is active. Eg: setting of 2 will halve
+  charging rate while uniform charging is active (defaults to 0, disabling the feature).
+- ``Wagon(ORTSQuickServiceLimit`` -- Quick service activates when triple valve
+  initially changes from release to apply, and will remain active until brake
+  cylinder pressure reaches the pressure specified here (default 0,
+  which disables quick service).
+- ``Wagon(ORTSQuickServiceApplicationRate`` -- Optional setting for brake cylinder
+  application rate during quick service, can be used to increase speed of initial
+  applications. Has no effect if set lower than ``MaxApplicationRate`` (default 0).
+- ``Wagon(ORTSQuickServiceVentRate`` -- Optional ability for the brake pipe
+  pressure to be locally reduced at the specified rate while quick service is active
+  (default 0).
+- ``Wagon(ORTSAcceleratedApplicationFactor`` -- Triple valves can speed up applications
+  by measuring the rate of brake pipe reduction, multiplying the reduction
+  by the factor specified here, then locally venting that amount of brake pipe air.
+  Eg: a factor of 0.5 will speed up brake pipe propogation by +50%. Warning: Large
+  factors can cause out of control brake pipe reductions, avoid settings larger
+  than 1 (default 0, which disables the feature entirely).
+- ``Wagon(ORTSAcceleratedApplicationMaxVentRate`` -- Sets the maximum rate
+  at which accelerated application will reduce the brake pipe pressure
+  (default 5 psi/s).
+- ``Wagon(ORTSInitialApplicationThreshold`` -- The pressure difference between
+  the brake pipe and auxiliary reservoir at which the triple valve will
+  change from release to apply (default 1 psi).
+- ``Wagon(ORTSCylinderSpringPressure`` -- Below the specified pressure, no
+  brake force will be developed, simulating the pressure required to
+  overcome the brake cylinder return spring (default 0).
 - ``Engine(ORTSMainResChargingRate`` -- Rate of main reservoir pressure change
   in psi per second when the compressor is on (default .4).
 - ``Engine(ORTSEngineBrakeReleaseRate`` -- Rate of engine brake pressure

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

@@ -75,8 +75,8 @@ public class AirSinglePipe : MSTSBrakeSystem
         protected float QuickServiceLimitPSI;
         protected float QuickServiceApplicationRatePSIpS;
         protected float QuickServiceVentRatePSIpS;
-        protected float AcceleratedApplicationRatio;
-        protected float AcceleratedApplicationLimitPSIpS = 10.0f;
+        protected float AcceleratedApplicationFactor;
+        protected float AcceleratedApplicationLimitPSIpS = 5.0f;
         protected float InitialApplicationThresholdPSI = 1.0f;
         protected float BrakeCylinderSpringPressurePSI;
         protected float ServiceMaxCylPressurePSI;
@@ -161,7 +161,7 @@ public override void InitializeFromCopy(BrakeSystem copy)
             QuickServiceLimitPSI = thiscopy.QuickServiceLimitPSI;
             QuickServiceApplicationRatePSIpS = thiscopy.QuickServiceApplicationRatePSIpS;
             QuickServiceVentRatePSIpS = thiscopy.QuickServiceVentRatePSIpS;
-            AcceleratedApplicationRatio = thiscopy.AcceleratedApplicationRatio;
+            AcceleratedApplicationFactor = thiscopy.AcceleratedApplicationFactor;
             AcceleratedApplicationLimitPSIpS = thiscopy.AcceleratedApplicationLimitPSIpS;
             InitialApplicationThresholdPSI = thiscopy.InitialApplicationThresholdPSI;
             BrakeCylinderSpringPressurePSI = thiscopy.BrakeCylinderSpringPressurePSI;
@@ -303,8 +303,8 @@ public override void Parse(string lowercasetoken, STFReader stf)
                 case "wagon(ortsquickservicelimit": QuickServiceLimitPSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, null); break;
                 case "wagon(ortsquickserviceapplicationrate": QuickServiceApplicationRatePSIpS = stf.ReadFloatBlock(STFReader.UNITS.PressureRateDefaultPSIpS, null); break;
                 case "wagon(ortsquickserviceventrate": QuickServiceVentRatePSIpS = stf.ReadFloatBlock(STFReader.UNITS.PressureRateDefaultPSIpS, null); break;
-                case "wagon(ortsacceleratedapplicationratio": AcceleratedApplicationRatio = stf.ReadFloatBlock(STFReader.UNITS.None, null); break;
-                case "wagon(ortsacceleratedapplicationmaxventrate": AcceleratedApplicationLimitPSIpS = stf.ReadFloatBlock(STFReader.UNITS.PressureRateDefaultPSIpS, 10.0f); break;
+                case "wagon(ortsacceleratedapplicationfactor": AcceleratedApplicationFactor = stf.ReadFloatBlock(STFReader.UNITS.None, null); break;
+                case "wagon(ortsacceleratedapplicationmaxventrate": AcceleratedApplicationLimitPSIpS = stf.ReadFloatBlock(STFReader.UNITS.PressureRateDefaultPSIpS, 5.0f); break;
                 case "wagon(ortsinitialapplicationthreshold": InitialApplicationThresholdPSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, 1.0f); break;
                 case "wagon(ortscylinderspringpressure": BrakeCylinderSpringPressurePSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, null); break;
                 case "wagon(ortsmaxservicecylinderpressure": ServiceMaxCylPressurePSI = stf.ReadFloatBlock(STFReader.UNITS.PressureDefaultPSI, null); break;
@@ -512,7 +512,6 @@ public void UpdateTripleValveState(float elapsedClockSeconds)
                 }
             }
             else EmergencyDumpStartTime = null;
-            prevBrakePipePressurePSI = BrakeLine1PressurePSI;
         }
 
         public override void Update(float elapsedClockSeconds)
@@ -574,9 +573,9 @@ public override void Update(float elapsedClockSeconds)
                 }
                 else
                 {
-                    if (TripleValveState == ValveState.Apply && AcceleratedApplicationRatio > 0) // Accelerated application: Air is vented from the brake pipe to speed up service applications
+                    if (AcceleratedApplicationFactor > 0) // Accelerated application: Air is vented from the brake pipe to speed up service applications
                     {
-                        dpPipe = Math.Min(BrakePipeChange * AcceleratedApplicationRatio, elapsedClockSeconds * AcceleratedApplicationLimitPSIpS); // Amount of air vented is proportional to pressure reduction from external sources
+                        dpPipe = Math.Min(BrakePipeChange * AcceleratedApplicationFactor, elapsedClockSeconds * AcceleratedApplicationLimitPSIpS); // Amount of air vented is proportional to pressure reduction from external sources
                     }
                     dp = elapsedClockSeconds * MaxApplicationRatePSIpS;
                 }
@@ -686,14 +685,17 @@ public override void Update(float elapsedClockSeconds)
             }
 
             // Handle brake release: reduce cylinder pressure if all triple valve, EP holding valve and retainers allow so
+            if (threshold < 2.2f) // Prevent brakes getting stuck with a small amount of air on distributor systems
+                threshold = 0;
             float minCylPressurePSI = Math.Max(threshold, RetainerPressureThresholdPSI);
+
             if (TripleValveState == ValveState.Release && HoldingValve == ValveState.Release && AutoCylPressurePSI > minCylPressurePSI)
             {
                 float dp = elapsedClockSeconds * ReleaseRatePSIpS;
-                if (AutoCylPressurePSI < minCylPressurePSI + 1)
+                if (AutoCylPressurePSI < threshold + 1 && threshold > 2.2f)
                     dp *= MathHelper.Clamp(AutoCylPressurePSI - threshold, 0.1f, 1.0f); // Reduce release rate if nearing target pressure to prevent toggling between release and lap
                 if (AutoCylPressurePSI - dp < minCylPressurePSI)
-                    dp = AutoCylPressurePSI-minCylPressurePSI;
+                    dp = AutoCylPressurePSI - minCylPressurePSI;
                 if (dp < 0)
                     dp = 0;
                 AutoCylPressurePSI -= dp;
@@ -751,6 +753,8 @@ public override void Update(float elapsedClockSeconds)
             {
                 if (AuxResPressurePSI < BrakeLine1PressurePSI && (valveType == MSTSWagon.BrakeValveType.Distributor ? true : TripleValveState == ValveState.Release) && !BleedOffValveOpen)
                 {
+                    if (AuxResPressurePSI > BrakeLine1PressurePSI - 1)
+                        dpAux *= MathHelper.Clamp(BrakeLine1PressurePSI - AuxResPressurePSI, 0.1f, 1.0f); // Reduce recharge rate if nearing target pressure to smooth out changes in brake pipe
                     if (UniformChargingRatio > 0) // Uniform charging: Aux res charging is slowed down when the brake pipe is substantially higher than the aux res
                     {
                         if (!UniformChargingActive && AuxResPressurePSI < BrakeLine1PressurePSI - UniformChargingThresholdPSI)
@@ -965,7 +969,7 @@ public override void Update(float elapsedClockSeconds)
 
             if (!Car.BrakesStuck)
             {
-                Car.BrakeShoeForceN = Car.MaxBrakeForceN * Math.Min(CylPressurePSI / MaxCylPressurePSI, 1);
+                Car.BrakeShoeForceN = Car.MaxBrakeForceN * MathHelper.Clamp((CylPressurePSI - BrakeCylinderSpringPressurePSI) / (MaxCylPressurePSI - BrakeCylinderSpringPressurePSI), 0, 1);
                 if (Car.BrakeShoeForceN < Car.MaxHandbrakeForceN * HandbrakePercent / 100)
                     Car.BrakeShoeForceN = Car.MaxHandbrakeForceN * HandbrakePercent / 100;
             }