Merge pull request #1120 from SteelFill/auto_friction

Automatically Calculate Friction Values if Missing

Author: SteelFill

Source/Documentation/Manual/features-rollingstock.rst

@@ -762,9 +762,9 @@ and the state of these parameters when the wagon or locomotive is full.
    single: FullBrakeRelayValveInshot
 
 To configure the stock correctly the following empty and full parameters need to be 
-included in the ORTSFreightAnims file. Empty values are included in the first block, 
-and full values are included in the second code block. A sample code block is shown 
-below::
+included in the ``ORTSFreightAnims`` block. Empty values are included in the first block, 
+and full values are included in the ``FreightAnimContinuous`` or ``FreightAnimStatic``
+sub-block. A sample code block is shown below::
 
     ORTSFreightAnims
     (
@@ -800,6 +800,12 @@ below::
      )
   )
 
+Any parameters not included will use the equivalent value specified outside
+the ORTSFreightAnims block. If the Davis A, B, and C values are not given
+they will be determined automatically using other properties of the rolling
+stock and either the 1926 Davis formula or 1992 CN formula, depending on the
+ORTSBearingType specified in the Wagon section.
+
 For some rolling stock, it may be more realistic to handle variations in load/empty
 brake force by changing the brake cylinder pressure developed, rather than changing
 the brake force directly. In such cases, the empty/load relay valve parameters work

Source/Documentation/Manual/physics.rst

@@ -39,50 +39,75 @@ the WAG / ENG file is discussed.
 Resistive Forces
 ----------------
 
-Open Rails physics calculates resistance based on real world physics:
-gravity, mass, rolling resistance and optionally curve resistance. This is
-calculated individually for each car in the train. The program calculates
-rolling resistance, or friction, based on the Friction parameters in the
-Wagon section of .wag/.eng file. Open Rails identifies whether the .wag
-file uses the *FCalc* utility or other friction data. If *FCalc* was used to
-determine the Friction variables within the .wag file, Open Rails compares
-that data to the Open Rails Davis equations to identify the closest match
-with the Open Rails Davis equation. If no-FCalc Friction parameters are
-used in the .wag file, Open Rails ignores those values, substituting its
-actual Davis equation values for the train car.
+Open Rails physics calculates resistance based on real world principles:
+gravity, mass, wind, rolling resistance, and curve resistance. This is
+calculated individually for each car in the train.
+
+The program supports a few methods for determining rolling resistance.
+The oldest method, intended only to support legacy content, uses the
+``Friction`` parameters in the Wagon section of .wag/.eng file.
+Open Rails identifies whether the .wag file used the *FCalc* utility or
+other friction data. If *FCalc* was used to determine the Friction variables
+within the .wag file, Open Rails attempts to determine the Davis coefficients
+originally used to derive the Friction parameters. If no FCalc Friction
+parameters are used in the .wag file, Open Rails ignores those values,
+substituting resistance calculated by the original 1923 Davis equation.
 
 .. index::
    single: ORTSDavis_A
    single: ORTSDavis_B
    single: ORTSDavis_C
+   single: ORTSBearingType
 
-A basic (simplified) Davis formula is used in the following form:
+For new content, it is preferred to not use the ``Friction`` parameters,
+and instead enter the Davis coefficients directly as this is more
+prototypical. In the Wagon section, the parameters ``ORTSDavis_A``,
+``ORTSDavis_B``, and ``ORTSDavis_C`` can be used to provide these values.
+When using this method, the wagon section should also specify the type of
+wheel bearings used with the ``ORTSBearingType`` parameter.
+These values are then used in a generic form of the Davis formula:
 
 F\ :sub:`res` = ORTSDavis_A + speedMpS * (ORTSDavis_B + ORTSDavis_C * speedMpS\ :sup:`2`\ )
 
