Automatic merge of T1.5.1-687-gd279e384a and 18 pull requests

- Pull request #570 at c59c788: Experimental glTF 2.0 support with PBR lighting
- Pull request #839 at d00beb9: First phase of https://blueprints.launchpad.net/or/+spec/additional-cruise-control-parameters
- Pull request #865 at 67014b7: Dispatcher window improvements
- Pull request #874 at f8dbeab: Dynamic brake controller refactoring
- Pull request #875 at 43bf33e: Bug fix for https://bugs.launchpad.net/or/+bug/2036346 Player train switching doesn't work with 3D cabs
- Pull request #876 at f92de76: docs: add source for documents previously on website to source Documentation folder
- Pull request #878 at f9aa2ad: Implement Polach Adhesion
- Pull request #882 at d8a1c4d: Blueprint/train car operations UI window
- Pull request #883 at edcc2dd: SwitchPanel disconnect/connect handling
- Pull request #885 at c81447b: feat: Add notifications to Menu
- Pull request #886 at 8da48b3: Scene viewer extension to TrackViewer
- Pull request #887 at 4665bda: docs: Document projects, assemblies, namespaces
- Pull request #888 at d7daf62: docs: Document player application model
- Pull request #889 at 43341cf: No speed update
- Pull request #892 at 1f5ba4c: Signal Function OPP_SIG_ID_TRAINPATH
- Pull request #893 at bf8876b: Signal errors
- Pull request #894 at 794fddf: Correct Decrease Colour
- Pull request #896 at 5866028: First implementation of https://blueprints.launchpad.net/or/+spec/specific-sounds-for-ai-trains

Author: openrails-bot

Source/Orts.Simulation/Simulation/RollingStocks/SubSystems/PowerTransmissions/Axle.cs

@@ -426,6 +426,11 @@ public float InertiaKgm2
         /// </summary>
         float forceToAccelerationFactor;
 
+        /// <summary>
+        /// switch between Polach and Pacha adhesion calculation
+        /// </summary>
+        bool UsePoalchAdhesion = false;
+
         /// <summary>
         /// Pre-calculation of slip characteristics at 0 slip speed
         /// </summary>
@@ -587,12 +592,12 @@ public void ComputeWheelSlipThresholdMpS()
             // i.e. the point where slope changes from positive (adhesion region)
             // to negative (slip region)
             double dx = 0.001;
-            double fa = SlipCharacteristics(a + dx) - SlipCharacteristics(a);
-            double fb = SlipCharacteristics(b + dx) - SlipCharacteristics(b);
+            double fa = SlipCharacteristicsPolach(a + dx) - SlipCharacteristicsPolach(a);
+            double fb = SlipCharacteristicsPolach(b + dx) - SlipCharacteristicsPolach(b);
 
             double SlipSpeedMpS = AxleSpeedMpS - TrainSpeedMpS;
 
