Merge pull request #41 from AhmedAredah/main

feat: speed-dependent braking model, blended braking fix, and GUI improvements

Author: AhmedAredah

CMakeLists.txt

@@ -151,7 +151,7 @@ if(BUILD_GUI)
     elseif(APPLE)
         set(KDREPORTS_DIR "/usr/local/KDAB/KDReports-2.3.95/lib/cmake/KDReports-qt6" CACHE PATH "Path to KDReports CMake directory")
     elseif(UNIX)
-        set(KDREPORTS_DIR "/usr/local/KDAB/KDReports-2.3.95/lib/cmake/KDReports-qt6" CACHE PATH "Path to KDReports CMake directory")
+        set(KDREPORTS_DIR "/usr/local/${CMAKE_BUILD_TYPE}/lib/cmake/KDReports-qt6" CACHE PATH "Path to KDReports CMake directory")
     endif()
 
     # Use the KDReports CMake package
@@ -170,7 +170,7 @@ if(BUILD_SERVER)
     elseif(UNIX)
         # Linux-specific paths
         set(CONTAINER_SEARCH_PATHS "/usr/local/lib/cmake/Container" CACHE PATH "Default path to container's library on Linux")
-        set(RABBITMQ_CMAKE_DIR "/usr/local/lib/cmake/rabbitmq-c" CACHE PATH "Default path to RabbitMQ-C library on Linux")
+        set(RABBITMQ_CMAKE_DIR "/usr/local/${CMAKE_BUILD_TYPE}/lib/cmake/rabbitmq-c" CACHE PATH "Default path to RabbitMQ-C library on Linux")
     else()
         message(FATAL_ERROR "Unsupported platform. Please set paths for CONTAINER_CMAKE_DIR and RABBITMQ_CMAKE_DIR manually.")
     endif()

src/NeTrainSim/traindefinition/car.cpp

@@ -76,6 +76,12 @@ Car::Car(double carLength_m, double carDragCoef,
 
     } // end else if
 
+    if (this->carType == TrainTypes::CarType::cargo) {
+        this->brakedWeightRatio = EC::DefaultCarBrakedWeightRatio_Cargo;
+    } else {
+        this->brakedWeightRatio = EC::DefaultCarBrakedWeightRatio_Tender;
+    }
+
     this->hostLink = std::shared_ptr<NetLink>(); // assign empty placeholder
     this->trackCurvature = 0; // zero initialized
     this->trackGrade = 0;   // zero initialized

src/NeTrainSim/traindefinition/energyconsumption.cpp

@@ -159,4 +159,16 @@ namespace EC {
         return fuelConversionFactor_carTypes[carType];
     }
 
+    double getBrakeShoeFriction(double speed_mps,
+                                TrainTypes::BrakeShoeType shoeType) {
+        double v_kmh = speed_mps * 3.6;
+        switch (shoeType) {
+        case TrainTypes::BrakeShoeType::composition:
+            return 0.36 * (v_kmh + 150.0) / (2.0 * v_kmh + 150.0);
+        case TrainTypes::BrakeShoeType::castIron:
+        default:
+            return 0.6 * (v_kmh + 100.0) / (5.0 * v_kmh + 100.0);
+        }
+    }
+
 }

src/NeTrainSim/traindefinition/energyconsumption.h

@@ -301,6 +301,34 @@ namespace EC {
      * @returns The fuel conversion factor.
      */
     double getFuelConversionFactor(TrainTypes::CarType carType);
+
+    /** (Immutable) gravitational acceleration (m/s^2) */
+    static constexpr double g = 9.8066;
+    /** (Immutable) default braked weight ratio for locomotives */
+    static constexpr double DefaultLocomotiveBrakedWeightRatio = 0.9;
+    /** (Immutable) default braked weight ratio for cargo cars */
+    static constexpr double DefaultCarBrakedWeightRatio_Cargo = 0.6;
+    /** (Immutable) default braked weight ratio for tender cars */
+    static constexpr double DefaultCarBrakedWeightRatio_Tender = 0.7;
+
+    /** (Immutable) the speed below which dynamic braking fades to zero (km/h) */
+    static constexpr double DynamicBrakingFadeSpeed_kmh = 15.0;
+
+    /**
+     * Gets the brake shoe friction coefficient using the Karwatzki model.
+     *
+     * @details For cast-iron shoes (UIC standard):
+     *   mu(v) = 0.6 * (v_kmh + 100) / (5 * v_kmh + 100)
+     * For composition shoes:
+     *   mu(v) = 0.36 * (v_kmh + 150) / (2 * v_kmh + 150)
+     *
+     * @param speed_mps  Train speed in m/s.
+     * @param shoeType   Type of brake shoe (default: castIron).
+     * @returns The brake shoe friction coefficient (dimensionless).
+     */
+    double getBrakeShoeFriction(double speed_mps,
+                                TrainTypes::BrakeShoeType shoeType =
+                                    TrainTypes::BrakeShoeType::castIron);
 }
 
 