-Where F\ :sub:`res` is the friction force of the car. The rolling resistance
-can be defined either by *FCalc* or ORTSDavis_A, _B and _C components. If
-one of the *ORTSDavis* components is zero, *FCalc* is used. Therefore, e.g.
-if the data doesn't contain the B part of the Davis formula, a very small
-number should be used instead of zero.
+Where F\ :sub:`res` is the friction force of the car when travelling at a
+speed of *speedMpS*. Note that in this formula, unlike the empirical Davis
+formula, the weight of the rolling stock and the number of axles are not
+considered by this equation; the ORTSDavis values must be set already
+accounting for the weight and number of axles. Accepted units of measure
+for ORTSDavis parameters and the list of bearing types can be found in the
+:ref:`required parameters table <required-params>`.
+
+In the case that ORTSDavis coefficients are not known or prove awkward to calculate,
+Open Rails can automatically calculate rolling resistance using other data
+in combination with the 1926 Davis equation (for grease and friction bearings)
+or the 1992 CN equation (for roller and low bearings). If given a supported
+``ORTSBearingType``, missing A and B coefficients will be found from the rail
+vehicle weight and number of axles. Likewise, if the C coefficient is missing it
+is automatically calculated from the ``ORTSWagonFrontalArea`` and
+``ORTSDavisDragConstant`` values (or defaults, if those are missing).
+While the auto-calculated results will be reasonable for standard rolling stock,
+manual entry of ORTSDavis coefficients is still preferred for more complicated
+rolling stock such as steam locomotives, multiple units, high speed trains,
+articulated units, and anything studied in experiments other than Davis.
 
 .. index::
    single: ORTSMergeSpeed
    single: ORTSStandstillFriction
 
-When a train is initially started, additional force is needed to overcome
-the initial higher bearing torque (forces) and track resistance.  Starting resistance is calculated 
-automatically by Open Rails based upon empirical prototypical data at low speeds. 
-By selecting different values for ``ORTSBearingType`` different values of starting 
-resistance will be applied. The Open Rails calculation for starting resistance takes 
-into account different conditions, such as weather (for example, snowing or clear), 
-wagon (axle) load, wheel bearing temperature and wheel diameter. Hence when using the OR calculation 
-the correct values should be inserted in ``ORTSNumberAxles`` parameter in the wagon section, and 
-``ORTSNumberDriveAxles`` in the engine section. The ``WheelRadius`` value should also be 
-inserted in both sections as appropriate.
-
-Alternatively the low-speed friction force can be manually specified by the user by setting 
-``ORTSStandstillFriction`` and ``ORTSMergeSpeed``.
+The various forms of Davis equation are only accurate above 5 mph or so. They
+prove inaccurate at low speeds as additional force is needed to overcome
+the initial higher bearing torque (forces) and track resistance. Starting resistance
+is calculated automatically by Open Rails based upon environmental conditions
+and the setting of ``ORTSBearingType``. Each bearing type has a different starting
+resistance profile based on empirical prototypical data, including consideration
+for the temperature of the bearing, wagon (axle) load, and wheel diameter. Hence
+when using the OR calculation  the correct values should be inserted in ``ORTSNumberAxles``
+parameter in the wagon section, and ``ORTSNumberDriveAxles`` in the engine section. The
+``WheelRadius`` value should also be inserted in both sections as appropriate.
+
+Alternatively the low-speed friction force can be manually specified by the user by
+setting the zero-speed force in ``ORTSStandstillFriction`` and the speed at which the
+regular Davis equation takes over with ``ORTSMergeSpeed``.
 
 .. index::
    single: ORTSTrackGauge
@@ -2161,6 +2186,8 @@ iii. `Testing Resources for Open Rails Steam Locomotives
 .. |-| unicode:: U+00AD .. soft hyphen
   :trim:
 
+.. _required-params:
+
 +-----------------------------------------------------------+-------------------+-------------------+-------------------+
 |Parameter                                                  |Description        |Recommended Units  |Typical Examples   |
 +===========================================================+===================+===================+===================+
@@ -2273,9 +2300,10 @@ iii. `Testing Resources for Open Rails Steam Locomotives
 |                                                           |friction           |lbf/mph^2          |(1.43lbf/mph^2)    |
 |                                                           |                   |Use FCalc          |                   |
 +-----------------------------------------------------------+-------------------+-------------------+-------------------+
-|ORTS |-| Bearing |-| Type ( x )                            |Bearing type,      || Roller,          |( Roller )         |
-|                                                           |defaults to        || Friction,        |                   |
-|                                                           |Friction           || Low              |                   |
+|ORTS |-| Bearing |-| Type ( x )                            |Bearing type used  || Grease,          |( Roller )         |
+|                                                           |to determine       || Friction,        |                   |
+|                                                           |rolling resistance || Roller           |                   |
+|                                                           |                   || Low              |                   |
 |                                                           |                   |                   |                   |
 +-----------------------------------------------------------+-------------------+-------------------+-------------------+
 |**Friction (Engine section)**                                                                                          |