-            MaximumPolachWheelAdhesion = (float)SlipCharacteristics(WheelSlipThresholdMpS);
+            MaximumPolachWheelAdhesion = (float)SlipCharacteristicsPolach(WheelSlipThresholdMpS);
 
             if (SlipSpeedMpS == 0)
             {
@@ -610,7 +615,7 @@ public void ComputeWheelSlipThresholdMpS()
             while (Math.Abs(b - a) > MpS.FromKpH(0.1f))
             {
                 double c = (a + b) / 2;
-                double fc = SlipCharacteristics(c + dx) - SlipCharacteristics(c);
+                double fc = SlipCharacteristicsPolach(c + dx) - SlipCharacteristicsPolach(c);
                 if (fa * fc > 0)
                 {
                     a = c;
@@ -813,7 +818,17 @@ public void Save(BinaryWriter outf)
         public (double, double, double, double) GetAxleMotionVariation(double axleSpeedMpS, double elapsedClockSeconds)
         {
             double slipSpeedMpS = axleSpeedMpS - TrainSpeedMpS;
-            double axleOutForceN = Math.Sign(slipSpeedMpS) * AxleWeightN * SlipCharacteristics(slipSpeedMpS);
+            double axleOutForceN = 0;
+
+            if (UsePoalchAdhesion)
+            {
+                axleOutForceN = Math.Sign(slipSpeedMpS) * AxleWeightN * SlipCharacteristicsPolach(slipSpeedMpS);
+            }
+            else
+            {
+                axleOutForceN = AxleWeightN * SlipCharacteristicsPacha((float)axleSpeedMpS - TrainSpeedMpS, TrainSpeedMpS, AdhesionK, AdhesionLimit);
+            }
+            
             double axleInForceN = 0;
             if (DriveType == AxleDriveType.ForceDriven)
                 axleInForceN = DriveForceN * transmissionEfficiency;
@@ -851,31 +866,9 @@ void Integrate(float elapsedClockSeconds)
             if (elapsedClockSeconds <= 0) return;
             double prevSpeedMpS = AxleSpeedMpS;
 
-            float upperSubStepStartingLimit = 100;
-            float tempupperSubStepLimit = upperSubStepStartingLimit;
+            float upperSubStepLimit = 100;
             float lowerSubStepLimit = 1;
 
-            float screenFrameUpperLimit = 60;
-            float screenFrameLowerLimit = 40;
-
-            var ScreenFrameRate = Simulator.SmoothedFrameRate;
-
-            // Reduces the number of substeps if screen FPS drops below a nominal rate of 60 fps
-            if ( (int)ScreenFrameRate >= screenFrameUpperLimit) // Screen FPS > 60, hold substeps @ maximum value
-            {
-                tempupperSubStepLimit = upperSubStepStartingLimit;
-            }
-            else if ((int)ScreenFrameRate < screenFrameLowerLimit) // Screen FPS < 40, hold substeps @ minimum value
-            {
-                tempupperSubStepLimit = upperSubStepStartingLimit * (screenFrameLowerLimit / screenFrameUpperLimit);
-            }
-            else
-            {
-                tempupperSubStepLimit = (int) ((ScreenFrameRate / 60) * upperSubStepStartingLimit);
-            }
-
-            var upperSubStepLimit = tempupperSubStepLimit;
-
             // use straight line graph approximation to increase substeps as slipspeed increases towards the threshold speed point
             // Points are 1 = (0, upperLimit) and 2 = (threshold, lowerLimit)           
             var AdhesGrad = ((upperSubStepLimit - lowerSubStepLimit) / (WheelSlipThresholdMpS - 0));
@@ -961,17 +954,44 @@ void Integrate(float elapsedClockSeconds)
         /// <param name="timeSpan"></param>
         public virtual void Update(float timeSpan)
         {
-            forceToAccelerationFactor = WheelRadiusM * WheelRadiusM / totalInertiaKgm2;
+            // Test to determine whether to use Polach or Pacha adhesion
+            var ScreenFrameRate = Simulator.SmoothedFrameRate;
+            
+            // Switches between Polach (high performance) adhesion model and Pacha (low performance) adhesion model
+            if(ScreenFrameRate > 59)
+            {
+                UsePoalchAdhesion = true;
+            }
+            else if(ScreenFrameRate < 55) 
+            {
+                UsePoalchAdhesion = false;
+                if (TrainSpeedMpS > 0 )
+                {
+                    Trace.TraceInformation("Advanced adhesion model switched to low performance option due to low frame rate {0} at ElapsedClockSeconds of {1}", ScreenFrameRate, timeSpan);
+                }
 
-            Polach.Update();
-            axleStaticForceN = AxleWeightN * SlipCharacteristics(0);
-            ComputeWheelSlipThresholdMpS();
+                // Set values for Pacha adhesion
+                WheelSlipThresholdMpS = MpS.FromKpH(AdhesionK / AdhesionLimit);
+                WheelAdhesion = 0.99f;
+                MaximumPolachWheelAdhesion = 0.99f;
 
-            if (count < 6 && count++ == 5)
+            }
+            
+            forceToAccelerationFactor = WheelRadiusM * WheelRadiusM / totalInertiaKgm2;        
+
+            if (UsePoalchAdhesion)
             {
-                TrainSpeedMpS = 10 / 3.6f;
+
                 Polach.Update();
-                axleStaticForceN = AxleWeightN * SlipCharacteristics(0);
+                axleStaticForceN = AxleWeightN * SlipCharacteristicsPolach(0);
+                ComputeWheelSlipThresholdMpS();
+
+                if (count < 6 && count++ == 5)
+                {
+                    TrainSpeedMpS = 10 / 3.6f;
+                    Polach.Update();
+                    axleStaticForceN = AxleWeightN * SlipCharacteristicsPolach(0);
+                }
             }
 
 #if DEBUG_ADHESION
@@ -1170,6 +1190,7 @@ public double SlipCharacteristics(double slipSpeedMpS)
         }
 
         /// <summary>
+        /// ***** Polach Adhesion *****
         /// Uses the Polach creep force curves calculation described in the following document
         ///	"Creep forces in simulations of traction vehicles running on adhesion limit" by O. Polach 2005 Wear - http://www.sze.hu/~szenasy/VILLVONT/polachslipvizsg.pdf
         /// 
@@ -1183,12 +1204,55 @@ public double SlipCharacteristics(double slipSpeedMpS)
         /// <param name="slipSpeedMpS">Difference between train speed and wheel speed</param>
         /// <param name="speedMpS">Current speed</param>
         /// <returns>Relative force transmitted to the rail</returns>
-        public double SlipCharacteristics(double slipSpeedMpS)
+        public double SlipCharacteristicsPolach(double slipSpeedMpS)
         {
             slipSpeedMpS = Math.Abs(slipSpeedMpS);
             double fx = Polach.SlipCharacteristics(slipSpeedMpS);
             WheelAdhesion = (float)fx;
             return fx;
         }
+
+
+        /// <summary>
+        /// ***** Pacha Adhesion *****
+        /// Slip characteristics computation
+        /// - Uses adhesion limit calculated by Curtius-Kniffler formula:
+        ///                 7.5
+        ///     umax = ---------------------  + 0.161
+        ///             speed * 3.6 + 44.0
+        /// - Computes slip speed
+        /// - Computes relative adhesion force as a result of slip characteristics:
+        ///             2*K*umax^2*dV
+        ///     u = ---------------------
+        ///           umax^2*dv^2 + K^2
+        /// 
+        /// For high slip speeds the formula is replaced with an exponentially 
+        /// decaying function (with smooth coupling) which reaches 40% of
+        /// maximum adhesion at infinity. The transition point between equations
+        /// is at dV = sqrt(3)*K/umax (inflection point)
+        /// 
+        /// </summary>
+        /// <param name="slipSpeedMpS">Difference between train speed and wheel speed</param>
+        /// <param name="speedMpS">Current speed</param>
+        /// <param name="K">Slip speed correction</param>
+        /// <param name="umax">Relative weather conditions, usually from 0.2 to 1.0</param>
+        /// <returns>Relative force transmitted to the rail</returns>
+        public float SlipCharacteristicsPacha(float slipSpeedMpS, float speedMpS, float K, float umax)
+        {
+            var slipSpeedKpH = MpS.ToKpH(slipSpeedMpS);
+            float x = slipSpeedKpH * umax / K; // Slip percentage
+            float absx = Math.Abs(x);
+            float sqrt3 = (float)Math.Sqrt(3);
+            if (absx > sqrt3)
+            {
+                // At infinity, adhesion is 40% of maximum (Polach, 2005)
+                // The value must be lower than 85% for the formula to work
+                float inftyFactor = 0.4f;
+                return Math.Sign(slipSpeedKpH) * umax * ((sqrt3 / 2 - inftyFactor) * (float)Math.Exp((sqrt3 - absx) / (2 * sqrt3 - 4 * inftyFactor)) + inftyFactor);
+            }
+            return 2.0f * umax * x / (1 + x * x);
+        }
+
+
     }
 }