Merge pull request #1067 from cesarBLG/controller-delays

Traction and dynamic brake retardation

Author: cesarBLG

Source/Documentation/Manual/physics.rst

@@ -425,6 +425,7 @@ locomotive (regardless of transmission type) are as follows:
    single: MaxPower
    single: MaxForce
    single: MaxContinuousForce
+   single: ORTSTractiveForceIsPowerLimited
 
 ``ORTSDieselEngineMaxPower`` ==> sets the maximum power output at the 
 shaft of the diesel engine (or prime mover).
@@ -438,6 +439,9 @@ wheels when starting.
 continuously supply to the wheels without exceeding the design specifications. 
 Typically this is linked to a particular speed (see next parameter).
 
+``ORTSTractiveForceIsPowerLimited`` ==> determines if tractive force curves
+shall be limited to the available output power from the diesel engine.
+
 .. index::
    single: ORTSSpeedOfMaxContinuousForce
    single: MaxVelocity
@@ -1141,6 +1145,67 @@ with the ``ORTSTractionMotorType ( AC ) `` parameter, to be inserted in the Engi
 section of the ENG file. The use of this motor will have an impact on wheel slip,
 because the wheel speed never exceeds the frequency of the rotating magnetic field.
 
+Traction force retardation
+''''''''''''''''''''''''''
+
+.. index::
+    single: ORTSTractiveForceRampUpRate
+    single: ORTSTractiveForceRampDownRate
+    single: ORTSTractiveForceRampDownToZeroRate
+    single: ORTSTractivePowerRampUpRate
+    single: ORTSTractivePowerRampDownRate
+    single: ORTSTractivePowerRampDownToZeroRate
+    single: ORTSDynamicBrakeForceRampUpRate
+    single: ORTSDynamicBrakeForceRampDownRate
+    single: ORTSDynamicBrakeForceRampDownToZeroRate
+    single: ORTSDynamicBrakePowerRampUpRate
+    single: ORTSDynamicBrakePowerRampDownRate
+    single: ORTSDynamicBrakePowerRampDownToZeroRate
+    single: ORTSDelayTimeBeforeUpdating
+
+When the driver sets full throttle, the control electronics may not apply the full
+tractive force instantly, but it will instead linearly apply force until reaching
+the target demand. This can be tuned both for traction and dynamic braking by inserting
+``ORTSTractiveForceRampUpRate``, ``ORTSTractiveForceRampDownRate``,
+``ORTSTractiveForceRampDownToZeroRate``, ``ORTSDynamicBrakeForceRampUpRate``,
+``ORTSDynamicBrakeForceRampDownRate`` and ``ORTSDynamicBrakeForceRampDownToZeroRate``
+in the .eng file. The value of each parameter determines the force increase/decrease
+rate. To include ramp up/down times also for power, use the equivalent
+``ORTSTractivePowerRampUpRate``, ``ORTSTractivePowerRampDownRate``,
+``ORTSTractivePowerRampDownToZeroRate``, ``ORTSDynamicBrakePowerRampUpRate``,
+``ORTSDynamicBrakePowerRampDownRate`` and ``ORTSDynamicBrakePowerRampDownToZeroRate``
+parameters.
+
+Example::
+
+  Engine (
+    ORTSTractiveForceRampUpRate ( 50kN/s )
+    ORTSTractiveForceRampDownRate ( 50kN/s )
+    ORTSTractiveForceRampDownToZeroRate ( 100kN/s )
+    ORTSDynamicBrakePowerRampUpRate ( 1000kW/s )
+    ORTSDynamicBrakeForceRampDownRate ( 50kN/s )
+  )
+
+Another possibility to avoid sudden variations in tractive force while the driver
+is moving the throttle, is to only update the throttle/brake demand when the lever
+has not been moved for a defined amount of time. This can be implemented using the
+``ORTSDelayTimeBeforeUpdating``, which has to be inserted for the desired
+controller in the ``EngineControllers`` block.
+
+Example::
+
+  Engine (
+    EngineControllers (
+      Throttle ( 0 1 0.1 0
+        NumNotches ( 0 )
+        ORTSDelayTimeBeforeUpdating ( 0.5s )
+      )
+      Brake_Dynamic ( 0 1 0.1 0
+        NumNotches ( 0 )
+        ORTSDelayTimeBeforeUpdating ( 1s )
+      )
+    )
+  )
 
 Steam Locomotives
 -----------------

Source/Orts.Parsers.Msts/STFReader.cs

@@ -647,7 +647,7 @@ public double ReadDouble(double? defaultValue)
         /// </summary>
         // Additional entries because MSTS has multiple default units, e.g. some speeds in metres/sec and others in miles/hr
         [Flags]
-        public enum UNITS
+        public enum UNITS : ulong
         {
             /// <summary>No unit parsing is done on the {constant_item} - which is obviously fastest
             /// </summary>
@@ -821,6 +821,16 @@ public enum UNITS
             /// </summary>            
             Energy = 1 << 29,
 
+            /// <summary>Valid Units: n/s, kn/s, lbf/s
+            /// <para>Scaled to newtons per second.</para>
+            /// </summary>
+            ForceRate = 1 << 30,
+
+            /// <summary>Valid Units: w/s, kw/s, hp/s
+            /// <para>Scaled to watts per second.</para>
+            /// </summary>
+            PowerRate = 1ul << 31,
+
             // "Any" is used where units cannot easily be specified, such as generic routines for interpolating continuous data from point values.
             // or interpreting locomotive cab attributes from the ORTSExtendedCVF experimental mechanism.
             // "Any" should not be used where the dimensions of a unit are predictable.
@@ -1170,6 +1180,23 @@ internal double ParseUnitSuffix(ref string constant, UNITS validUnits)
                     case "wh": return 3.6e3f;
                     case "kwh": return 3.6e6f;
                 }
+            if ((validUnits & UNITS.ForceRate) > 0)
+                switch (suffix)
+                {
+                    case "": return 1.0;
+                    case "n/s": return 1;
+                    case "kn/s": return 1e3;
+                    case "lbf/s": return 4.44822162;
+                    case "lb/s": return 4.44822162;
+                }
+            if ((validUnits & UNITS.PowerRate) > 0)
+                switch (suffix)
+                {
+                    case "": return 1.0;
+                    case "w/s": return 1;
+                    case "kw/s": return 1e3;
+                    case "hp/s": return 745.699872;
+                }
             STFException.TraceWarning(this, "Found a suffix '" + suffix + "' which could not be parsed as a " + validUnits.ToString() + " unit");
             return 1;
         }

Source/Orts.Simulation/Simulation/RollingStocks/MSTSControlTrailerCar.cs

@@ -263,7 +263,7 @@ public override string GetStatus()
         /// <summary>
         /// This function updates periodically the locomotive's motive force.
         /// </summary>
-        protected override void UpdateTractiveForce(float elapsedClockSeconds, float t, float AbsSpeedMpS, float AbsWheelSpeedMpS)
+        protected override void UpdateTractiveForce(float elapsedClockSeconds)
         {
         }