Automatic merge of T1.6-186-g21d9ada29 and 13 pull requests

- Pull request #1082 at 6550dab: Allow variable water level in glass gauge
- Pull request #1057 at 85bde8e: Switchable brake system
- Pull request #1081 at a8127a1: Brake cuts power unification
- Pull request #1091 at 378be55: Automatic speed control
- Pull request #1122 at 73c47b4: Wagon Size and Centering Controls
- Pull request #1124 at e241a0d: Built-in PBL2 brake controller
- Pull request #1128 at b6c197f: Particle Emitter Overhaul
- Pull request #1158 at 2599bfe: Temporary fix for bug 2121985: F9 TCO out-of-range after resume
- Pull request #1169 at 906f204: Revise TrainCar.SetUpWheels to Better Handle Unusual Rolling Stock
- Pull request #1175 at d28315e: Make Data Logger interval configurable
- Pull request #1176 at 4cd961b: Remove Implicit Requirement for Engine Name to Come After "Engine ("
- Pull request #1178 at 015769e: Fix Diesel RPM Rate of Change
- Pull request #1183 at 41911f1: docs: Add code guidelines for translations

Author: openrails-bot

Source/Documentation/Manual/physics.rst

@@ -1595,6 +1595,54 @@ ii) Cylinder Cocks Exhaust - the exhaust out of the cylinder drainage cocks,
 The following CAB controls have been defined, ``STEAM_BOOSTER_AIR``, ``STEAM_BOOSTER_IDLE``,
  ``STEAM_BOOSTER_LATCH``, ``STEAM_BOOSTER_PRESSURE``.
 
+Boiler Water and Water Gauge
+............................
+
+The management of boiler water on a steam locomotive is important for maintaining steam productions as 
+well as ensuring that water levels do not drop far enough to expose the firebox crown and the fusible plugs.
+
+The Water Glass is the primary indication used by the fireman to manage boiler water levels, however as the 
+locomotive goes up and down grades, the water level will appear to significantly change. The amount of variation 
+will be determined by a number of factors, and principal amongst them are the following.
+
+``ORTSBoilerLength`` - length of the boiler (UoM distance)
+``ORTSWaterGaugeGlassHeight`` - length of the water gauge (UoM Distance)
+``ORTSBoilerDiameter`` - diameter of the boiler (UoM Distance)
+``ORTSBoilerCrownHeight`` - Height of boiler crown above centre line of the boiler (UoM Distance)
+``ORTSBoilerCrownCoverageHeight`` - Amount of water required to cover the crown (UoM Distance)
+
+To display the changing water level in the Cab, use ``BOILER_WATER_GRADE``.
+
+Steam Water Injectors
+.....................
+
+Water injectors are typically modelled by default, and sizes and injection rates will be calculated automatically by OR.
+
+If desired the user may customise some of the default values by using the following parameters:
+
+``InjectorTypes ( x, y )`` - will allow the user to set up a combination of exhaust or live steam injectors for the 
+locomotive. Use 0 = Live steam and 1 = Exhaust steam in either of the x or y positions.
+
+``ORTSInjectorSize ( x, y )`` - the size of each injector can be indicated in this parameter. The values will be in 
+mm, and typically should not be greater then 19mm.
+
+
+Locomotive Back Pressure
+........................
+
+OR calculates a default back pressure value for the exhaust steam emitted from the cylinder.
+
+The user may customise the default value where appropriate values are known, ie from test reports, etc.
+
+To customise the backpressure curve use:
+
+``ORTSCylinderBackPressureVsSteamOutput ( x, y )`` - where x = series of cylinder steam usage rates in lb/h, and y = back 
+pressure in psig.
+
+Note: The older parameter ``ortscylinderbackpressure`` is inaccurate and no longer supported in OR. An error message will 
+display if OR detects the use of this parameter.
+
+
 Locomotive Types
 ................
 

Source/Orts.Formats.Msts/CabViewFile.cs

