TrainSource


TrainSource is the object that starts any railway process flow.

It generates trains, places them on one of the tracks  in the rail yard and injects the train into the train process flowchart. 

You can set the object not to place created trains on a track of the rail yard (this behavior is controlled with the After creation parameter). It is commonly used when you need to pass the train agent to the regular process flowchart where it can go through delays, queues, decisions, etc. and place it on a track of the rail yard later on (using TrainEnter object).

Train "arrival times", i.e. the times when new trains appear in the model can be set up similarly to the Source object in the Process Modeling Library (an in fact, Source is used inside the TrainSource). Arrivals can defined by interarrival times or by arrival schedule. In addition, there is a "manual mode" when TrainSource would create a train only when its inject() function is called. Just like in Source, you can limit the number of arrivals.

How-To video: Setting up a freight train

A new train should contain at least one rail car. You can tell TrainSource to use your own rail car type. The same applies for the train.

You can assign custom 2D or 3D animation shapes to the cars and perform any additional setup for each car, for example, set up a custom length, in the Car setup field. Please note that the size of rail car custom animation will not be automatically adjusted to the length of the rail car, so you need to choose the proper scale of the animation shape so that there are no spaces between cars in the train and cars are not drawn one above the other.

A new train is placed on a track, and you should make sure there is a free space on that track for all cars (at the creation time a train should be fully located on a single track). You need to specify the offset of the first car on the track and orientation of the train relative to the track. A train has its first car (the one that has been created first) and the last car. In the train API "front" always means the first car.

The train cruise speed and acceleration/deceleration, are also defined in the TrainSource object but can be modified later via the train API. The speed of the train is at this time set to its cruise speed, so that, if needed, the train can start immediately at the cruise speed.

Parameters

[Note that in the descriptions below RC refers to the type specified by the user in the New rail car field. In the similar way, T refers to the type specified by the user in the New train field.] 
Arrivals defined by
Specifies the mode of train generation:
Interarrival time - the time between two subsequent trains is defined by the specified expression.
Arrival table in Database - trains are generated according to the records in the specified database table. You specify the table below in the Database table parameter, then select the table column containing the arrival moments in the Arrival date drop-down list. The block will generate one train per each data record in the specified table.
Arrival schedule – trains are generated at exact times defined in the arrival schedule.
Manual (call inject() method) - trains are not generated automatically and are only generated on calls of inject() method.
Get value: arrivalType
Set new value dynamically: set_arrivalType( new value )
Valid valuesInterarrival time - Source.INTERARRIVAL_TIME
                     Arrival table in Database - Source.DATABASE_ARRIVAL_TABLE
                     Arrival schedule - Source.ARRIVAL_SCHEDULE
                     Manual (call inject() method) -  Source.MANUAL
Interarrival time [dynamic]
[Visible if Arrivals defined by is set to Interarrival time] Expression used to evaluate the time interval between the two subsequent trains.
Value type: double
Default value: 10 minutes
Arrival schedule
[Visible if Arrivals defined by is set to Arrival schedule] The name of the Schedule object with integer value type containing times of train arrivals. Typically, the value column would contain "1" as one train is generated at a time. 
Syntax: Schedule<Integer> arrivalSchedule
Limited number of arrivals 
If the option is selected (true), the number of arrivals will be limited to Maximum number of arrivals.
Syntax: boolean limitArrivals
Default value: false
Maximum number of arrivals 
[Visible when the Limited number of arrivals is selected] The maximum number of arrivals to be generated by this object.
Syntax: int maxArrivals
Default value: 1000
Database table
[Visible if Arrivals defined by: Arrival table in Database] Choose here the database table containing the data on agent arrivals.
Arrival date
[Visible if Arrivals defined by: Arrival table in Database] Choose here the column of the Database table that contains the agent arrival timestamps.
# of cars (including loco) [dynamic]
The number of cars in the train. Must be 1 or more.
Value type: int
Default value: 11
After creation 
Defines what to be done with the created train. There are two options available:
Put the train in a rail yard - The train will be put into the specified rail yard (in this case you specify the rail yard, the track, offset and orientation on the track using the parameters given below).
Leave as a logical agent (will use TrainEnter later on) - The train will not be placed on the track of the rail yard by this object. This option is commonly used when you need to pass the train agent to the regular process flowchart where it can go through delays, queues, decisions, etc. and place it on a track of the rail yard later on (using TrainEnter object).
Syntax: boolean putInRailYard
Default value: Put the train in a rail yard (true)
Entry point defined as
[Visible if After creation is set to Put the train in a rail yard] Here you can choose how you will define the position on track where new trains will be placed.
There are two alternative options:
Position on track - Define the point graphically with specific space markup element Position on track.
Offset on the track - Define the point as the distance from the start or end point of the track to the front side of the first car of the train, in meters. You specify the offset in the parameter Offset of 1st car, see below.
Name: locationType
Position on track [dynamic]  
[Visible if After creation is set to Put the train in a rail yard and Entry point defined as Position on track] Here you should choose the Position on track element defining the point of the track where new trains will be placed.
Value type: PositionOnTrack
Local variable: T train – the train
Railway track [dynamic]  
[Visible if After creation is set to Put the train in a rail yard and Entry point defined as is set to Offset on the track, m.] The railway track where the newly created train will be placed (all cars should be fully located on a single track).
Value type: RailwayTrack
Local variable: T train – the train
Offset from [dynamic]
[Visible if Entry point defined as Offset on the track] Choose here where to count the offset from: the end of the track or from the beginning of the track.
Value type: boolean
Default value: false (from the end of the track)
Local variable: T train – the train
Offset of 1st car [dynamic]
[Visible if After creation is set to Put the train in a rail yard and Entry point defined as Offset on the track] The distance from the start or end point of the track to the front side of the first car of the train.
Type: double
Default value: tracklength - 10
Local variables: double tracklength – the length of the track
             T train – the train
