Defines a train component base class. More...

#include <traincomponent.h>

Inheritance diagram for TrainComponent:

Public Member Functions
virtual double	getResistance (double trainSpeed)
	Gets the resistance applied on only this vehicle.

virtual void	resetTimeStepConsumptions ()
	Resets the energy consumptions data for the current time step.

virtual void	setCurrentWeight (double newCurrentWeight)
	sets the current weight of the vehicle

virtual std::pair< bool, double >	consumeFuelDiesel (double EC_kwh, double dieselConversionFactor, double dieselDensity)
	consume the locomotive diesel fuel.

virtual std::pair< bool, double >	consumeFuelBioDiesel (double EC_kwh, double bioDieselConversionFactor, double bioDieselDensity)
	consume the locomotive bio diesel fuel.

virtual std::pair< bool, double >	consumeElectricity (double timeStep, double EC_kwh)
	consume any source of electricity in the locomotive; either the catenary or the batteries.

virtual std::pair< bool, double >	consumeFuelHydrogen (double EC_kwh, double hydrogenConversionFactor, double hydrogenDensity)
	consume the locomotive hydrogen fuel.

virtual double	refillBattery (double timeStep, double EC_kwh)
	refill the locomtoive battery

virtual bool	rechargeCatenary (double EC_kwh)
	Rechage catenary and grid system if they are available.

virtual std::pair< bool, double >	consumeFuel (double timeStep, double trainSpeed, double EC_kwh, double LocomotiveVirtualTractivePower=std::numeric_limits< double >::quiet_NaN(), double dieselConversionFactor=EC::DefaultDieselConversionFactor, double biodieselConversionFactor=EC::DefaultBiodieselConversionFactor, double hydrogenConversionFactor=EC::DefaultHydrogenConversionFactor, double dieselDensity=EC::DefaultDieselDensity, double biodieselDensity=EC::DefaultBioDieselDensity, double hydrogenDensity=EC::DefaultHydrogenDensity)
	Consume fuel or battery from the vehicle.

Public Member Functions inherited from Battery
void	setBattery (double maxCharge, double initialChargePercentage, double depthOfDischarge, double batteryCRate, double maxRechargeSOC=0.9, double minRechargeSOC=0.5)
	Sets the battery properties.

double	getBatteryMaxCharge () const
	Gets the maximum charge of the battery.

void	setBatteryMaxCharge (double newMaxCharge)
	Sets the maximum charge of the battery.

double	getBatteryInitialCharge () const
	Gets the initial charge of the battery.

void	setBatteryInitialCharge (double newInitialCharge)
	Sets the initial charge of the battery.

double	getBatteryCurrentCharge () const
	Gets the current charge of the battery.

std::pair< bool, double >	consumeBattery (double timeStep, double consumedCharge)
	Consumes charge from the battery.

double	rechargeBatteryForHybrids (double timeStep, double recharge)
	Recharges the battery for hybrid vehicles.

double	rechargeBatteryByRegeneratedEnergy (double timeStep, double recharge)
	Recharges the battery by regenerated energy.

double	getBatteryStateOfCharge () const
	Gets the state of charge of the battery.

double	getBatteryDOD () const
	Gets the depth of discharge of the battery.

void	setBatteryDOD (double newBatteryDOD)
	Sets the depth of discharge of the battery.

double	getBatteryCRate () const
	Gets the C-Rate of discharge for the battery.

void	setBatteryCRate (double newBatteryCRate)
	Sets the C-Rate of discharge for the battery.

bool	isBatteryDrainable (double requiredCharge)
	Checks if the battery can be drained by the required charge.

bool	isBatteryRechargable ()
	Checks if the battery can be recharged.

double	getBatteryMaxDischarge (double timeStep)
	Gets the maximum discharge of the battery.

double	getBatteryMaxRecharge (double timeStep)
	Gets the maximum recharge of the battery.

bool	isRechargeRequired () const
	Checks if the battery requires a recharge.

double	getBatteryRechargeSOCUpperBound () const
	Gets the upper bound of the battery's recharge state of charge.

void	setBatteryRechargeSOCUpperBound (double newBatteryMaxSOC)
	Sets the upper bound of the battery's recharge state of charge.

double	getBatteryRechargeSOCLowerBound () const
	Gets the lower bound of the battery's recharge state of charge.