@@ -140,10 +140,12 @@ public enum CABViewControlTypes
         WATER_INJECTOR1,
         WATER_INJECTOR2,
         SMALL_EJECTOR,
+        BACK_PR,
         STEAM_PR,
         STEAMCHEST_PR,
         TENDER_WATER,
         BOILER_WATER,
+        BOILER_WATER_GRADE,
         REVERSER_PLATE,
         STEAMHEAT_PRESSURE,
         FIREBOX,

Source/Orts.Simulation/Common/SteamTable.cs

@@ -2494,7 +2494,7 @@ public void UpdateCarSteamHeat(float elapsedClockSeconds)
                             car.CarHeatCompartmentPipeAreaM2 = CarCompartmentPipeAreaM2 + CarDoorPipeAreaM2;
 
                             // Pipe convection heat produced - steam is reduced to atmospheric pressure when it is injected into compartment
-                            float CompartmentSteamPipeTempC = C.FromF(mstsLocomotive.SteamHeatPressureToTemperaturePSItoF[0]);
+                            float CompartmentSteamPipeTempC = C.FromF(mstsLocomotive.SaturatedSteamHeatPressureToTemperaturePSItoF[0]);
                             car.CarCompartmentSteamPipeHeatConvW = (PipeHeatTransCoeffWpM2K * car.CarHeatCompartmentPipeAreaM2 * (CompartmentSteamPipeTempC - car.CarInsideTempC));
 
                             // Pipe radiation heat produced
@@ -2513,7 +2513,7 @@ public void UpdateCarSteamHeat(float elapsedClockSeconds)
                         float HeatTransCoeffConnectHoseBTUpFt2pHrpF = 0.04f * car.ConvectionFactor; // rubber connecting hoses - BTU / sq.ft. / hr / l in / °F. TO BE CHECKED
 
                         // Calculate Length of carriage and heat loss in main steam pipe
-                        float CarMainSteamPipeTempF = mstsLocomotive.SteamHeatPressureToTemperaturePSItoF[car.CarSteamHeatMainPipeSteamPressurePSI];
+                        float CarMainSteamPipeTempF = mstsLocomotive.SaturatedSteamHeatPressureToTemperaturePSItoF[car.CarSteamHeatMainPipeSteamPressurePSI];
                         car.CarHeatSteamMainPipeHeatLossBTU = Me.ToFt(car.CarLengthM) * (MathHelper.Pi * Me.ToFt(car.MainSteamHeatPipeOuterDiaM)) * HeatTransCoeffMainPipeBTUpFt2pHrpF * (CarMainSteamPipeTempF - C.ToF(car.CarOutsideTempC));
 
                         // calculate steam connecting hoses heat loss - assume 1.5" hose
@@ -2561,7 +2561,7 @@ public void UpdateCarSteamHeat(float elapsedClockSeconds)
                         }
 
                         // Calculate steam flow rates and steam used
-                        SteamFlowRateLbpHr = (ProgressiveHeatAlongTrainBTU / mstsLocomotive.SteamHeatPSItoBTUpLB[mstsLocomotive.CurrentSteamHeatPressurePSI]) + pS.TopH(car.CarHeatSteamTrapUsageLBpS) + pS.TopH(car.CarHeatConnectingSteamHoseLeakageLBpS);
+                        SteamFlowRateLbpHr = (ProgressiveHeatAlongTrainBTU / mstsLocomotive.SaturatedSteamHeatPSItoBTUpLB[mstsLocomotive.CurrentSteamHeatPressurePSI]) + pS.TopH(car.CarHeatSteamTrapUsageLBpS) + pS.TopH(car.CarHeatConnectingSteamHoseLeakageLBpS);
                         mstsLocomotive.CalculatedCarHeaterSteamUsageLBpS = pS.FrompH(SteamFlowRateLbpHr);
 
                         // Calculate Net steam heat loss or gain for each compartment in the car

Source/Orts.Simulation/Simulation/Physics/Train.cs