Orientation on track [dynamic]
[Visible if After creation is set to Put the train in a rail yard] Defines the orientation of the train relative to the track:
Forward (first car is closer to the end of the track) – the train orientation is the same as the track
Backward (first car is closer to the beginning) – opposite orientation
Syntax: boolean orientation
Default value: Forward (first car is closer to the end of the track) - true
Local variable: T train – the train
Train and cars
New train [dynamic]
The train type created by this TrainSource. (This type should have the option that it is used in flowcharts as train.)
Value type: Agent
Cruise speed [dynamic]
The cruise speed of the train. This cruise speed will be used as default but you can change it later on via the train API or in the TrainMoveTo object. The speed of the train will be also set to the cruise speed at the time the train exits TrainSource – as if it has just been moving with cruise speed. Therefore if the next object in the flowchart is TrainMoveTo, the train will be able to start immediately at cruise speed and will not need any acceleration.
Value type: double
Default value: 20 meters per second
Local variable: T train – the train
Acceleration [dynamic]
The acceleration of the train. When you request the train to accelerate to a desired speed, the speed will be growing by acceleration value each second. The acceleration can be changed later on via the train API.
Value type: double
Default value: 1 meters/seconds2
Local variable: T train – the train
Deceleration [dynamic]
The deceleration of the train. When you request the train to decelerate to a desired speed, or to stop, the speed will be reducing by deceleration value each time unit. The deceleration can be changed later on via the train API.
Value type: double
Default value: 2 meters/seconds2
Local variable: T train – the train
Add trains to
Here you specify where the trains created by this block will be stored: in the default population of root agent, or in some custom population (specified below in the Train population property).
Syntax: boolean addTrainToCustomPopulation
Default value: Default population of root agent (false)
Train population [dynamic]
[Visible if Add trains to is set to Custom population] The name of the agent population where the rail cars created by this block will be stored.
Value type: AgentList<? super T>
Local variable: T agent – the agent
New rail car [dynamic]
The type of the rail cars created by this block. Should evaluate to an object of rail car type. You can provide different construction codes for different cars by using the local variable carindex, for example: carindex == 0 ? new MyLocomotive() : new MyHopper()
Value type: Agent
Local variables: T train - the train
             int carindex - the index of the car that is being created, starting from 0
Car length [dynamic]
The expression returning the car length.
Value type: double
Local variables: T train – the train
                          RC car – the rail car being set up,
                          int carindex - index of the car that is being set up, starting from 0,
Car setup [code]
The code that is executed for each car where you can perform additional rail car setup. You can set up the car animation shapes, initialize custom statistics, etc. Use the local variable carindex to distinguish between the cars, for example: car.setWidth( carindex == 0 ? 3.5 : 4 ).
Local variables: T train – the train
                          RC car – the rail car being set up,
                          int carindex - index of the car that is being set up, starting from 0.
Add rail cars to
Here you specify where the rail cars created by this block will be stored: in the default population of root agent, or in some custom population (specified below in the Population property). The default population (Java collection of type AgentList<Agent> ) contained in the top-level agent can be accessed with the function getDefaultPopulation().
Syntax: boolean addCarToCustomPopulation
Car population [dynamic]
[Visible if Add rail cars to is set to Custom population] The name of the agent population where the rail cars created by this block will be stored.
Value type: AgentList
Local variable: RC agent – the agent
Actions
On exit [code]
Code executed when the train exits the object.
Local variable: T train – the train

Functions

void inject() - Generates a new train immediately (at the time of call). The train will be set up according to the TrainSource parameters settings. Is typically used when Arrivals defined by parameter is set to Manual.

long count() - Returns the number of trains exited this TrainSource.

Ports

out

The output port.