Merge pull request #916 from SteelFill/dpu_brakes

Distributed Power Air Brake Synchronization

Author: SteelFill

Source/Documentation/Manual/cabs.rst

@@ -684,14 +684,16 @@ Air Flow Meter
 
 .. index::
    single:  ORTS_AIR_FLOW_METER
+   single:  ORTS_TRAIN_AIR_FLOW_METER
 
 This cabview control is used on some locomotives, particularly in North America, to show the
 volumetric flow rate of air moving from the main res to the brake pipe during release/recharge.
 Such an indication can be used to determine when brake pipe charging is complete,
 measure the amount of brake pipe leakage, and so on.
 The control will only function on locomotives with air brakes.
 
-Here is an example implementation of ORTS_AIR_FLOW_METER as an analog dial::
+Here is an example implementation of ORTS_AIR_FLOW_METER as an analog dial (display types other
+than analog dials can be used)::
 
 
 		Dial (
@@ -706,8 +708,10 @@ Here is an example implementation of ORTS_AIR_FLOW_METER as an analog dial::
 			DirIncrease ( 0 )
 		)
 
-Applicable user-defined units are CUBIC_FT_MIN, LITERS_S, LITERS_MIN, and CUBIC_M_S. Cubic meters per
-second will be used if no units are specified.
+Alternately, a control type of ORTS_TRAIN_AIR_FLOW_METER can be used to display the total
+air flow rate of all locomotives, useful for distributed power where multiple locomotives can
+charge the brake pipe simultaneously. Applicable user-defined units are CUBIC_FT_MIN, LITERS_S,
+LITERS_MIN, and CUBIC_M_S. Cubic meters per second will be used if no units are specified.
 
 
 Animated 2D Wipers

Source/Documentation/Manual/physics.rst

@@ -2350,6 +2350,52 @@ The actual set value of traction or dynamic brake of *async* group is shown in
 lines *Throttle* and *Dynamic Brake*, respectively, in brackets, e.g.: 
 Throttle: 0% (50%).
 
