Train

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

To create a custom train type

  1. Open the Rail Library palette and drag the Train Type element onto the agent type diagram, e.g. Main.

  2. The New agent wizard window will open. Specify The name of new type. Click Next to proceed to the next step.

  3. Here you can define the parameters of the train type. Click < add new... > and specify the parameter name, type and default value. To remove a parameter from the list, click the button . You can always add more parameters onto the train diagram after you finish creating it.

  4. Click Finish. AnyLogic will automatically open new train type diagram with the defined parameters. 

  5. Now you can use the new train type in the Rail Library blocks parameters, for instance, in TrainSource properties:

Functions

Rail cars

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: ithe index

Speed

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 speedSpeedUnits 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

Acceleration and deceleration

void setAcceleration( double acceleration ) - Sets the acceleration of the train in meters / sec2 (must be >0).
        Parameter: acceleration - the new acceleration of the train in meters / sec2

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 / sec2.

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 / sec2 (must be >0).
        Parameter: deceleration - the new deceleration of the train in meters / sec2

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 / sec2.

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

Movement control

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.
        Parameter: front - if true, the location of front of the train (open side of the first car), otherwise - of the back

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