New Triple Valve Features Vol. 2

[SteelFill]

I'm back! This is another round of triple valve improvements requested by the community. Can be considered a continuation of #851
Associated Trello Card
Discuss on ElvasTower

• Fixed an issue that could cause quick release to get stuck if retainers were used, preventing future brake applications (reported on TrainSimCommunity Discord)
• Fixed an easy to miss issue that would result in dynamic brake blending failing to activate on copied locomotives
• Fixed this issue that was giving a division by 0 error if the max brake cylinder pressure was set to 0
• Fixed TrainPipeLeakRate token. Previously the leak would only occur on the lead locomotive, now the leak will be applied to the whole train (I want to do better leak simulation eventually, but not yet).
• Added psi/min and bar/min as valid pressure units in the .eng/.wag file reader. This should help users define very slow rates of pressure change (eg: leakage, overcharge elimination).
• Changed ORTSEmergencyResQuickRelease to accept "2" as an input. If the value 2 is given, the emergency res will behave like an accelerated release res; it will not be used to enhance brake cylinder pressure in emergency applications but it will be used to provide accelerated release action.
• Rewrote quick service implementation to be more accurate to reality, uses the same user inputs as previously added.
• Changed the way the "threshold" (ie: target BC pressure) is calculated to accommodate new features, also refactored some application/release code to take advantage of threshold
• Added empty and loaded RelayValveRatio and Inshot for freight animations. If the freight is more than 25% loaded, the loaded setting will be used, otherwise the empty setting. Syntax is EmptyBrakeRelayValveRatio, EmptyBrakeRelayValveInshot, FullBrakeRelayValveRatio, and FullBrakeRelayValveInshot (this syntax will only work in the ORTSFreightAnims block).
• Two stage brake pressures: In some systems [not all, this is disabled by default], two distinct brake cylinder pressure limits may be used depending on speed. ORTSTwoStageLowPressure ( x bar ) sets the pressure limit at low speeds (at high speeds, the pressure is limited in the usual ways). Or if appropriate, ORTSTwoStageRelayValveRatio ( x ) can be used to set a different relay valve ratio at low speed, with the high speed relay valve ratio set as usual. ORTSTwoStageIncreasingSpeed ( x kmh ) is the speed at which the lower pressure limit is removed when accelerating, while ORTSTwoStageDecreasingSpeed ( x kmh ) sets the speed where the lower pressure limit is activated when decelerating. This is disabled during emergency (unsure if this is accurate).
• High speed reducing valve: A peculiar feature present only on some old American designs. It acts as a safety valve venting excess brake cylinder pressure during service applications, but during emergency applications intentionally allows brake cylinder pressure to exceed this limit. The brake pressure will then gradually return to normal. The activation pressure can be set with ORTSHighSpeedReducingPressure ( 60 psi ) [60 is typical, but this is disabled by default]. I've tried to automatically determine exactly how quickly the valve will vent excess pressure, but it may need tuning.
• Uniform release: Similar to uniform charging in the previous PR, this is a feature that activates when the brake pipe is modestly higher than the aux res pressure [3 psi is the standard, and the default value]. The user sets this offset with ORTSUniformReleaseThreshold ( 3 psi ). Unlike uniform charging which reduced aux res charging speed, uniform release reduces brake cylinder release rate, which is done to prevent the brakes coming off entirely on the front of the train while they are still fully applied at the rear. The reduction in release rate is set with ORTSUniformReleaseRatio ( x ), where the release rate is divided by x [ORTSUniformReleaseRatio ( 2 ) would halve release rate, default is 0 which disables this feature.]
• Separate brake application rates for service and emergency: To implement distinct application rates, I added a new way to limit the application rate during service applications specifically using ORTSMaxServiceApplicationRate ( x psi/s ). During emergency applications, the brake application rate will be the limit set by MaxApplicationRate ( y psi/s ). If no service application rate is set, it is assumed to be the same as the maximum application rate.
• Quick action: Another feature from older American triple valves. This one allows for higher brake cylinder pressures during emergency not by having an emergency reservior but by throwing air from the brake pipe into the brake cylinder. ORTSEmergencyQuickAction ( 1 ) will enable the feature, though it is disabled by default. Rate of brake cylinder filling is determined by MaxApplicationRate, which must be set to a fairly large number for this to work as intended. Remember ORTSMaxServiceApplicationRate can be used to keep the application rate under control for service applications.
• Did some testing with EP brakes this time to ensure EP brakes respect the service application rate, service brake cylinder pressure, and two stage braking. Unfortunately the current EP setup doesn't differentiate between full service and emergency so emergency pressures can only be achieved by the automatic air brake. This may justify some extra attention.
• Supply reservoirs: Option for an additional air volume which, if equipped, will be used to supply air for the brake cylinders (via the relay valve) instead of the aux res. Additionally, if applied to a locomotive/cab car, the supply res will be used to charge the brake pipe (and the supply res itself will draw from the main res). This is common on passenger stock and allows for a much smaller aux res to be used regardless of the size of brake cylinders. Supply_Reservoir must be added to BrakeEquipmentType to use a supply res. ORTSSupplyResCapacity sets the volume of the supply reservoir, and ORTSSupplyResChargingRate sets the rate at which the supply res pressure increases when draining air from the brake pipe. If on a twin pipe system, the supply res will charge from the MR pipe instead, unless ORTSMainResPipeAuxResCharging ( 0 ) is set.
• In-shot: Something I noticed on many relay valves (at least in the US) with a ratio < 1 is that a small amount of demanded BC pressure is added at a 1:1 ratio to the output of the relay valve. This gives a boost in output pressure when input pressure is low, ensuring that the brake cylinders extend fully even with light applications. (Eg: A relay valve with 0.6 ratio and 5 psi of in-shot will produce 8 psi output with 5 psi input, instead of just 3 psi.) ORTSBrakeRelayValveInshot ( x psi ) sets the in-shot pressure for automatic brake applications, and ORTSEngineBrakeRelayValveInshot ( x psi ) does the same for the engine brake. I also found that some types of in-shot override the demanded pressure (until the demanded pressure is greater than inshot) rather than add to the demanded pressure. If that is desired, simply enter a negative number as the inshot pressure.
• A bunch of new brake cylinder tokens that will allow for better simulation of the brake cylinder, ORTSBrakeCylinderDiameter ( x in ) allows for defining the brake cylinder diameter. ORTSBrakeCylinderPistonTravel ( x in ) gives the length of extension between the released and applied states of the brake cylinder, which is 8 inches by default. These two are used to determine the volume of the brake cylinder, and establish how the brake cylinder volume changes depending on the amount of pressure. ORTSBrakeCylinderPipingVolume ( x in^3 ) allows for adding an additional fixed volume to the brake cylinder, simulating the volume of piping between the triple valve and brake cylinder. Some brake systems intentionally increase this volume to produce the expected brake cylinder pressures. By default, this volume is automatically calculated to produce the expected brake cylinder pressures. ORTSNumberBrakeCylinders ( x ) is used to set the number of brake cylinders on the car, which will multiply the calculated volumes. On a related note, ORTSAuxiliaryResCapacity ( x in^3 ) can now be used to define the aux res volume directly, rather than indirectly with ratios.
• If ORTSBrakeCylinderDiameter is defined, then a more advanced brake cylinder simulation is activated that calculates and considers the effects of the brake cylinder(s) changing in volume. This WILL lead to different results than the simplified simulation, and forces the user to abandon some incorrect assumptions that have gone around the train simulation circle. Still, the setup will attempt to do its best given user inputs, and will produce warnings if the brake system parameters don't make sense.
• Animated brake rigging: Thanks to the introduction of the new brake cylinder tokens, I figured it would make sense to use the simulated brake cylinder to drive animations for the brake cylinder and brake rigging. There are 3 new animation types: ORTSBRAKECYLINDER, ORTSHANDBRAKE, and ORTSBRAKERIGGING (specifically, any animation matrix that begins with one of these names will be used for the brake animation). For creators: there is some nuance to setting this up correctly. I'm not sure if it's intuitive, but I don't have room here to explain (have you seen how huge this wall of text has gotten?), so check the post on ET for an explanation.
• New token ORTSBrakeForceReferencePressure ( x psi ) to solve some frustration other users and I had. When this token is provided, the forces entered in MaxBrakeForce or ORTSMaxBrakeShoeForce will be assumed to be the force at the given pressure, rather than at BrakeCylinderPressureForMaxBrakeBrakeForce. This should help data entry for cases where the brake force has been calculated at an intermediate pressure, rather than at the absolute maximum pressure.
• Unlimited brake cylinder pressure: If a 0, negative, or simply no value is defined for BrakeCylinderPressureForMaxBrakeBrakeForce, OR will completely remove the limit on brake cylinder pressure. The pressure will be limited by the parameters of the brake system, rather than this value. This will be accurate for some systems where there is no safety valve or pressure limiting valve, but is certainly not accurate for all situations.