@@ -4769,10 +4797,7 @@ impact due to the wind will be zero.
 
 **Wind Lateral Force Resistance**  - When the wind blows from the side of the
 train, the train will be pushed against the outside track rail, thus increasing
-the amount of resistance experienced by the train.
-
-To activate calculation of wind resistance, select the tickbox for "Wind dependent
-resistance" in the Simulation TAB of the options menu. As wind only becomes
+the amount of resistance experienced by the train. As wind only becomes
 significant at higher train speeds, the wind resistance calculation only commences
 once the train speed exceeds 5 mph.
 
@@ -4808,9 +4833,9 @@ parameters can be inputted via the WAG file or section.
 ``ORTSWagonFrontalArea`` -- The frontal cross sectional area of the wagon. The default units
 are in ft^2, so if entering metres, include the Units of Measure.
 
-``ORTSDavisDragConstant`` -- OR by default uses the standard Davis Drag constants. If alternate
-drag constants are used in calculating the still air resistance, then it might be worthwhile
-inputting these values.
+``ORTSDavisDragConstant`` -- OR assigns a default drag constant based on the type of
+rolling stock. For more specifity or for less typical types of rolling stock, the drag
+coefficient can be entered manually. Typical values are unitless in the range of 0.0002 - 0.0024.
 
 
 .. _physics-track-sanding:
@@ -4905,7 +4930,7 @@ However for those who like to customise, the following parameter can be inputted
    single: ORTSTrailLocomotiveResistanceFactor
 
 ``ORTSTrailLocomotiveResistanceFactor`` -- The constant value by which the leading locomotive resistance
-needs to be decreased for trailing operation.
+needs to be multiplied for trailing operation (eg: 0.5 halves resistance, default 0.2083).
 
 For steam locomotive tenders it may be necessary to enter this value depending upon the Drag constant used
 to calculate the tender resistance.

Source/Orts.Common/Conversions.cs

@@ -260,8 +260,23 @@ public static class NpM
     /// <summary>
     /// Resistance conversions from and to Newtons/metre/sec
     /// </summary>
-    public static class NpMpS
+    public static class NSpM
     {
+        /// <summary>Convert from pounds per mph to newtons per meter per second</summary>
+        public static float FromLbfpMpH(float lbfPerMpH) { return lbfPerMpH * 9.9503884f; }
+        /// <summary>Convert from newtons per meter per second to pounds per mph</summary>
+        public static float ToLbfpMpH(float nPerMpS) { return nPerMpS / 9.9503884f; }
+    }
+
+    /// <summary>
+    /// Resistance conversions from and to Newtons/metre^2/sec^2
+    /// </summary>
+    public static class NSSpMM
+    {
+        /// <summary>Convert from pounds per mph^2 to newtons per mps^2</summary>
+        public static float FromLbfpMpH2(float lbfPerMpH2) { return lbfPerMpH2 * 22.2583849f; }
+        /// <summary>Convert from newtons per mps^2 to pounds per mph^2</summary>
+        public static float ToLbfpMpH2(float nPerMpS2) { return nPerMpS2 / 22.2583849f; }
     }
 
     /// <summary>
@@ -576,8 +591,12 @@ public static class FormatStrings
         public static string f = Catalog.GetString("°F");
         public static string n = Catalog.GetString("N");
         public static string kN = Catalog.GetString("kN");
+        public static string nspm = Catalog.GetString("N/m/s");
+        public static string nsspmm = Catalog.GetString("N/(m/s)²");
         public static string lbf = Catalog.GetString("lbf");
         public static string klbf = Catalog.GetString("klbf");
+        public static string lbfpmph = Catalog.GetString("lbf/mph");
+        public static string lbfpmph2 = Catalog.GetString("lbf/mph²");
         public static string deg = Catalog.GetString("°");
 
         /// <summary>
@@ -789,6 +808,18 @@ public static string FormatLargeForce(float forceN, bool isMetric)
             return String.Format(CultureInfo.CurrentCulture, "{0:F1} {1}", force * 1e-3f, unit);
         }
 
