TrainMoveTo

The only block that controls the train movement. A train can only move while inside a
TrainMoveTo
block.
The
train can move forward (first car in front) or backward. The train can
have a target position where it should get, or just move without a
target. In the latter case the train agent will exit TrainMoveTo either when
it leaves the rail yard via an open-ended track or if it hits another
train. The train can move without a pre-defined route, i.e. just follow
the current states of switches, or you can specify the route
explicitly, or you can ask TrainMoveTo to
calculate the route automatically from the current location to target.
You can optionally ask the train to accelerate to a given speed at the
beginning of movement and to decelerate to stop at the target.
If the train hits another train when moving, it stops and exits
TrainMoveTo
via
outHit
port. In all other cases (namely, when it reaches the specified target or leaves the yard) it exits via the
out
port.
A target is a point on a given track specified either as an offset from the track start in meters or graphically, with the
Position on Track
element intersecting the track. You can additionally tell
TrainMoveTo
to check if there are other rail cars on the target track and to adjust
the target point respectively so that the train stops exactly at the
first car on its way (available only if the route is specified). This
is useful when the train is going to be coupled with another train.
Please note that the check is performed only for the target track and
only at the time when the train enters the TrainMoveTo
block. If the situation on the target track changes while the train is moving, it will not notice it.
A
route can be specified explicitly as a sequence of tracks or calculated
automatically. If you choose to specify the route explicitly, you
should enter the track where the head of the train is located as the
first track, and then all other tracks the train should go by in the
correct order. If the target is specified, the target track must be the
last track in the sequence. To let TrainMoveTo
calculate the route automatically, you need to specify the target track.
TrainMoveTo
will only find straight routes, i.e. the ones without the need for
changing of movement direction. When moving with a route, the train
will control the switches on its way, namely, it will change a switch
state as needed when it approaches the switch. If a track on the
train's route becomes unavailable due to blocking or reservation when
the train is already on the way, the train can either stop at the last
available switch before the blocked track and wait until it becomes
unblocked or it can recalculate the route to exclude this track and
keep moving to the target.
Keep
in mind that while the Rail Library will detect the train collisions,
it does not take care of managing the train traffic, like making one
train to wait until another train passes a certain switch or track. The
higher-level traffic management may differ from one rail yard to
another and is something to be defined by the modeler.
To
enable the train to make decisions about acceleration or route while it
is moving, a continuous movement can be modeled by a sequence of
multiple TrainMoveTo
blocks, possibly with
SelectOutput
blocks in between. You can let the train keep its current speed between the two
TrainMoveTo
blocks by setting the
Finish option
of the first block to
Finish at current speed
and not to
Decelerate and stop. The second
TrainMoveTo
can then either
Continue at current speed
or
Accelerate/decelerate to the cruise speed.
You can specify the cruise speed specific for the movement defined by a particular instance of
TrainMoveTo,
otherwise the current cruise speed of the train will be used. Depending
on the length of the route and acceleration/deceleration values, the
train may not be able to achieve the cruise speed. The current (actual)
speed of the train can be obtained by calling the train
function
getSpeed().
While the train is moving under the control of
TrainMoveTo, you still can modify its speed or let it accelerate or decelerate by using the train API.
TrainMoveTo
offers a number of callback extension points where you can define the actions to be executed while the train is moving.
Parameters
- Direction
-
Defines in which direction should the train go:
Forward
– the first car of the train moves at the head.
Backward
– the last car of the train moves the head, and the first – at the tail.
Syntax:
boolean forward
Default value:
Forward(true)
- Route is
- Defines the routing options:
Not specified (train will follow switches)
– the train will move without a pre-defined route, i.e. just will follow the current states of switches. If the
Target is
parameter is set to
Not specified, at the end of the movement (when the train leaves the rail yard), the train will be removed from the system.
A given list of tracks
– the train will go along the route explicitly defined by you.
Calculated automatically from current to target track
– the route will be automatically calculated. The target track and
position must be specified if this option is selected.
Syntax:
RouteType routeType
Valid values: TrainMoveTo.ROUTE_NOT_SPECIFIED, TrainMoveTo.ROUTE_LIST_OF_TRACKS, TrainMoveTo.ROUTE_AUTO
- Route { Track1, Track2, …}
[dynamic]
- [Visible if
Route is
is set to
A given list of tracks]
The sequence of tracks. The track where the head of the train is
located must be the first track in the sequence, followed by all other
tracks the train should go by in correct order. If the target is
specified, the target track must be the last track in the sequence.
Value type:
RailwayTrack[]
Local variable:
train
- the train
- If the track gets blocked
- [Visible if
Route is
is set to
Calculated automatically from current to target track]
Here you can specify the behaviour of the train in case a track from
its current route becomes unavailable because of blocking or
reservation. The train can either Stop before this track, i.e. stop at the switch connected to the blocked track and wait until the track gets unblocked, or it can
Recalculate route.
Syntax:
BlockedTrackHandling BlockedTrackHandling
Valid values:
TrainMoveTo.STOP_AT_SWITCH,
TrainMoveTo.RECALCULATE_ROUTE
- Route should not contain
[dynamic]
- [Visible if
Route is
is set to
Calculated automatically from current to target track]
The list of tracks (it may contain one or several tracks) that are
forbidden to include in the automatically calculated route for the
train. Add the tracks in the list, or if you use the dynamic value
editor, put the list in curly brackets, e.g.: {railwayTrack1,
railwayTrack2}
Value type:
RailwayTrack[]
Local variable:
train
- the train.
- Target is
- Defines the target options:
Not specified
– the train will just move on until it either leaves the yard or hits another train. If the
Route is
parameter is set to
Not specified (train will follow switches), at the end of the movement (when the train leaves the rail yard), the train will be removed from the system.
A given position on track
– the train will finish at the intersection point of the target track and a given
Position on Track.
A given offset on a track
– the train will finish at a particular position on a given track; the
offset of the position is calculated from the start or the end of the
track.
Name:
targetType
Valid values:
TrainMoveTo.TARGET_NOT_SPECIFIED,
TrainMoveTo.TARGET_AT_POINT_ON_TRACK,
TrainMoveTo.TARGET_AT_TRACK_OFFSET
- Position on track
[dynamic]
- [Visible if
Target is
is set to
A given position on track] The
Position on Track
element defining the place to stop at. The element must have an intersection point with the target track.
Value type:
PositionOnTrack
Local variable:
train
- the train.
- Railway track
[dynamic]
- [Visible if
Target is
is set to
A given offset on a track] The target track where the train should finish.
Value type:
RailwayTrack
Local variable:
train
- the train
- Offset from
[dynamic]
- [Visible if
Target is:
A given offset on the track] Choose here where to count the offset from:
End of the track
or
Beginning of the track.
Value type:
boolean
Default value:
false
(End of the track)
Local variable:
train
– the train
- Offset on track
[dynamic]
- [Visible if
Target is
is set to
A given offset on a track] The offset of the finish position from the start or end point of the target track.
Value type:
double
Local variables:
train
- the train
double tracklength
– the full length of the target track
Default value:
tracklength
meters
- Check free space on target track
- [Visible if
Route is
is not set to
Not specified
and
Target is
is not set to
Not specified] If selected (true),
the train will check if there are other rail cars on the target track
and to adjust the target point respectively so that the train
stops exactly at the first car on its way. This is useful when the train
is going to be coupled with another train. The check is done only for
the target track and only at the time when the train enters the TrainMoveTo
block, so if the situation on the target track changes while the train is moving, it will not notice it.
Syntax:
boolean checkFreeSpaceOnTargetTrack
Default value:
false
- Limit distance to move
- [Visible if
Route is
is not set to
Not specified] If selected (true), the train will move no more than by the distance specified with the parameters below.
Syntax:
boolean limitDistance
Default value:
false
- Distance is
- [Visible if
Limit distance to move
is selected] Here you can choose how you want to limit distance the
train may move - by specifying the maximum distance (Traveled by train), or by specifying the distance from some particular switch (From switch to train tail).
Get value:
distanceIs
Valid values:
TrainMoveTo.DISTANCE_IS_TRAVELED_BY_TRAIN, TrainMoveTo.DISTANCE_IS_FROM_SWITCH_TO_TRAIN_TAIL
- Distance
[dynamic]
- [Visible if
Limit distance to move
is selected] Here you can specify the maximum movement distance for the
train - either from the current place, or from some particular switch,
depending on the value of the Distance is
parameter.
Value type:
double
Default value:
infinity
- Switch
[dynamic]
- [Visible if
Limit distance to move
is selected and
Distance is
set to
From switch to train tail] The switch shape. The train will be stopped when its tail will move for the distance specified in the
Distance
parameter from this particular switch.
Value type:
RailwaySwitch
Local variable:
train
- the train.
- Cruise speed (0 for no change)
[dynamic]
- Optional
new cruise speed for the train that will apply starting from this
movement. If 0 is specified, the current cruise speed setting will not
be changed.
Value type:
double
Local variable:
train
- the train.
Default value:
0
- Start options
- Defines what the train should do at the beginning of movement:
Continue at current speed
– just continue moving at the current speed (left from the previous
TrainMoveTo,
TrainSource, or set by calling
setSpeed()).
Accelerate/decelerate to cruise speed
– accelerate or decelerate from the current speed to the
Cruise speed (0 for no change).
Accelerate/decelerate if condition is true
– same as above, but only if a given condition is
true
Get value:
startOptions
Valid values:
TrainMoveTo.ACCELERATE_NO, TrainMoveTo.ACCELERATE_YES, TrainMoveTo.ACCELERATE_CONDITION
- Accelerate if
[dynamic]
- [Visible if
Start options
is set to
Accelerate/decelerate if condition is true]
The condition that is calculated at the time the train enters the block
to find out whether to apply acceleration/deceleration to cruise speed.
Value type:
boolean
Local variable:
train
- the train
- Finish options
- [Invisible if the
Route is:
Not specified (train will follow switches)
and the
Target is:
any of the options or when the
Route is:
any of the options and the
Target is:
Not specified] It defines what the train should do at the end of movement:
Finish at current speed
– do nothing, just finish at whatever speed it has gained.
Decelerate and stop
– try to decelerate to stop, which may not be possible because of the
route length, the current speed, and deceleration value.
Decelerate if condition is true
– same as above, but only if a given condition is
true.
If the finish options haven't been specified, the speed of the train will remain the same.
Get value:
finishOptions
Valid values:
TrainMoveTo.ACCELERATE_NO, TrainMoveTo.ACCELERATE_YES, TrainMoveTo.ACCELERATE_CONDITION
- Decelerate if
[dynamic]
- [Visible if
Finish options
is set to
Decelerate if condition is true]
The condition that is calculated at the time the train enters the block
to find out whether to apply deceleration to zero at the end of
movement.
Value type:
boolean
Local variable:
train
– the train
-
Actions
- On enter[code]
- Code executed when the train enters the block.
Local variable:
train
– the train
- On at switch
[code]
- Code
executed when the train approaches a switch. You can still change the
switch state here, but note that if the route is specified, the train
does this automatically.
Local variables:
train
– the train
RailwayTrack track
– the track before the switch
RailwaySwitch
sw
– the switch
- On enter track
[code]
- Code executed when the train is entering a new track.
Local variables:
train
– the train
RailwayTrack
track
– the new track
RailwaySwitch
sw
– the switch before the track
- On exit track
[code]
- Code executed when the train exits a track, i.e. when its tail leaves the track.
Local variables:
train
– the train
RailwayTrack
track
– the track that the train leaves
RailwaySwitch
sw
– the switch before the track
- On exit rail yard
[code]
- Code executed when the train exits the rail yard.
Local variables:
train
– the train
RailwayTrack
track
– the (open ended) track by which the train left the yard
- On exit[code]
- Code executed when the train leaves the block via the
out
port, which means the train has reached the target or left the yard.
Local variable:
train
– the train
- On exit (hit another train)
[code]
- Code executed when the train leaves the block via the
outHit
port, having touched another train.
Local variable:
train
– the train
- On remove
[code]
- Code executed when a train is intentionally removed from this block by calling the train's function
remove(). This code is automatically executed after the
remove()
function call.
Local variable:
train
– the train
Functions
int size()
- Returns the number of currently being moved by this block.
Agent getTrain( int index )
- Returns the train with a given index that is currently moving.
Ports
- in
-
The input port.
- out
-
The output port for trains that reach the target or leave the yard.
- outHit
-
The output port for trains that hit another train.