+In addition to applying power and dynamic brake, remote units can also manage the
+train brake, independent brake, and emergency brake in sync with the lead locomotive.
+This can dramatically speed up brake application and release on long trains, which has
+allowed trains to increase in length substantially without major decreases in brake
+performance. Only one locomotive in each group, the 'lead' DP unit, will have brakes
+cut-in. Usually this is the same locomotive recieving throttle data from the lead
+locomotive. In Open Rails, these locomotives are designated automatically. To determine
+which units are the 'lead' in each group, check the ID row on the DPU Info window.
+
+As described earlier, operation in *sync* mode or *async* mode has no effect on air
+brake behavior. In reality, additional remote modes such as *set-out*, *bv out*,
+and *isolate* would disable air brakes on remote units, but these modes are not
+present for simplicity.
+
+.. index::
+   single: ORTSDPBrakeSynchronization
+
+By default, Open Rails will treat remote groups as manned helpers who typically
+would not assist in train brake operations, so only independent brakes will synchronize.
+To enable train brake synchronization, the token ``engine(ORTSDPBrakeSynchronization(``
+should be used. The valid settings for ``ORTSDPBrakeSynchronization`` are as follows:
+
+- ``"Apply"``: DP units will reduce the brake pipe pressure locally to match the
+  equalizing reservoir pressure of the controlling locomotive. (The controlling
+  locomotive must also have the ``"Apply"`` setting.)
+- ``"Release"``: DP units will increase the brake pipe pressure locally to match
+  the equalizing reservoir pressure of the controlling locomotive. (The controlling
+  locomotive must also have the ``"Release"`` setting.)
+- ``"Emergency"``: DP units will vent the brake pipe to 0 if an emergency application
+  is triggered by the controlling locomotive. (The controlling locomotive must also
+  have the ``"Emergency"`` setting.)
+- ``"Independent"``: DP units will match the brake cylinder pressure of the
+  controlling locomotive, and will automatically bail-off automatic brake
+  applications if needed. (The controlling locomotive must also have the
+  ``"Independent"`` setting.)
+                - NOTE: Although ``"Independent"`` is enabled by default,
+                  if ``ORTSDPBrakeSynchronization`` is present in the .eng
+                  file but ``"Independent"`` is not specified as an option,
+                  independent brakes will NOT be synchronized.
+
+All settings can be combined as needed, simply place a comma between each setting
+in the string: ``ORTSDPBrakeSynchronization("Apply, Release, Emergency, Independent")``
+will simulate the configuration of most modern locomotives. Unlike other distributed power
+features, brake synchronization can be applied to any locomotive type to simulate a wide
+variety of braking systems.
+
 Distributed power info and commands can also be displayed and operated through 
 cabview controls, as explained :ref:`here <cabs-distributed-power>`
 

Source/Orts.Formats.Msts/CabViewFile.cs

@@ -201,6 +201,7 @@ public enum CABViewControlTypes
         ORTS_QUICKRELEASE,
         ORTS_OVERCHARGE,
         ORTS_AIR_FLOW_METER,
+        ORTS_TRAIN_AIR_FLOW_METER,
         ORTS_BATTERY_SWITCH_COMMAND_SWITCH,
         ORTS_BATTERY_SWITCH_COMMAND_BUTTON_CLOSE,
         ORTS_BATTERY_SWITCH_COMMAND_BUTTON_OPEN,

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

@@ -76,6 +76,9 @@ namespace Orts.Simulation.Physics
     public class Train
     {
         public List<TrainCar> Cars = new List<TrainCar>();           // listed front to back
+        public List<TrainCar> DPLeadUnits = new List<TrainCar>();    // list of all DP lead locomotives
+        // list of connected locomotives, each element is a list of the connected locomotives themselves
+        public List<List<TrainCar>> LocoGroups = new List<List<TrainCar>>();
         public int Number;
         public string Name;
         public string TcsParametersFileName;
@@ -138,6 +141,7 @@ public TrainCar LastCar
         public float BrakeLine4 = -1;                    // extra line just in case, ep brake control line. -2: hold, -1: inactive, 0: release, 0 < value <=1: apply
         public RetainerSetting RetainerSetting = RetainerSetting.Exhaust;
         public int RetainerPercent = 100;
+        public float TotalBrakePipeFlowM3pS; // Total flow rate of air from all MR to BP
         public float TotalTrainBrakePipeVolumeM3; // Total volume of train brake pipe
         public float TotalTrainBrakeCylinderVolumeM3; // Total volume of train brake cylinders
         public float TotalTrainBrakeSystemVolumeM3; // Total volume of train brake system
@@ -509,6 +513,9 @@ public TrainCar LeadLocomotive
                         //if (lead.EngineBrakeController != null)
                         //    lead.EngineBrakeController.UpdateEngineBrakePressure(ref BrakeLine3PressurePSI, 1000);
                     }
+
+                // If lead locomotive changes, distributed power needs to be updated
+                SetDPUnitIDs(true);
             }
         }
 
@@ -691,6 +698,7 @@ public Train(Simulator simulator, BinaryReader inf)
             BrakeLine2PressurePSI = inf.ReadSingle();
             BrakeLine3PressurePSI = inf.ReadSingle();
             BrakeLine4 = inf.ReadSingle();
+            TotalBrakePipeFlowM3pS = inf.ReadSingle();
             aiBrakePercent = inf.ReadSingle();
             LeadLocomotiveIndex = inf.ReadInt32();
             RetainerSetting = (RetainerSetting)inf.ReadInt32();
@@ -1039,6 +1047,7 @@ public virtual void Save(BinaryWriter outf)
             outf.Write(BrakeLine2PressurePSI);
             outf.Write(BrakeLine3PressurePSI);
             outf.Write(BrakeLine4);
+            outf.Write(TotalBrakePipeFlowM3pS);
             outf.Write(aiBrakePercent);
             outf.Write(LeadLocomotiveIndex);
             outf.Write((int)RetainerSetting);
@@ -1314,6 +1323,7 @@ public TrainCar GetNextCab()
             LeadLocomotiveIndex = Math.Abs(nextCabIndex) - 1;
             Trace.Assert(LeadLocomotive != null, "Tried to switch to non-existent loco");
             TrainCar newLead = LeadLocomotive;  // Changing LeadLocomotiveIndex also changed LeadLocomotive
+            SetDPUnitIDs(true); // DP IDs must be reprocessed when lead locomotive changes
             ((MSTSLocomotive)newLead).UsingRearCab = nextCabIndex < 0;
 
             if (oldLead != null && newLead != null && oldLead != newLead)
