defines a rail locomotive. More...

#include <locomotive.h>

Inheritance diagram for Locomotive:

Public Member Functions
	Locomotive (double locomotiveMaxPower_kw, double locomotiveTransmissionEfficiency, double locomotiveLength_m, double locomotiveDragCoef, double locomotiveFrontalArea_sqm, double locomotiveWeight_t, int locomotiveNoOfAxiles=DefaultLocomotiveNoOfAxiles, int locomotivePowerType=DefaultLocomotiveType, double locomotiveMaxSpeed_mps=DefaultLocomotiveMaxSpeed, int totalNotches=DefaultLocomotiveNoOfNotches, int locomotiveMaxAchievableNotch=DefaultLocomotiveMaxAcheivableNotch, double locomotiveAuxiliaryPower_kw=EC::DefaultLocomotiveAuxiliaryPower, string locomotiveName=DefaultLocomotiveName, double batteryMaxCharge_kwh=std::numeric_limits< double >::quiet_NaN(), double batteryInitialCharge_perc=std::numeric_limits< double >::quiet_NaN(), double tankMaxCapacity_kg=EC::DefaultLocomotiveTankMaxCapacityDiesel, double tankInitialCapacity_perc=EC::DefaultLocomotiveTankInitialCapacity, double batteryCRate=EC::DefaultLocomotiveBatteryCRate, TrainTypes::LocomotivePowerMethod theHybridMethod=TrainTypes::LocomotivePowerMethod::notApplicable)
	!

string	getPowerTypeString ()
	Gets power type as a string.

TrainTypes::PowerType	getPowerTypeEnum (string powertype)
	Gets power type as an enum.

double	getHyperbolicThrottleCoef (double &trainSpeed)
	Gets hyperbolic throttle coef.

double	getlamdaDiscretized (double &lamda)
	Get lamda discretized.

double	getDiscretizedThrottleCoef (double &trainSpeed)
	Gets discretized throttle coef.

double	getThrottleLevel (double &trainSpeed, bool &optimize, double &optimumThrottleLevel)
	Gets the throttle level the locomotive should move by.

double	getResistance (double trainSpeed) override
	Gets the resistance this locomotive is contributing to the whole train.

double	getTractiveForce (double &frictionCoef, double &trainSpeed, bool &optimize, double &optimumThrottleLevel)
	Gets tractive force that this locomotive can generate by the current speed and notch level.

double	getNetForce (double &frictionCoef, double &trainAcceleration, bool &optimize, double &optimumThrottleLevel)
	Gets net force.

double	getSharedVirtualTractivePower (double &trainSpeed, double &trainAcceleration, double &sharedWeight, double &sharedResistance)
	Gets shared virtual tractive power.

double	getRegenerativeEffeciency (double &LocomotiveVirtualTractivePower, double &trainAcceleration, double &trainSpeed)
	get the regenerative effeciency at that speed when decelerating

double	getEnergyConsumptionAtDCBus (double &LocomotiveVirtualTractivePower, double &trainAcceleration, double &trainSpeed, double &timeStep)
	get the Energy Consumption At DC Bus

double	getEnergyConsumptionAtTank (double &LocomotiveVirtualTractivePower, double &trainSpeed, double EnergyConsumptionAtDCBus)
	get the Energy Consumption At Tank

double	getEnergyConsumption (double &LocomotiveVirtualTractivePower, double &acceleration, double &speed, double &timeStep)
	Gets energy consumption of this locomotive.

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) override
	Consume the locomotive fuel.

double	getMaxRechargeEnergy (double timeStep, double trainSpeed, double LocomotiveVirtualTractivePower)
	Get the max energy the locomotive can regenerate.

double	getUsedPowerPortion (double trainSpeed, double LocomotiveVirtualTractivePower)
	getUsedPowerPortion

void	rechargeBatteryByMaxFlow (double timeStep, double trainSpeed, double powerPortion, double fuelConversionFactor, double fuelDensity, double LocomotiveVirtualTractivePower, std::function< std::pair< bool, double >(double, double, double)> ConsumeFuelFunc)