+        public static string FormatLinearResistance(float resistanceNSpM, bool isMetric)
+        {
+            var resistance = isMetric ? resistanceNSpM : NSpM.ToLbfpMpH(resistanceNSpM);
+            return String.Format(CultureInfo.CurrentCulture, isMetric ? "{0:F1} {1}" : "{0:F2} {2}", resistance, nspm, lbfpmph);
+        }
+
+        public static string FormatQuadraticResistance(float resistanceNSSpMM, bool isMetric)
+        {
+            var resistance = isMetric ? resistanceNSSpMM : NSSpMM.ToLbfpMpH2(resistanceNSSpMM);
+            return String.Format(CultureInfo.CurrentCulture, isMetric ? "{0:F3} {1}" : "{0:F4} {2}", resistance, nsspmm, lbfpmph2);
+        }
+
         public static string FormatTemperature(float temperatureC, bool isMetric, bool isDelta)
         {
             var temperature = isMetric ? temperatureC : isDelta ? C.ToDeltaF(temperatureC) : C.ToF(temperatureC);

Source/Orts.Parsers.Msts/STFReader.cs

@@ -1076,7 +1076,7 @@ internal double ParseUnitSuffix(ref string constant, UNITS validUnits)
                     case "": return 1.0;
                     case "n/m/s": return 1;
                     case "ns/m": return 1;
-                    case "lbf/mph": return 10.0264321;  // 1 lbf = 4.4822162, 1 mph = 0.44704 mps => 4.4822162 / 0.44704 = 10.0264321
+                    case "lbf/mph": return 9.9503884;  // 1 lbf = 4.4482216, 1 mph = 0.44704 mps => 4.4482216 / 0.44704 = 9.9503884
                 }
             if ((validUnits & UNITS.PressureDefaultPSI) > 0)
                 switch (suffix)
@@ -1146,7 +1146,7 @@ internal double ParseUnitSuffix(ref string constant, UNITS validUnits)
                 {
                     case "": return 1.0;
                     case "Nm/s^2": return 1;
-                    case "lbf/mph^2": return 22.42849;  // 1 lbf = 4.4822162, 1 mph = 0.44704 mps +> 4.4822162 / (0.44704 * 0.44704) = 22.42849
+                    case "lbf/mph^2": return 22.2583849;  // 1 lbf = 4.4482216, 1 mph = 0.44704 mps +> 4.4482216 / (0.44704 * 0.44704) = 22.2583849
                 }
             if ((validUnits & UNITS.Temperature) > 0)
             {
@@ -3391,10 +3391,10 @@ static float ParseUnitSuffix(ref string constant, UNITS validUnits, StfToken tok
             if ((validUnits & UNITS.Resistance) > 0)
                 switch (suffix)
                 {
-                    case "": return 1.0f;
+                    case "": return 1.0;
                     case "n/m/s": return 1;
                     case "ns/m": return 1;
-                    case "lbf/mph": return 10.0264321f;  // 1 lbf = 4.4822162, 1 mph = 0.44704 mps => 4.4822162 / 0.44704 = 10.0264321
+                    case "lbf/mph": return 9.9503884;  // 1 lbf = 4.4482216, 1 mph = 0.44704 mps => 4.4482216 / 0.44704 = 9.9503884
                 }
             if ((validUnits & UNITS.PressureDefaultPSI) > 0)
                 switch (suffix)
@@ -3459,9 +3459,9 @@ static float ParseUnitSuffix(ref string constant, UNITS validUnits, StfToken tok
             if ((validUnits & UNITS.ResistanceDavisC) > 0)
                 switch (suffix)
                 {
-                    case "": return 1.0f;
+                    case "": return 1.0;
                     case "Nm/s^2": return 1;
-                    case "lbf/mph^2": return 22.42849f;  // 1 lbf = 4.4822162, 1 mph = 0.44704 mps +> 4.4822162 / (0.44704 * 0.44704) = 22.42849
+                    case "lbf/mph^2": return 22.2583849;  // 1 lbf = 4.4482216, 1 mph = 0.44704 mps +> 4.4482216 / (0.44704 * 0.44704) = 22.2583849
                 }
 
             STFException.TraceWarning(tokenForWarnings, "Found a suffix '" + suffix + "' which could not be parsed as a " + validUnits.ToString() + " unit");