A train is a sequence of one or several rail cars coupled with each other that can move in the rail yard and is controlled by Rail Library andProcess Modeling Library flowchart blocks. Trains, and not the rail cars are the main agents you are dealing with when creating the rail models. If a rail car is a part of a train, it is fully controlled by the train, so it will not accept most of low-level commands such as, for example, setSpeed() or couple().
Trains are created by TrainSource blocks and must be disposed by TrainDispose blocks. A train can be split into two trains by TrainDecouple and two trains can be combined into one by TrainCouple. Trains move in the rail yard under control of TrainMoveTo blocks. Trains can go through any Process Modeling Library blocks like Delay, Seize, Release, etc.
The cars in the train are ordered and there is always the first car and the last car (which are the same in case the train contains only one car). The orientation of cars at the time of the train creation is the same as of the train, but later on it can change as a result of coupling/decoupling. The length of the train (the length of the track portion occupied by the train) is equal to the sum of all car lengths.
The Rail Library does not have a notion of locomotive, or of any other car type: all rail cars are considered to be equal. Any train can move at any speed, or be coupled/decoupled at any side.
The train has cruise speed, acceleration, and deceleration properties. They are initially set up by TrainSource but can later on be changed via the train API. While the train is moving you can change its speed instantly or by applying acceleration and deceleration.
How-To video: Setting up a freight train
Train 3D animation
Function |
Description |
int size() |
Returns the number of cars in the train. |
double getLength() |
Returns the length of the train (the sum of lengths of all cars) in meters. |
double getLength(LengthUnits units) |
Returns the length of the train (the sum of lengths of all cars) in specified length units.
Parameter: |
boolean isEmpty() |
Tests if the train is empty, i.e. contains no cars. Returns true if empty, false otherwise. |
Agent getFirst() |
Returns the first car in the train, or null if the train is empty. |
Agent getLast() |
Returns the last car in the train, or null if the train is empty. |
Agent getHeadCar() |
Returns the car that is at the head of a moving train (either first or last), null if the train is not moving. |
Agent getTailCar() |
Returns the car that is at the tail of the moving train (either first or last), null if the train is not moving. |
Agent getCar(int i) |
Returns a car with a given index. the first car index is 0, the last car - size()-1.
Parameter: |
Function |
Description |
double getSpeed() |
Returns the speed of the train in meters/second. If the train is empty, returns 0. |
double getSpeed(SpeedUnits units) |
Returns the speed of the train in specified speed units. If the train is empty, returns 0.
Parameter: |
double getCruiseSpeed() |
Returns the cruise speed of the train in meters/second. |
double getCruiseSpeed(SpeedUnits units) |
Returns the cruise speed of the train in specified speed units.
Parameter: |
void setSpeed(double v) |
Sets the new speed of the train. It applies immediately even if the train is moving. If the train is not moving, just remembers the speed but does not start the train. While the train is moving, speed cannot be set to 0. Discards any
acceleration/deceleration with the exception of the final deceleration before arrival to target and the deceleration that occurs when the
pauseTrain()
function is called.
Parameter: |
void setSpeed(double v, SpeedUnits units) |
Sets the new speed of the train in the specified speed units. It applies immediately even if the train is moving. If the train is not moving, just remembers the speed but does not start the train. While the train is moving, speed cannot be set to
0. Discards any acceleration/deceleration with the exception of the final deceleration before arrival to target and the deceleration that occurs when the
pauseTrain()
function is called.
Parameters: |
void setCruiseSpeed(double speed) |
Sets the cruise speed of the train (must be >0) in meters per second.
Parameter: |
void setCruiseSpeed(double speed, SpeedUnits units) |
Sets the new cruise speed of the train (must be >0) in specified speed units.
Parameters: |
Function |
Description |
double getAcceleration() |
Returns the acceleration of the train in meters / sec2. |
double getAcceleration(AccelerationUnits units) |
Returns the acceleration of the train in specified acceleration units.
Parameter: |
double getDeceleration() |
Returns the deceleration of the train in meters / sec2. |
double getDeceleration(AccelerationUnits units) |
Returns the deceleration of the train in specified acceleration units.
Parameter: |
void setAcceleration(double acceleration) |
Sets the acceleration of the train in meters / sec2
(must be >0).
Parameter: |
void setAcceleration(double acceleration, AccelerationUnits units) |
Sets the acceleration of the train in specified units (must be >0).
Parameters: |
void setDeceleration(double deceleration) |
Sets the deceleration of the train in meters / sec2 (must be >0).
Parameter: |
void setDeceleration(double deceleration, AccelerationUnits units) |
Sets the deceleration of the train in specified units (must be >0).
Parameters: |
void accelerateTo(double speed) |
Accelerates or decelerates the train to achieve a given speed. Can only be called while the train is moving. Does not change the cruise speed. Uses the current settings for acceleration/deceleration. Deceleration to 0 (stop) cannot be done as stop
is controlled by
TrainMoveTo
block (use decelerate before finish option). Discards any acceleration/deceleration with the exception of the final deceleration before arrival to target.
Parameter: |
void accelerateTo(double speed, SpeedUnits units) |
Similar to
accelerateTo( double speed ). The given speed is specified not in meters per second, but in specified speed units.
Parameters: |
Function |
Description |
boolean isMoving() |
Tests if the train is currently moving. An empty train is considered as not moving. Returns true if moving, false if not. |
void pauseTrain() |
Causes the deceleration of the train (according to the specified deceleration settings) until its movement stops altogether. The train remains in the
TrainMoveTo
block. |
void resumeTrain() |
Causes the acceleration of the stopped train (according to the specified acceleration settings) until it reaches its cruise speed. |
boolean getDirection() |
Tests if the first car of the train is moving at the head of the train. Returns true if first car moves at the head of the train, otherwise false. |
boolean getOrientation(boolean front) |
Tests if the train has same orientation as the track where its given side is located. Returns
true
for same orientation,
false
for opposite.
Parameter: |
boolean isForwardOnTrack( boolean front ) |
Tests if the train is moving towards the end of the track on which its given side is located.
Parameter: |
Route getRoute() |
Returns the route the train is currently following, if any. The route only exists while the train is handled by the TrainMoveTo block. |
List<RailwayTrack> getAllOccupiedTracks() |
Returns all occupied railway tracks. |
RailwayTrack getTrack(boolean front) |
Returns the railway track where a given side of the train is currently located.
Parameter: |
RailwayTrack getTargetTrack() |
Returns the target track of a moving train, null if target is not set. |
double getOffset(boolean front) |
Returns the offset of a given side of the train relative to the track start point in meters. 0 is the beginning of the track.
Parameter: |
double getOffset(boolean front, LengthUnits units) |
Returns the offset of a given side of the train relative to the track start point in specified length units. 0 is the beginning of the track.
Parameters: |
double getTargetOffset() |
Returns the target offset (on the target track) of a moving train in meters, assumes the target is set. |
double getTargetOffset(LengthUnits units) |
Returns the target offset (on the target track) of a moving train in specified length units, assumes the target is set.
Parameter: |
double getDistanceToTarget() |
Returns distance from current position to target point in meters. Assumes the train is moving along a route (specified manually or calculated automatically) and the target is set. |
double getDistanceToTarget(LengthUnits units) |
Returns distance from current position to target point in specified length units. Assumes the train is moving along a route (specified manually or calculated automatically) and the target is set.
Parameter: |
double distanceToTrain(Agent train, boolean targetSide) |
Returns the distance (in meters) in the network from the head of the train to the specified side of the target train.
Parameters: |
double distanceToTrain(Agent train, boolean targetSide, |
Returns the distance (in the specified units) in the network from the head of the train to the specified side of the target train.
Parameters: |
double getDistanceDriven() |
Returns the distance driven by the train in meters since its creation or since the last call of resetDistanceDriven(). |
void resetDistanceDriven() |
Resets the distance driven by the train to zero. |
Function |
Description |
RailSettings getSettings() |
Returns the rail settings. |
RailwayNetwork getRailYard() |
Returns the rail yard where the train is currently in. If the train is empty returns null. |
void highlight(boolean yes) |
Highlights or dehighlights the train.
Parameter: |