std::pair< bool, double >	consumeEnergyFromHybridTechnology (double timeStep, double trainSpeed, double powerPortion, double EC_kwh, double fuelConversionFactor, double fuelDensity, double LocomotiveVirtualTractivePower, std::function< std::pair< bool, double >(double, double, double)> ConsumeFuelFunc)

Vector< double >	defineThrottleLevels ()
	Define throttle levels.

void	updateLocNotch (double &trainSpeed)
	Updates the location notch described by trainSpeed.

void	reducePower (double &reductionFactor)
	reduce the power that the locomotive is producing by reducing the notch position to a lower position.

void	resetPowerRestriction ()
	reset lower power restriction on the locomotive.

double	getMaxProvidedEnergy (double &timeStep)
	getMaxProvidedEnergy

double	canProvideEnergy (double &EC, double &timeStep)
	check if the locomotive can provide required energy

Public Member Functions inherited from TrainComponent
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
double	maxPower
	The max power of the locomotive in kw.

double	currentTractiveForce = 0.0
	The tractive forces of this time step.

double	transmissionEfficiency
	Transmission effeciency of the locomotive.

TrainTypes::PowerType	powerType
	The type of the car.

TrainTypes::LocomotivePowerMethod	hybridMethod
	the hybrid technology whether it is series or paralletl.

double	maxSpeed
	Current used notch max speed.

bool	isLocOn = true
	Decide if the locomotive is adding power to the train.

int	Nmax = 8
	Number of notches the locomotives have.

int	maxLocNotch = 0
	The max notch the locomotive is allowed to achieve, if zero, then use all notches.

int	currentLocNotch = 0
	The current notch the locomotive is going by.

double	locPowerReductionFactor = 1.0
	The forced lower power factor to the locomotive in case lower energy consumption is required.

Vector< double >	discritizedLamda
	The discretized throttlelevels.

double	throttleLevel
	The current throttle level based on the current notch.

Vector< double >	throttleLevels
	The throttle levels.

const double	g = 9.8067
	(Immutable) the gravitation acceleration

double	usedPowerPortion = 0.0

Public Attributes inherited from TrainComponent
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, Locomotive &stud)
	Stream insertion operator.

Detailed Description

defines a rail locomotive.

This class inherits the TrainComponent class.

The locomotive provide power to the train unlike the railcar. locomotives can have different powertrains (different technologies). For every technology, there is an associated effeciencies and conversion factors. These conversion factors and efficiencies are accessible from the EC namespace. The locomotive may have a battery and/or tank based on its type. once the locomotive's stored power is low. the locomotive attempts to request energy from the tenders if available. if not, the locomotive is turned off.

Author: Ahmed Aredah

Date: 2/28/2023

Constructor & Destructor Documentation

◆ Locomotive()

Locomotive::Locomotive	(	double	locomotiveMaxPower_kw,
		double	locomotiveTransmissionEfficiency,
		double	locomotiveLength_m,
		double	locomotiveDragCoef,
		double	locomotiveFrontalArea_sqm,
		double	locomotiveWeight_t,
		int	locomotiveNoOfAxiles = `DefaultLocomotiveNoOfAxiles`,
		int	locomotivePowerType = `DefaultLocomotiveType`,
		double	locomotiveMaxSpeed_mps = `DefaultLocomotiveMaxSpeed`,
		int	totalNotches = `DefaultLocomotiveNoOfNotches`,
		int	locomotiveMaxAchievableNotch = `DefaultLocomotiveMaxAcheivableNotch`,
		double	locomotiveAuxiliaryPower_kw = `EC::DefaultLocomotiveAuxiliaryPower`,
		string	locomotiveName = `DefaultLocomotiveName`,
		double	batteryMaxCharge_kwh = `std::numeric_limits<double>::quiet_NaN()`,
		double	batteryInitialCharge_perc = `std::numeric_limits<double>::quiet_NaN()`,
		double	tankMaxCapacity_kg = `EC::DefaultLocomotiveTankMaxCapacityDiesel`,
		double	tankInitialCapacity_perc = `EC::DefaultLocomotiveTankInitialCapacity`,
		double	batteryCRate = `EC::DefaultLocomotiveBatteryCRate`,
		TrainTypes::LocomotivePowerMethod	theHybridMethod = `TrainTypes::LocomotivePowerMethod::notApplicable`
	)