@@ -1372,6 +1382,7 @@ public void LeadNextLocomotive()
             else if (coud > 1)
                 LeadLocomotiveIndex = firstLead;
             TrainCar newLead = LeadLocomotive;
+            SetDPUnitIDs(true); // DP IDs must be reprocessed when lead locomotive changes
             if (prevLead != null && newLead != null && prevLead != newLead)
                 newLead.CopyControllerSettings(prevLead);
         }
@@ -1527,19 +1538,79 @@ public void ReverseCars()
         /// </summary>
         public void SetDPUnitIDs(bool keepRemoteGroups = false)
         {
+            // List to keep track of new 'lead' DP units
+            // 'Lead' DP units follow the air brake commands of the master loco, 'trail' DP units do not
+            List<TrainCar> tempDPLeads = new List<TrainCar>();
+            TrainCar tempDPLead = null;
+            // Value judging how compatible this locomotive is to the lead locomotive for DP purposes
+            float dpRating = 0;
+
+            // List of each DP group's locomotives
+            List<List<TrainCar>> tempLocoGroups = new List<List<TrainCar>>();
+
+            var prevId = -1;
             var id = 0;
+
             foreach (var car in Cars)
             {
-                //Console.WriteLine("___{0} {1}", car.CarID, id);
-                if (car is MSTSLocomotive)
+                if (car is MSTSLocomotive loco)
                 {
-                    (car as MSTSLocomotive).DPUnitID = id;
+                    float thisDPRating = DetermineDPCompatibility(LeadLocomotive, car);
+
+                    loco.DPUnitID = id;
+
+                    if (id != prevId) // New locomotive group
+                    {
+                        // Add the most suitable unit from the previous group as a DP lead unit
+                        if (tempDPLead != null && !tempDPLeads.Contains(tempDPLead))
+                            tempDPLeads.Add(tempDPLead);
+
+                        dpRating = thisDPRating;
+                        tempDPLead = car;
+
+                        prevId = id;
+                    }
+                    else // Same locomotive group
+                        // Check to see if this locomotive is more compatible than previous ones
+                        if (thisDPRating > dpRating)
+                        {
+                            dpRating = thisDPRating;
+                            tempDPLead = car;
+                        }
+
                     if (car.RemoteControlGroup == 1 && !keepRemoteGroups)
                         car.RemoteControlGroup = 0;
                 }
                 else
                     id++;
             }
+
+            // Add final DP lead unit
+            if (tempDPLead != null && !tempDPLeads.Contains(tempDPLead))
+                tempDPLeads.Add(tempDPLead);
+
+            foreach (TrainCar locoCar in tempDPLeads)
+            {
+                // The train's lead unit should always be a DP lead unit, even if not at the front
+                // If a different locomotive in the lead loco's group has been declared DP lead, replace that loco with the lead loco
+                if (LeadLocomotive is MSTSLocomotive lead && locoCar is MSTSLocomotive loco)
+                    if (loco.DPUnitID == lead.DPUnitID && locoCar != LeadLocomotive)
+                    {
+                        tempDPLeads.Insert(tempDPLeads.IndexOf(locoCar), LeadLocomotive);
+                        tempDPLeads.Remove(locoCar);
+                        break; // foreach doesn't like it when the collection is modified during the loop, break to mitigate error
+                    }
+            }
+
+            DPLeadUnits = tempDPLeads;
+
+            foreach (TrainCar loco in DPLeadUnits)
+            {
+                // Find all locomotives connected to each DP unit
+                tempLocoGroups.Add(DetermineLocomotiveGroup(loco));
+            }
+
+            LocoGroups = tempLocoGroups;
         }
 
         /// <summary>
@@ -4231,6 +4302,127 @@ public TrainCar FindLeadLocomotive()
             return null;
         }
 