void	setBatteryRechargeSOCLowerBound (double newBatteryRechargeSOCLowerBound)
	Sets the lower bound of the battery's recharge state of charge.

double	getBatteryCumEnergyConsumption ()
	Gets the cumulative energy consumption for this battery only.

double	getBatteryCumEnergyRegenerated ()
	Gets the cumulative energy regenerated for this battery only.

double	getBatteryCumNetEnergyConsumption ()
	Gets the cumulative net energy consumption for this battery.

bool	batteryHasCharge ()
	Checks if the battery has enough charge.

bool	IsBatteryExceedingThresholds ()
	Checks if the battery exceeds certain thresholds.

Public Member Functions inherited from Tank
void	SetTank (double maxCapacity, double initialCapacityPercentage, double depthOfDischarge)
	Set the main properties of the tank (initialize the tank)

double	getTankMaxCapacity () const
	Gets the maximum capacity of the tank.

void	setTankMaxCapacity (double newMaxCapacity)
	Sets the maximum capacity of the tank.

double	getTankInitialCapacity () const
	Gets the initial capacity of the tank.

void	setTankInitialCapacity (double newInitialCapacityPercentage)
	Sets the initial capacity of the tank.

double	getTankCurrentCapacity () const
	Gets the current capacity of the tank.

double	consumeTank (double consumedAmount)
	Consumes fuel from the tank.

double	getTankStateOfCapacity () const
	Gets the state of capacity of the tank.

bool	isTankDrainable (double consumedAmount)
	Checks if the specified amount of fuel is drainable from the tank.

double	getTankDOD () const
	Gets the depth of discharge of the tank.

void	setTankDOD (double newTankDOD)
	Sets the depth of discharge of the tank.

bool	tankHasFuel ()
	Checks if the tank has fuel (current capacity > 0)

double	getTankCumConsumedFuel () const
	Gets the total amount of fuel consumed from the tank.

Public Attributes
std::string	name
	The name of the vehicle.

double	length
	Length of the vehicle in meter.

double	trackCurvature
	The current curvature the vehicle is experiencing.

double	trackGrade
	The current grade the vehicle is experiencing.

double	dragCoef
	The air drag factor for aerodynamics resistance.

double	frontalArea
	The total frontal area of the vehicle for the aerodynamics resistance.

double	currentWeight
	The gross weight of the vehicle when the train is travelling.

double	emptyWeight
	The light weight of the vehicle when the train is travelling.

int	noOfAxiles
	The number of axiles the car has.

double	auxiliaryPower
	Auxiliary power.

double	energyConsumed = 0.0
	The amount of energy consumed in kwh.

double	cumEnergyConsumed = 0.0
	The amount of cummulative energy consumed in kwh.

double	energyRegenerated = 0.0
	The amount of energy regenerated in kwh.

double	cumEnergyRegenerated = 0.0
	The amount of cummulative energy regenerated in kwh.

std::shared_ptr< NetLink >	hostLink
	Holds the current link this vehicle is on.

Friends
ostream &	operator<< (ostream &ostr, TrainComponent &stud)
	Stream insertion operator.

Detailed Description

Defines a train component base class.

The train component could be a railcar or a locomotive.

Author: Ahmed

Date: 2/14/2023

Member Function Documentation

◆ consumeElectricity()

std::pair< bool, double > TrainComponent::consumeElectricity	(	double	timeStep,
		double	EC_kwh
	)

virtual

consume any source of electricity in the locomotive; either the catenary or the batteries.

Author: Ahmed

Date: 2/14/2023

the function consumes the electricity stored in the locomotive batteries or provided by the catenary if available. For battery: It checks the amout of energy required by the locomotive below the max amount the battery can provide.

if yes, it consumes it from the battery and returns (true, 0.0),
if no, it consumes the max that the battery can provide and return (true, 0.0), If the battery cannot provide any energy because it is empty, it returns (false, 0.0). For Catenary: It consumes the whole amount of energy required from the catenary.

Parameters

EC_kwh	is the energy required for the locomotive to keep running
minBatterySOC	is the battery min state of charge, which below it, the battery is considered empty.

Returns: std::pair<bool, double> bool: no energy consumed and double: rest of energy that needs to be consumed.

◆ consumeFuel()