src/NeTrainSim/traindefinition/locomotive.cpp

@@ -216,7 +216,9 @@ Locomotive::Locomotive(double locomotiveMaxPower_kw,
         this->hybridMethod = TrainTypes::LocomotivePowerMethod::notApplicable;
     }
 
-};	
+    this->brakedWeightRatio = EC::DefaultLocomotiveBrakedWeightRatio;
+
+};
 
 
 double Locomotive::getHyperbolicThrottleCoef(double & trainSpeed)
@@ -541,20 +543,24 @@ double Locomotive::getEnergyConsumption(double& LocomotiveVirtualTractivePower,
 		return EC;
 	}
     else {
-        // get regenerative eff
+        // Blended braking: only the dynamic portion (motor as generator) is recoverable.
+        // Friction braking energy is dissipated as heat.
+        double recoverablePower =
+            -this->getRecoverableBrakingPower(tractivePower, trainSpeed);
+
         double regenerativeEff =
             this->getRegenerativeEffeciency(tractivePower,
                                             trainAcceleration, trainSpeed);
 
-        return ((tractivePower * regenerativeEff + this->auxiliaryPower) *
+        return ((recoverablePower * regenerativeEff + this->auxiliaryPower) *
                 EC::getDriveLineEff(trainSpeed,
                                     this->currentLocNotch,
                                     std::abs(powerPortion),
                                     this->powerType,
                                     this->hybridMethod) *
                 unitConversionFactor);
 
-	}
+    }
 }
 
 double Locomotive::getUsedPowerPortion(double trainSpeed,
@@ -568,6 +574,25 @@ double Locomotive::getUsedPowerPortion(double trainSpeed,
     return std::min((LocomotiveVirtualTractivePower) / maxPower, 1.0);
 }
 
+double Locomotive::getRecoverableBrakingPower(double totalBrakingPower,
+                                              double trainSpeed)
+{
+    if (!TrainTypes::locomotiveRechargableTechnologies.exist(this->powerType)) {
+        return 0.0;
+    }
+
+    // Motor's max dynamic braking power is approximately its rated traction power
+    double maxDynamicPower = this->maxPower * 1000.0; // kW to W
+
+    // Dynamic braking fades linearly below 15 km/h (motor can't generate
+    // sufficient back-EMF at very low speeds)
+    double v_kmh = trainSpeed * 3.6;
+    double fadeFactor = std::min(v_kmh / EC::DynamicBrakingFadeSpeed_kmh, 1.0);
+    maxDynamicPower *= fadeFactor;
+
+    return std::min(std::abs(totalBrakingPower), maxDynamicPower);
+}
+
 double Locomotive::getMaxRechargeEnergy(double timeStep, double trainSpeed,
                                         double LocomotiveVirtualTractivePower)
 {

src/NeTrainSim/traindefinition/locomotive.h

@@ -481,6 +481,20 @@ class Locomotive : public TrainComponent{
     double getUsedPowerPortion(double trainSpeed,
                                double LocomotiveVirtualTractivePower);
 
+    /**
+     * @brief Gets the recoverable dynamic braking power, capped at motor capacity.
+     *
+     * @details In blended braking, only the dynamic braking portion (motor as generator)
+     * produces recoverable energy. This is capped at the motor's rated power and
+     * fades linearly below 15 km/h where dynamic braking becomes ineffective.
+     *
+     * @param totalBrakingPower  The total braking power magnitude in Watts (positive).
+     * @param trainSpeed         The current train speed in m/s.
+     * @returns The recoverable dynamic braking power in Watts (positive value).
+     */
+    double getRecoverableBrakingPower(double totalBrakingPower,
+                                      double trainSpeed);
+
     void rechargeBatteryByMaxFlow(double timeStep, double trainSpeed,
                                   double powerPortion,
                                   double fuelConversionFactor,

src/NeTrainSim/traindefinition/train.cpp

@@ -23,15 +23,13 @@ Train::Train(
     double trainStartTime_sec, double frictionCoeff,
     Vector<std::shared_ptr<Locomotive>> locomotives,
     Vector<std::shared_ptr<Car>> cars, bool optimize,
-    double desiredDecelerationRate_mPs,
     double operatorReactionTime_s, bool stopIfNoEnergy,
     double maxAllowedJerk_mPcs, double optimization_k,
     int runOptimizationEvery,
     int optimizationLookaheadSteps)
     : QObject(nullptr)
 {
 
-    this->d_des = desiredDecelerationRate_mPs;
     this->operatorReactionTime = operatorReactionTime_s;
     this->stopTrainIfNoEnergy  = stopIfNoEnergy;
     this->maxJerk              = maxAllowedJerk_mPcs;
@@ -68,7 +66,7 @@ Train::Train(
                                      Map<int, double>()));
     Train::NumberOfTrainsInSimulator++;
     this->T_s = this->operatorReactionTime
-                + (this->totalLength / this->speedOfSound);
+                + (this->totalLength / this->brakePipePropagationSpeed);
 
     for (auto &car : this->cars)
     {
@@ -173,6 +171,19 @@ double Train::getMinFollowingTrainGap()
     return DefaultMinFollowingGap;
 }
 
+double Train::getDesiredDeceleration(double speed)
+{
+    double totalBrakingForce = 0.0;
+    for (auto &vehicle : this->trainVehicles)
+    {
+        totalBrakingForce += vehicle->getBrakingForce(speed);
+    }
+    double d_physical = totalBrakingForce / this->totalMass;
+    double d = DefaultServiceBrakingFactor * d_physical;
+    double d_max = this->coefficientOfFriction * this->g;
+    return std::max(MinDesiredDeceleration, std::min(d, d_max));
+}
+
 double Train::getBatteryEnergyConsumed()
 {
     double total = 0.0;
@@ -640,15 +651,17 @@ double Train::getSafeGap(double initialGap, double speed,
     double gap_lad = 0;
     if (!estimate)
     {
+        double d = this->getDesiredDeceleration(speed);
         gap_lad = initialGap + T_s * speed
                   + (Utils::power(speed, 2)
-                     / (2.0 * this->d_des));
+                     / (2.0 * d));
     }
     else
     {
+        double d = this->getDesiredDeceleration(freeFlowSpeed);
         gap_lad = initialGap + T_s * freeFlowSpeed
                   + (Utils::power(freeFlowSpeed, 2)
-                     / (2.0 * this->d_des));
+                     / (2.0 * d));
     };
     return gap_lad;
 }
@@ -778,11 +791,12 @@ double Train::get_acceleration_an2(
     double gap, double minGap, double speed,
     double leaderSpeed, double T_s, double frictionCoef)
 {
+    double d = this->getDesiredDeceleration(speed);
     double term = 0.0;
     term        = Utils::power(Utils::power(speed, 2)
                                    - Utils::power(leaderSpeed, 2),
                                2)
-           / (4.0 * this->d_des);
+           / (4.0 * d);
     term =
         term / Utils::power(max((gap - minGap), 0.0001), 2);
     return min(term, frictionCoef * this->g);

src/NeTrainSim/traindefinition/train.h

@@ -53,8 +53,12 @@ class NETRAINSIMCORE_EXPORT Train : public QObject {
 private:
     /** Holds the number of trains in the simulator. */
     static unsigned int NumberOfTrainsInSimulator;
-    /** (Immutable) the default desired deceleration rate */
-    static constexpr double DefaultDesiredDecelerationRate = 0.2;
+    /** (Immutable) minimum desired deceleration to prevent infinite safe gaps (m/s^2) */
+    static constexpr double MinDesiredDeceleration = 0.05;
+    /** Fraction of emergency braking used for normal service braking.
+     *  0.5 = 50% of max brake force (Karwatzki physical maximum).
+     *  Typical: 0.35 heavy haul, 0.5 freight, 0.65 passenger. */
+    static constexpr double DefaultServiceBrakingFactor = 0.5;
     /** (Immutable) the default reaction time of the train operator */
     static constexpr double DefaultOperatorReactionTime = 1.0;
     /** (Immutable) the default switch of the train behaviour if no energy source */
@@ -71,14 +75,12 @@ class NETRAINSIMCORE_EXPORT Train : public QObject {
 public:
 
     /**
-     * (Immutable) the speed of sound in m / s, this is an approximation of the brackes back
-     * propagation
+     * (Immutable) brake pipe pressure wave propagation speed in m/s.
+     * Measured ~250 m/s for service braking on freight (Qiao 2018).
      */
-    static constexpr double speedOfSound = 343.0;
+    static constexpr double brakePipePropagationSpeed = 250.0;
     /** (Immutable) gravitational acceleration */
     const double g = 9.8066;
-    /** The desired decceleration value */
-    double d_des;
     /** the perception reaction time of the train operator. */
     double operatorReactionTime;
     /** Total length of the train */
@@ -273,15 +275,12 @@ class NETRAINSIMCORE_EXPORT Train : public QObject {
      * @param 	locomotives				   	The locomotives.
      * @param 	cars					   	The cars.
      * @param 	optimize				   	True to optimize.
-     * @param 	desiredDecelerationRate_mPs	(Optional) The desired deceleration rate m ps.
      * @param 	operatorReactionTime_s	   	(Optional) The operator reaction time s.
      * @param 	stopIfNoEnergy			   	(Optional) True to stop if no energy.
-     * @param 	isRunnigOffGrid			   	(Optional) True if is runnig off grid, false if not.
      * @param 	maxAllowedJerk_mPcs		   	(Optional) The maximum allowed jerk m pcs.
      */
     Train(int simulatorID, string id, Vector<int> trainPath, double trainStartTime_sec, double frictionCoeff,
           Vector<std::shared_ptr<Locomotive>> locomotives, Vector<std::shared_ptr<Car>> cars, bool optimize,
-          double desiredDecelerationRate_mPs = DefaultDesiredDecelerationRate,
           double operatorReactionTime_s = DefaultOperatorReactionTime,
           bool stopIfNoEnergy = DefaultStopIfNoEnergy,
           double maxAllowedJerk_mPcs = DefaultMaxAllowedJerk,
@@ -344,6 +343,20 @@ class NETRAINSIMCORE_EXPORT Train : public QObject {
      */
     double getMinFollowingTrainGap();
 
+    /**
+     * @brief Gets the speed-dependent desired deceleration rate.
+     *
+     * @details Computes comfortable braking deceleration for the
+     * car-following safe gap calculation. Sums per-vehicle shoe braking
+     * forces (Karwatzki model), divides by total train mass, then scales
+     * by DefaultBrakingComfortFactor to convert from physical maximum
+     * to a desired comfortable rate.
+     *
+     * @param speed The current train speed in m/s.
+     * @returns The desired deceleration in m/s^2.
+     */
+    double getDesiredDeceleration(double speed);
+
     /**
      * @brief set the current links the train is spanning
      * @param newLinks

src/NeTrainSim/traindefinition/traincomponent.cpp

@@ -6,6 +6,12 @@ double TrainComponent::getResistance(double trainSpeed) {
 	return 0.0;
 }
 
+double TrainComponent::getBrakingForce(double trainSpeed) {
+    double muShoe = EC::getBrakeShoeFriction(trainSpeed);
+    double weightKg = this->currentWeight * 1000.0;
+    return this->brakedWeightRatio * weightKg * EC::g * muShoe;
+}
+
 void TrainComponent::resetTimeStepConsumptions() {
     // reset the energy consumption for the time step.
 	this->energyConsumed = 0.0;

src/NeTrainSim/traindefinition/traincomponent.h

@@ -47,6 +47,8 @@ class TrainComponent : public Battery, public Tank{
 	int noOfAxiles;
 	/** Auxiliary power */
 	double auxiliaryPower;
+	/** The braked weight ratio for this vehicle (UIC lambda). Set by subclass constructors. */
+	double brakedWeightRatio = 0.8;
 
     /** The amount of energy consumed in kwh*/
 	double energyConsumed = 0.0;
@@ -92,6 +94,20 @@ class TrainComponent : public Battery, public Tank{
 	 */
 	virtual double getResistance(double trainSpeed);
 
+	/**
+	 * \brief Gets the braking force for this vehicle at the given speed.
+	 *
+	 * \details Computes per-vehicle braking force using the Karwatzki model:
+	 *   F = brakedWeightRatio * weight * g * mu_shoe(v)
+	 *
+	 * Grade is excluded because it causes discontinuous jumps when vehicles
+	 * cross link boundaries and is already captured in the resistance model.
+	 *
+	 * @param trainSpeed The current train speed in m/s.
+	 * @returns The braking force in Newtons (shoe friction only).
+	 */
+	virtual double getBrakingForce(double trainSpeed);
+
 	/**
 	 * \brief Resets the energy consumptions data for the current time step
 	 *