@@ -916,7 +916,7 @@ public override string GetDebugStatus()
                    Simulator.Catalog.GetString("Press"),
                    FormatStrings.FormatPressure(CurrentSteamHeatPressurePSI, PressureUnit.PSI, MainPressureUnit, true),
                    Simulator.Catalog.GetString("StTemp"),
-                   FormatStrings.FormatTemperature(C.FromF(SteamHeatPressureToTemperaturePSItoF[CurrentSteamHeatPressurePSI]), IsMetric, false),
+                   FormatStrings.FormatTemperature(C.FromF(SaturatedSteamHeatPressureToTemperaturePSItoF[CurrentSteamHeatPressurePSI]), IsMetric, false),
                    Simulator.Catalog.GetString("StUse"),
                    FormatStrings.FormatMass(pS.TopH(Kg.FromLb(CalculatedCarHeaterSteamUsageLBpS)), IsMetric),
                    FormatStrings.h,

Source/Orts.Simulation/Simulation/RollingStocks/MSTSDieselLocomotive.cs

@@ -416,7 +416,7 @@ public override string GetDebugStatus()
                    Simulator.Catalog.GetString("Press"),
                    FormatStrings.FormatPressure(CurrentSteamHeatPressurePSI, PressureUnit.PSI, MainPressureUnit, true),
                    Simulator.Catalog.GetString("StTemp"),
-                   FormatStrings.FormatTemperature(C.FromF(SteamHeatPressureToTemperaturePSItoF[CurrentSteamHeatPressurePSI]), IsMetric, false),
+                   FormatStrings.FormatTemperature(C.FromF(SaturatedSteamHeatPressureToTemperaturePSItoF[CurrentSteamHeatPressurePSI]), IsMetric, false),
                    Simulator.Catalog.GetString("StUse"),
                    FormatStrings.FormatMass(pS.TopH(Kg.FromLb(CalculatedCarHeaterSteamUsageLBpS)), IsMetric),
                    FormatStrings.h,

Source/Orts.Simulation/Simulation/RollingStocks/MSTSElectricLocomotive.cs

@@ -225,9 +225,9 @@ public float CurrentLocomotiveSteamHeatBoilerWaterCapacityL
 
         // Carriage Steam Heating Parameters
         public float MaxSteamHeatPressurePSI;    // Maximum Steam heating pressure
-        public Interpolator SteamHeatPressureToTemperaturePSItoF;
+        public Interpolator SaturatedSteamHeatPressureToTemperaturePSItoF;
         public Interpolator SteamDensityPSItoLBpFT3;   // saturated steam density given pressure
-        public Interpolator SteamHeatPSItoBTUpLB;      // total heat in saturated steam given pressure
+        public Interpolator SaturatedSteamHeatPSItoBTUpLB;      // total heat in saturated steam given pressure
         public bool IsSteamHeatingBoilerFitted = false;   // Flag to indicate when steam heat boiler van is fitted
         public float CalculatedCarHeaterSteamUsageLBpS;
 
@@ -1625,9 +1625,9 @@ public override void Initialize()
                 IsSteamHeatFitted = true;
             }
 
-            SteamHeatPressureToTemperaturePSItoF = SteamTable.SteamHeatPressureToTemperatureInterpolatorPSItoF();
+            SaturatedSteamHeatPressureToTemperaturePSItoF = SteamTable.SaturatedSteamHeatPressureToTemperatureInterpolatorPSItoF();
             SteamDensityPSItoLBpFT3 = SteamTable.SteamDensityInterpolatorPSItoLBpFT3();
-            SteamHeatPSItoBTUpLB = SteamTable.SteamHeatInterpolatorPSItoBTUpLB();
+            SaturatedSteamHeatPSItoBTUpLB = SteamTable.SaturatedSteamHeatInterpolatorPSItoBTUpLB();
 
             // Check to see if water scoop elements have been configured
             if (WaterScoopFillElevationM == 0)