+        //================================================================================================//
+        /// <summary>
+        /// Find connected locomotives
+        /// <\summary>
+
+        // Finds all locomotives connected to the TrainCar reference provided as input,
+        // returning the connected locomotives* as a list of TrainCars.
+        // Returns null if there are no locomotives in the given group.
+        // *If the input is a steam locomotive, the output will instead be the steam locomotive and any tenders connected.
+        // Useful for determining locomotive brake propagation on groups of locomotives other than the lead group.
+
+        public List<TrainCar> DetermineLocomotiveGroup(TrainCar loco)
+        {
+            if (loco is MSTSLocomotive)
+            {
+                List<TrainCar> tempGroup = new List<TrainCar>();
+                int first;
+                int last;
+
+                first = last = Cars.IndexOf(loco);
+
+                // If locomotive is a steam locomotive, check for tenders only
+                if (first >= 0 && loco is MSTSSteamLocomotive)
+                {
+                    if (last < Cars.Count - 1 && !loco.Flipped && Cars[last + 1].WagonType == TrainCar.WagonTypes.Tender)
+                        last++;
+                    else if (first > 0 && loco.Flipped && Cars[first - 1].WagonType == TrainCar.WagonTypes.Tender)
+                        first--;
+                }
+                else // Other locomotive types
+                {
+                    for (int i = last; i < Cars.Count && (Cars[i] is MSTSLocomotive && !(Cars[i] is MSTSSteamLocomotive)); i++)
+                        last = i;
+                    for (int i = first; i >= 0 && (Cars[i] is MSTSLocomotive && !(Cars[i] is MSTSSteamLocomotive)); i--)
+                        first = i;
+                }
+
+                if (first < 0 || last < 0)
+                    return null;
+                else
+                {
+                    for (int i = first; i <= last; i++)
+                        tempGroup.Add(Cars[i]);
+                    return tempGroup;
+                }
+            }
+            else
+                return null;
+        }
+
+        //================================================================================================//
+        /// <summary>
+        /// Find connected DP lead locomotive
+        /// <\summary>
+
+        // Finds the DP lead locomotive to the TrainCar reference provided as input,
+        // returning the TrainCar reference to the DP lead unit.
+        // Returns null if there are no DP lead units controlling the given train car.
+
+        public TrainCar DetermineDPLeadLocomotive(TrainCar locoCar)
+        {
+            if (Cars.Contains(locoCar) && locoCar is MSTSLocomotive loco)
+                foreach (TrainCar dpLead in DPLeadUnits)
+                    if (dpLead is MSTSLocomotive dpLeadLoco && dpLeadLoco.DPUnitID == loco.DPUnitID)
+                        return dpLead;
+
+            return null;
+        }
+
+        //================================================================================================//
+        /// <summary>
+        /// Find compatibility of DP connection between two locomotives
+        /// <\summary>
+
+        // Returns a score judging the compatibility of a lead locomotive (first input as a TrainCar)
+        // and remote locomotive (second input as a TrainCar). The more capabilities the two locomotives
+        // share, the higher the number returned. There is an additional slight bias for remote
+        // locomotives having higher capabilities than the lead locomotive.
+        // Returns -1 if one of the input TrainCars isn't a locomotive
+
+        public float DetermineDPCompatibility(TrainCar leadCar, TrainCar remoteCar)
+        {
+            float score = 0;
+
+            if (leadCar is MSTSLocomotive lead && remoteCar is MSTSLocomotive remote)
+            {
+                if (remote.DPSyncTrainApplication)
+                {
+                    if (lead.DPSyncTrainApplication)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+                if (remote.DPSyncTrainRelease)
+                {
+                    if (lead.DPSyncTrainRelease)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+                if (remote.DPSyncEmergency)
+                {
+                    if (lead.DPSyncEmergency)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+                if (remote.DPSyncIndependent)
+                {
+                    if (lead.DPSyncIndependent)
+                        score++;
+                    else
+                        score += 0.1f;
+                }
+
+                return score;
+            }
+            else
+                return -1;
+        }
+
         //================================================================================================//
         /// <summary>
         /// Propagate brake pressure

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

@@ -1171,8 +1171,7 @@ public string GetDpuStatus(bool dataDpu, CABViewControlUnits loadUnits = CABView
             var brakeInfoValue = brakeValue(Simulator.Catalog.GetString("BP"), Simulator.Catalog.GetString("Flow"));
             status.AppendFormat("{0:F0}\t", brakeInfoValue);
             // Air flow meter
-            brakeInfoValue = brakeValue(Simulator.Catalog.GetString("Flow"), Simulator.Catalog.GetString("EOT"));
-            status.AppendFormat("{0:F0}\t", brakeInfoValue);
+            status.AppendFormat("{0:F0}\t", FormatStrings.FormatAirFlow(FilteredBrakePipeFlowM3pS, IsMetric));
 
             // Remote
             if (dataDpu)