std::pair< bool, double > TrainComponent::consumeFuel	(	double	timeStep,
		double	trainSpeed,
		double	EC_kwh,
		double	LocomotiveVirtualTractivePower = `std::numeric_limits<double>::quiet_NaN()`,
		double	dieselConversionFactor = `EC::DefaultDieselConversionFactor`,
		double	biodieselConversionFactor = `EC::DefaultBiodieselConversionFactor`,
		double	hydrogenConversionFactor = `EC::DefaultHydrogenConversionFactor`,
		double	dieselDensity = `EC::DefaultDieselDensity`,
		double	biodieselDensity = `EC::DefaultBioDieselDensity`,
		double	hydrogenDensity = `EC::DefaultHydrogenDensity`
	)

virtual

Consume fuel or battery from the vehicle.

if it energy required is greater than stored energy in tank/battery return true, otherwise false.

This function is responsible for fuel consumption or regeneration of energy. It takes as input the energy consumed in kWh, a boolean flag indicating whether the locomotive is off-grid or not, conversion factors for diesel and hydrogen, and diesel density. First: the function checks if the energy is to be consumed. If it is, it checks the type of the power source for the vehicle.

If it is of diesel or hydrogen types, it computes the quantity consumed in liters (for diesel) or in kg (for hydrogen).
based on the energy consumed and the provided conversion factors. If there is enough fuel, the function updates the variables for the energy consumed and the current state of the tank and returns true. Otherwise, it returns false indicating that the tank is empty.
If the power source is electric and the vehicle is off-grid, the function checks if there is enough charge left in the battery. If there is enough charge, the function updates the variables for the energy consumed and the current state of the battery and returns true. Otherwise, it returns false indicating that the battery is empty.
If the power source is electric and the locomotive is not off-grid, the function simply updates the variables for
the energy consumed and the cumulative energy consumed and returns true. Second, If the energy consumed is not greater than zero, the function checks if the power source is electric and the locomotive is off-grid. If that is the case, the function checks if there is room for recharging the battery. If there is, the function updates the variables for the energy regenerated and the current state of the battery and returns true. If there is no more room in the battery, the function updates the variables for the energy regenerated and the battery state of charge and returns true.

Author: Ahmed

Date: 2/14/2023

Parameters

EC_kwh	The energy consumption in kwh.
isOffGrid	True if is off grid, false if not.
dieselConversionFactor	(Optional) The diesel conversion factor from kwh to liters.
hydrogenConversionFactor	(Optional) The hydrogen conversion factor from kwh to kg.
dieselDensity	(Optional) The diesel density in kg/liter.

Returns: True if it succeeds, false if it fails.

Reimplemented in Car, and Locomotive.

◆ consumeFuelBioDiesel()

std::pair< bool, double > TrainComponent::consumeFuelBioDiesel	(	double	EC_kwh,
		double	bioDieselConversionFactor,
		double	bioDieselDensity
	)

virtual

consume the locomotive bio diesel fuel.

Author: Ahmed

Date: 2/14/2023

Parameters

EC_kwh	is the Energy consumption in kWH
bioDieselConversionFactor	is the diesel conversion factor from kWH to liters
bioDieselDensity	is the diesel density kg/liter

Returns

◆ consumeFuelDiesel()

std::pair< bool, double > TrainComponent::consumeFuelDiesel	(	double	EC_kwh,
		double	dieselConversionFactor,
		double	dieselDensity
	)

virtual

consume the locomotive diesel fuel.

Author: Ahmed

Date: 2/14/2023

Parameters

EC_kwh	is the Energy consumption in kWH
dieselConversionFactor	is the diesel conversion factor from kWH to liters
dieselDensity	is the diesel density kg/liter

Returns

◆ consumeFuelHydrogen()

std::pair< bool, double > TrainComponent::consumeFuelHydrogen	(	double	EC_kwh,
		double	hydrogenConversionFactor,
		double	hydrogenDensity
	)

virtual

consume the locomotive hydrogen fuel.

Author: Ahmed

Date: 2/14/2023

Parameters

EC_kwh
hydrogenConversionFactor

Returns

◆ getResistance()

double TrainComponent::getResistance ( double trainSpeed )

virtual

Gets the resistance applied on only this vehicle.

This function takes in a parameter trainSpeed and returns the resistance of a vehicle at a given speed. The function performs a series of calculations using various properties of the Car object, including its weight, number of axles, frontal area, drag coefficient, track grade, and track curvature.