!

the constructor for the locomotive class

the constructor sets the definition of the locomotive and initialize its default values.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

locomotiveMaxPower_kw	The locomotive maximum power kw.
locomotiveTransmissionEfficiency	The locomotive transmission efficiency.
locomotiveLength_m	The locomotive length m.
locomotiveDragCoef	The locomotive drag coef.
locomotiveFrontalArea_sqm	The locomotive frontal area sqm.
locomotiveWeight_t	The locomotive weight.
locomotiveNoOfAxiles	(Optional) The locomotive no of axiles.
locomotivePowerType	(Optional) Type of the locomotive power.
locomotiveMaxSpeed_mps	(Optional) The locomotive maximum speed mps.
totalNotches	(Optional) The total notches.
locomotiveMaxAchievableNotch	(Optional) The locomotive maximum achievable notch.
locomotiveAuxiliaryPower_kw	(Optional) The locomotive auxiliary power kw.
locomotiveName	(Optional) Name of the locomotive.
batteryMaxCharge_kwh	(Optional) The battery maximum charge kwh.
batteryInitialCharge_perc	(Optional) The battery initial charge perc.
tankMaxCapacity_kg	(Optional) The tank maximum capacity kilograms.
tankInitialCapacity_perc	(Optional) The tank initial capacity perc.

Member Function Documentation

◆ canProvideEnergy()

double Locomotive::canProvideEnergy	(	double &	EC,
		double &	timeStep
	)

check if the locomotive can provide required energy

Parameters

EC
timeStep

Returns

◆ consumeEnergyFromHybridTechnology()

std::pair< bool, double > Locomotive::consumeEnergyFromHybridTechnology	(	double	timeStep,
		double	trainSpeed,
		double	powerPortion,
		double	EC_kwh,
		double	fuelConversionFactor,
		double	fuelDensity,
		double	LocomotiveVirtualTractivePower,
		std::function< std::pair< bool, double >(double, double, double)>	ConsumeFuelFunc
	)

◆ consumeFuel()

