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 and Process 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 objects and must be disposed by TrainDispose objects. 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 objects. 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
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.
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: i
- the index
void setCruiseSpeed(
double speed ) -
Sets the cruise speed of the
train (must be >0) in meters per second.
Parameter: speed
- the new cruise speed of the train in meters/second
void setCruiseSpeed(
double speed, SpeedUnits units
) - Sets the cruise speed of the
train (must be >0) in specified speed units.
Parameter: speed
- the new cruise speed of the train in specified speed units
units
- one of speed
unit constants
double getCruiseSpeed() -
Returns the cruise speed of the train in specified speed units.
Parameter: units
- one of speed
unit constants
double getCruiseSpeed( SpeedUnits units ) - Returns the cruise speed of the train in meters/second.
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: units
- one of speed
unit constants
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.
Parameter: v
- the new speed in meters / second
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.
Parameters: v
- the new speed value in the specified units
units
- one of speed
unit constants
void
setAcceleration(
double acceleration ) - Sets the acceleration of the
train in meters / sec^{2} (must be
>0).
Parameter: acceleration
- the new acceleration of the train in meters / sec^{2}
void
setAcceleration(
double acceleration, AccelerationUnits units ) - Sets the
acceleration of the
train in specified units (must be >0).
Parameters: acceleration
- the new acceleration of the train in specified units^{
}
units
- one of acceleration
unit constants
double getAcceleration() - Returns the acceleration of the train in meters / sec^{2}.
double
getAcceleration(AccelerationUnits units) -
Returns the acceleration of
the train in specified acceleration units.
Parameter: units
- one of acceleration
unit constants
void
setDeceleration(
double deceleration ) - Sets the deceleration of
the train in meters / sec^{2 }(must be >0).
Parameter: deceleration
- the new deceleration of the train in meters / sec^{2}
void
setDeceleration(
double deceleration, AccelerationUnits units
) - Sets the deceleration of
the train in specified units (must be >0).
Parameters: deceleration
- the new deceleration of the train in specified units^{
}
units
- one of acceleration
unit constants
double getDeceleration() - Returns the deceleration of the train in meters / sec^{2}.
double
getDeceleration(AccelerationUnits units) -
Returns the deceleration of
the train iin specified acceleration units.
Parameter: units
- one of acceleration
unit constants
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
object (use decelerate before finish option). Discards any
acceleration/deceleration with the exception of the final deceleration
before arrival to target.
Parameter: speed
- the new desired speed in meters / second
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: speed
- the new desired speed in specified speed units
units
- one of speed
unit constants
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.
boolean isMoving()
- Tests if the
train is currently moving. An empty train is considered as not moving.
Returns true if
moving, false if not
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.
RailwayTrack getTrack( boolean front ) - Returns the railway track where a given side of the train is currently located.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: front
- if true, this is
front side, otherwise
rear side
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: front
- if true, this is
front side, otherwise
rear side
units
- one of length
unit constants
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: front
- if true, the
location of front of the
train (open side of the first car), otherwise - of the back
boolean
isForwardOnTrack( boolean front ) -
Tests if the train is moving towards the end of the track on which its
given side is located.
Parameter: front
- if true, the front
of the train (open
side of the first car), otherwise - the back
RailwayTrack getTargetTrack() -
Returns the target track of a moving train, null
if target is not set.
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: units
- one of length
unit constants
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: units
- one of length
unit constants
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.
Miscellaneous
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: yes
- true for
highlighted status, false
for regular