$\begin{eqnarray*} Resistance = (1.5 + \frac{18}{axileWeight} + 0.03 * speed + \frac{frontalArea * dragCoef* speed^2}{vehicleWeight}) * totalWeight + 20 * vehicleWeight (trackGrade + 0.04 * curvature)\\ \end{eqnarray*}$

Author: Ahmed

Date: 2/14/2023

Parameters

trainSpeed The current time step train speed.

Returns: The resistance.

Reimplemented in Car, and Locomotive.

◆ rechargeCatenary()

bool TrainComponent::rechargeCatenary ( double EC_kwh )

virtual

Rechage catenary and grid system if they are available.

Author: Ahmed

Date: 2/14/2023

Parameters

EC_kwh

Returns

◆ refillBattery()

double TrainComponent::refillBattery	(	double	timeStep,
		double	EC_kwh
	)

virtual

refill the locomtoive battery

Author: Ahmed

Date: 2/14/2023

Parameters

timeStep
EC_kwh

Returns

◆ resetTimeStepConsumptions()

void TrainComponent::resetTimeStepConsumptions ( )

virtual

Resets the energy consumptions data for the current time step.

Author: Ahmed Aredah

Date: 2/18/2023

◆ setCurrentWeight()

void TrainComponent::setCurrentWeight ( double newCurrentWeight )

virtual

sets the current weight of the vehicle

Author: Ahmed

Date: 2/14/2023

Parameters

newCurrentWeight is the new weight of the vehicle in ton

Friends And Related Symbol Documentation

◆ operator<<

ostream & operator<<	(	ostream &	ostr,
		TrainComponent &	stud
	)

friend

Stream insertion operator.

Author: Ahmed

Date: 2/14/2023

Parameters

[in,out]	ostr	The ostr.
[in,out]	stud	The stud.

Returns: The shifted result.

Member Data Documentation

◆ auxiliaryPower

double TrainComponent::auxiliaryPower

Auxiliary power.

◆ cumEnergyConsumed

double TrainComponent::cumEnergyConsumed = 0.0

The amount of cummulative energy consumed in kwh.

◆ cumEnergyRegenerated

double TrainComponent::cumEnergyRegenerated = 0.0

The amount of cummulative energy regenerated in kwh.

◆ currentWeight

double TrainComponent::currentWeight

The gross weight of the vehicle when the train is travelling.

◆ dragCoef

double TrainComponent::dragCoef

The air drag factor for aerodynamics resistance.

◆ emptyWeight

double TrainComponent::emptyWeight

The light weight of the vehicle when the train is travelling.

◆ energyConsumed

double TrainComponent::energyConsumed = 0.0

The amount of energy consumed in kwh.

◆ energyRegenerated

double TrainComponent::energyRegenerated = 0.0

The amount of energy regenerated in kwh.

◆ frontalArea

double TrainComponent::frontalArea

The total frontal area of the vehicle for the aerodynamics resistance.

◆ hostLink

std::shared_ptr<NetLink> TrainComponent::hostLink

Holds the current link this vehicle is on.

◆ length

double TrainComponent::length

Length of the vehicle in meter.

◆ name

std::string TrainComponent::name

The name of the vehicle.

◆ noOfAxiles

int TrainComponent::noOfAxiles

The number of axiles the car has.

◆ trackCurvature

double TrainComponent::trackCurvature

The current curvature the vehicle is experiencing.

◆ trackGrade

double TrainComponent::trackGrade

The current grade the vehicle is experiencing.

	NeTrainSim 0.1.1 beta The Open-Source Network Trains Simulator

Public Member Functions

Public Attributes

Friends

Detailed Description

Member Function Documentation

◆ consumeElectricity()

◆ consumeFuel()

◆ consumeFuelBioDiesel()

◆ consumeFuelDiesel()

◆ consumeFuelHydrogen()

◆ getResistance()

◆ rechargeCatenary()

◆ refillBattery()

◆ resetTimeStepConsumptions()

◆ setCurrentWeight()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ auxiliaryPower

◆ cumEnergyConsumed

◆ cumEnergyRegenerated

◆ currentWeight

◆ dragCoef

◆ emptyWeight

◆ energyConsumed

◆ energyRegenerated

◆ frontalArea

◆ hostLink

◆ length

◆ name

◆ noOfAxiles

◆ trackCurvature

◆ trackGrade