std::pair< bool, double > Locomotive::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`
	)

overridevirtual

Consume the locomotive fuel.

If the locomotive does not have the necessary power to continue, It searches for the power from any other tender. if there is no tenders available, the locomotive is shut down.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

timeStep	The simulator time step in seconds.
trainSpeed	The speed of the train in m/s.
EC_kwh	The energy consumption in kwh.
isOffGrid	True if is off grid, false if not.
dieselConversionFactor	(Optional) The diesel conversion factor that convert from kwh to liters.
bioDieselConversionFactor	(Optional) The biodiesel conversion factor that convert from kwh to liters.
hydrogenConversionFactor	(Optional) The hydrogen conversion factor that convert from kWh to liters.
dieselDensity	(Optional) The diesel density in kg/liter.
biodieselDensity	(Optional) The biodiesel density in kg/liter.
hydrogenDensity	(Optional) The hydrogen density in kg/liter.

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

Reimplemented from TrainComponent.

◆ defineThrottleLevels()

Vector< double > Locomotive::defineThrottleLevels ( )

Define throttle levels.

Author: Ahmed Aredah

Date: 2/28/2023

Returns: A Vector<double>

◆ getDiscretizedThrottleCoef()

double Locomotive::getDiscretizedThrottleCoef ( double & trainSpeed )

Gets discretized throttle coef.

for more details refer to the published paper. [Aredah], A.; Fadhloun, K.; Rakha, H.; List, G. NeTrainSim: A Network Freight Train Simulator for Estimating Energy/ Fuel Consumption. Preprints 2022, 2022080518. https://doi.org/10.20944/ preprints202208.0518.v1.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out] trainSpeed The train speed.

Returns: The discretized throttle coef.

◆ getEnergyConsumption()

double Locomotive::getEnergyConsumption	(	double &	LocomotiveVirtualTractivePower,
		double &	acceleration,
		double &	speed,
		double &	timeStep
	)

Gets energy consumption of this locomotive.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out]	LocomotiveVirtualTractivePower	The locomotive virtual tractive power.
[in,out]	speed	The train speed in m/s.
[in,out]	acceleration	The train acceleration in m/s^2.
[in,out]	timeStep	The simulator time step in seconds.

Returns: The energy consumption in KWh.

◆ getEnergyConsumptionAtDCBus()

double Locomotive::getEnergyConsumptionAtDCBus	(	double &	LocomotiveVirtualTractivePower,
		double &	trainAcceleration,
		double &	trainSpeed,
		double &	timeStep
	)

get the Energy Consumption At DC Bus

Author: Ahmed Aredah

Date: 4/28/2023

Parameters

LocomotiveVirtualTractivePower
trainAcceleration
trainSpeed
timeStep

Returns

◆ getEnergyConsumptionAtTank()

double Locomotive::getEnergyConsumptionAtTank	(	double &	LocomotiveVirtualTractivePower,
		double &	trainSpeed,
		double	EnergyConsumptionAtDCBus
	)

get the Energy Consumption At Tank

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

LocomotiveVirtualTractivePower
trainSpeed
EnergyConsumptionAtDCBus

Returns

◆ getHyperbolicThrottleCoef()

double Locomotive::getHyperbolicThrottleCoef ( double & trainSpeed )

Gets hyperbolic throttle coef.

refer to the published paper for more details. [Aredah], A.; Fadhloun, K.; Rakha, H.; List, G. NeTrainSim: A Network Freight Train Simulator for Estimating Energy/Fuel Consumption. Preprints 2022, 2022080518. https://doi.org/10.20944/ preprints202208.0518.v1.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out] trainSpeed The train speed in m/s.

Returns: The hyperbolic throttle coefficient.

◆ getlamdaDiscretized()

double Locomotive::getlamdaDiscretized ( double & lamda )

Get lamda discretized.

for more details refer to the published paper.

this function discretize the continous throttle level function 'getHyperbolicThrottleCoef' [Aredah], A.; Fadhloun, K.; Rakha, H.; List, G. NeTrainSim: A Network Freight Train Simulator for Estimating Energy/Fuel Consumption. Preprints 2022, 2022080518. https://doi.org/10.20944/ preprints202208.0518.v1.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out] lamda The throttle level coefficient (as a continuous value). This comes from the @getHyper

Returns: A double.

◆ getMaxProvidedEnergy()

double Locomotive::getMaxProvidedEnergy ( double & timeStep )

getMaxProvidedEnergy

Parameters

timeStep

Returns

◆ getMaxRechargeEnergy()

double Locomotive::getMaxRechargeEnergy	(	double	timeStep,
		double	trainSpeed,
		double	LocomotiveVirtualTractivePower
	)

Get the max energy the locomotive can regenerate.

this depends on the max power from the generator can produce.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

timeStep
trainSpeed
LocomotiveVirtualTractivePower

Returns

◆ getNetForce()

double Locomotive::getNetForce	(	double &	frictionCoef,
		double &	trainAcceleration,
		bool &	optimize,
		double &	optimumThrottleLevel
	)

Gets net force.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out]	frictionCoef	The friction coef of the rail.
[in,out]	trainSpeed	The train speed in m/s.
[in,out]	optimize	True to optimize.
[in,out]	optimumThrottleLevel	The optimum throttle level in cae of optimization is enabled.

Returns: The net force in Newton.

◆ getPowerTypeEnum()

TrainTypes::PowerType Locomotive::getPowerTypeEnum ( string powertype )

Gets power type as an enum.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

powertype The powertype of the locomotive.

Returns: The power type as an enum.

◆ getPowerTypeString()

string Locomotive::getPowerTypeString ( )

Gets power type as a string.

Author: Ahmed Aredah

Date: 2/28/2023

Returns: The power type as a string.

◆ getRegenerativeEffeciency()

double Locomotive::getRegenerativeEffeciency	(	double &	LocomotiveVirtualTractivePower,
		double &	trainAcceleration,
		double &	trainSpeed
	)

get the regenerative effeciency at that speed when decelerating

Author: Ahmed Aredah

Date: 4/28/2023

Parameters

LocomotiveVirtualTractivePower
trainAcceleration
trainSpeed

Returns

◆ getResistance()

double Locomotive::getResistance ( double trainSpeed )

overridevirtual

Gets the resistance this locomotive is contributing to the whole train.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

trainSpeed The train speed in m/s.

Returns: The resistance in Newton.

Reimplemented from TrainComponent.

◆ getSharedVirtualTractivePower()

double Locomotive::getSharedVirtualTractivePower	(	double &	trainSpeed,
		double &	trainAcceleration,
		double &	sharedWeight,
		double &	sharedResistance
	)

Gets shared virtual tractive power.

The virtual power is the power when the train is on a negative slope.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out]	trainSpeed	The train speed in m/s.
[in,out]	trainAcceleration	The train acceleration in m/s^2.
[in,out]	sharedWeight	The shared weight is the weight this locomotive is pulling. It includes the portion of the train weight this locomotive is responsible for.
[in,out]	sharedResistance	The shared resistance. This includes the portion of the train resistance, this locomotiv is responsible for.

Returns: The shared virtual tractive power in kW.

◆ getThrottleLevel()

double Locomotive::getThrottleLevel	(	double &	trainSpeed,
		bool &	optimize,
		double &	optimumThrottleLevel
	)

Gets the throttle level the locomotive should move by.

for more details refer to the published paper. [Aredah], A.; Fadhloun, K.; Rakha, H.; List, G. NeTrainSim: A Network Freight Train Simulator for Estimating Energy/ Fuel Consumption. Preprints 2022, 2022080518. https://doi.org/10.20944/ preprints202208.0518.v1.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out]	trainSpeed	The train speed in m/s.
[in,out]	optimize	True to optimize.
[in,out]	optimumThrottleLevel	The optimum throttle level in case the optimization is enabled.

Returns: The throttle level.

◆ getTractiveForce()

double Locomotive::getTractiveForce	(	double &	frictionCoef,
		double &	trainSpeed,
		bool &	optimize,
		double &	optimumThrottleLevel
	)

Gets tractive force that this locomotive can generate by the current speed and notch level.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out]	frictionCoef	The friction coef of the rail.
[in,out]	trainSpeed	The train speed in m/s.
[in,out]	optimize	True to optimize.
[in,out]	optimumThrottleLevel	The optimum throttle level in case of optimization is eneabled.

Returns: The tractive force in Newton.

◆ getUsedPowerPortion()

double Locomotive::getUsedPowerPortion	(	double	trainSpeed,
		double	LocomotiveVirtualTractivePower
	)

getUsedPowerPortion

Parameters

trainSpeed
LocomotiveVirtualTractivePower

Returns

◆ rechargeBatteryByMaxFlow()

void Locomotive::rechargeBatteryByMaxFlow	(	double	timeStep,
		double	trainSpeed,
		double	powerPortion,
		double	fuelConversionFactor,
		double	fuelDensity,
		double	LocomotiveVirtualTractivePower,
		std::function< std::pair< bool, double >(double, double, double)>	ConsumeFuelFunc
	)

◆ reducePower()

void Locomotive::reducePower ( double & reductionFactor )

reduce the power that the locomotive is producing by reducing the notch position to a lower position.

if the locomotive could reduce the notch position to a lower position, reduce it. O.W, turn the locomotive off in case the locomotive was already moving by the notch 1.

Author: Ahmed Aredah

Date: 3/12/2023

◆ resetPowerRestriction()

void Locomotive::resetPowerRestriction ( )

reset lower power restriction on the locomotive.

Author: Ahmed Aredah

Date: 3/12/2023

◆ updateLocNotch()

void Locomotive::updateLocNotch ( double & trainSpeed )

Updates the location notch described by trainSpeed.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

[in,out] trainSpeed The train speed in m/s.

Friends And Related Symbol Documentation

◆ operator<<

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

friend

Stream insertion operator.

Author: Ahmed Aredah

Date: 2/28/2023

Parameters

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

Returns: The shifted result.

Member Data Documentation

◆ currentLocNotch

int Locomotive::currentLocNotch = 0

The current notch the locomotive is going by.

◆ currentTractiveForce

double Locomotive::currentTractiveForce = 0.0

The tractive forces of this time step.

◆ discritizedLamda

Vector<double> Locomotive::discritizedLamda

The discretized throttlelevels.

◆ g

const double Locomotive::g = 9.8067

(Immutable) the gravitation acceleration

◆ hybridMethod

TrainTypes::LocomotivePowerMethod Locomotive::hybridMethod

the hybrid technology whether it is series or paralletl.

◆ isLocOn

bool Locomotive::isLocOn = true

Decide if the locomotive is adding power to the train.

◆ locPowerReductionFactor

double Locomotive::locPowerReductionFactor = 1.0

The forced lower power factor to the locomotive in case lower energy consumption is required.

◆ maxLocNotch

int Locomotive::maxLocNotch = 0

The max notch the locomotive is allowed to achieve, if zero, then use all notches.

◆ maxPower

double Locomotive::maxPower

The max power of the locomotive in kw.

◆ maxSpeed

double Locomotive::maxSpeed

Current used notch max speed.

◆ Nmax

int Locomotive::Nmax = 8

Number of notches the locomotives have.

◆ powerType

TrainTypes::PowerType Locomotive::powerType

The type of the car.

◆ throttleLevel

double Locomotive::throttleLevel

The current throttle level based on the current notch.

◆ throttleLevels

Vector<double> Locomotive::throttleLevels

The throttle levels.

◆ transmissionEfficiency

double Locomotive::transmissionEfficiency

Transmission effeciency of the locomotive.

◆ usedPowerPortion

double Locomotive::usedPowerPortion = 0.0

	NeTrainSim 0.1.1 beta The Open-Source Network Trains Simulator

Public Member Functions

Public Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Locomotive()

Member Function Documentation

◆ canProvideEnergy()

◆ consumeEnergyFromHybridTechnology()

◆ consumeFuel()

◆ defineThrottleLevels()

◆ getDiscretizedThrottleCoef()

◆ getEnergyConsumption()

◆ getEnergyConsumptionAtDCBus()

◆ getEnergyConsumptionAtTank()

◆ getHyperbolicThrottleCoef()

◆ getlamdaDiscretized()

◆ getMaxProvidedEnergy()

◆ getMaxRechargeEnergy()

◆ getNetForce()

◆ getPowerTypeEnum()

◆ getPowerTypeString()

◆ getRegenerativeEffeciency()

◆ getResistance()

◆ getSharedVirtualTractivePower()

◆ getThrottleLevel()

◆ getTractiveForce()

◆ getUsedPowerPortion()

◆ rechargeBatteryByMaxFlow()

◆ reducePower()

◆ resetPowerRestriction()

◆ updateLocNotch()

Friends And Related Symbol Documentation

◆ operator<<

Member Data Documentation

◆ currentLocNotch

◆ currentTractiveForce

◆ discritizedLamda

◆ g

◆ hybridMethod

◆ isLocOn

◆ locPowerReductionFactor

◆ maxLocNotch

◆ maxPower

◆ maxSpeed

◆ Nmax

◆ powerType

◆ throttleLevel

◆ throttleLevels

◆ transmissionEfficiency

◆ usedPowerPortion