Dev:Guide on modelling of rollingstock circulations in railML 3
This guide is to explain how rollingstock circulations are modelled in railML 3. This was introduced with implementation of the use case LTCP. For more information on the use case "Long term circulation planning" (LTCP) please see the UC:TT:LongTermCirculationPlanning Use Case Specification. As described below the data structures introduced with LTCP can also be used to describe circulation plans for specific time periods. However, if further requirements are raised for modelling of short term circulations, these should be collected in another use case, e.g. UC:TT:AdoptVehicleWorkingSchedulingToTimetableChanges.
Definition and Requirements
Train rostering describes a sequence of train runs or tasks (maintenance, refueling, etc.), which a vehicle / group of vehicles has to perform.
A rostering plan focuses on a vehicle "class" (a group of similar vehicles) and includes multiple "instances" (individual units within the class). It assigns a specific vehicle class to cover a set of train runs. Once calculated, the plan determines how many instances are needed and outlines the train runs each vehicle instance must complete.
‘Long-term’ means: typically covers train runs of one representative week of the timetable. Special or limited services due to holidays or construction works are usually not considered. However, the data structures also support circulation plans for specific time periods of any duration.
The modelling supports open and closed (circular) rostering plans. Closed rostering plans can be repeated indefinitely, as they have no “final” task, each task has one or more follow-up tasks. They are not bound to a specific time period. Open rostering plans cannot be repeated – they contain one or more tasks without follow-up task. Their validity is typically defined by a specific start and end date.
Basic concept
A rostering plan in general can be interpreted as a sequence of tasks/train runs that a vehicle must complete within a certain period of time:
Example of sequential rostering plan. Provided by railML.org e.V. partner iRFP (link to the railML® website)
Since the sequences of tasks and train runs are often identical on a given day, it is possible to combine equal sequences into one. This way, the linear sequence of tasks can be transformed into a graph/network.:
Example of condensed rostering plan in the form of a network/graph. Provided by railML.org e.V. partner iRFP (link to the railML® website)
This network structure is the base of the rostering plan model in railML 3.
Elements of the rostering plan model in railML 3
Blocks
<TT:block>s represent one train run or task (maintenance, refuelling, etc.) that must be carried out by one vehicle instance of the rostering plan. It is mainly defined by its start and end times and one or two locations (for train runs between two stations). These can either be
- inherited from a referenced <TT:operationalTrainSectionPart> in case of an already defined train run or
- explicitly specified in the element itself, in case of a task or train run, that is not defined within the document.
Block connections
<TT:blockConnection>s define the sequential order of <TT:block>s. Since one block in a rostering plan may have different successors depending on the operating day, a block connection can include more than one relation between one start block and all of its successors. Block connections indirectly express whether two connected tasks can be carried on the same day after each other or if the second block must be carried out on the next day. Each relation between two blocks within a block connection is annotated with a reference to its <TT:validities:validity>.
Vehicle rostering
The <TT:vehicleRostering> element serves as a container for all <TT:block>s and <TT:blockConnection>s belonging to one rostering plan. Block connections shall not connect blocks of different <TT:vehicleRostering>s. Its scope is one vehicle or one vehicle group of a constant vehicle class.
Commented code example
Introduction of the rostering plan example
Simple (closed) rostering plan Monday-Friday. Provided by railML.org e.V. partner iRFP (link to the railML® website)
The example shows a simple (closed) rostering plan consisting of two train runs ("Train 101" and "Train 102") and a service task ("Cleaning") that takes place during standstill of the vehicle.
From Monday to Thursday, "Train 102" follows immediately after "Train 101". On Fridays, an additional cleaning task is carried out between these two train runs.
After train run "Train 102", the vehicle continues again with "Train 101" on a later day. For the operating days Monday to Thursday, this is always the next weekday, i.e. "Train 102" on Monday is followed by "Train 101" on Tuesday, etc. In contrast to this, on Fridays there is a transition to the Monday-instance of "Train 101", as no train runs/services are scheduled for Saturday and Sunday in this timetable.
<vehicleRostering> element
The following XML example shows the basic structure of the <TT:vehicleRostering> element and its position within the railML® 3 XML tree.
<railML>
<timetable>
<vehicleRosterings>
<vehicleRostering id="vrg_1" depotRef="opp_A" formationRef="frm_1">
<blocks>
<!-- -->
</blocks>
<blockConnections>
<!-- -->
</blockConnections>
</vehicleRostering>
</vehicleRosterings>
</timetable>
</railML>
Each rostering plan is defined by its own <vehicleRostering> element. It contains the header data of the rostering plan and serves as a container element for the blocks and block connections.
The essential attribute of the vehicleRostering element is the formationRef, which references a <RS:formation> of the <RS:rollingstock> sub schema. This formation defines the vehicle class to which the rostering plan applies.
Optionally, an <IS:operationalPoint> of the <IS:functionalInfrastructure> can be referenced in the depotRef attribute in order to formally assign the rostering plan to a specific depot.
Blocks
Train runs or other services/tasks of a rostering plan are symbolised by the <TT:block> element. Seen from a technical perspektive, they are basically defined by their start/destination locations and their start/end times.
They come in two basic variants:
- Blocks with a reference to a <TT:operationalTrainSectionPart>: The relevant data of the block is implicitly inherited from the referenced train part. This is the normal case if the railML file contains <TT:operationalTrain>s and the rostering plan is linked to this train data.
- Blocks with explicitly specified start/destination locations and start/end times: These are used if there is no corresponding train data, especially for services at standstill, e.g. cleaning, refuelling, etc. However, it is also possible to use this block variant for moving tasks using the <TT:shunting> or the <TT:trainSketch> subelement.
In the example, two blocks with references to an <operationalTrainSectionPart> are used for the two train runs "Train 101" and "Train 102". Another block with explicitly specified start and end times is used for the cleaning service:
<blocks>
<block id="blk_101">
<trainSectionPartRef ref="tpt_101"/>
</block>
<block id="blk_102">
<trainSectionPartRef ref="tpt_102"/>
</block>
<block id="blk_cleaning">
<cleaning startTime="08:00:00" endTime="09:00:00">
<location opRef="opp_A" trackRef="trk_202"/>
</cleaning>
</block>
</blocks>
Optionally, the location of the cleaning service can be specified referencing an <IS:operationalPoint> and a <IS:track>.
Block connections
<TT:blockConnection>s link one initial <TT:block> with one or more follow-up blocks depending on the operating day. The initial block is referenced with the blockRef attribute.
The follow-up blocks are defined using the subsequent <TT:successor> element. This provides a reference to a <TT:validities:validity> to define on which operating days these blocks are linked together. These validities always refer to the start time of the initial block. It contains also the dayOffset attribute, which is used to indicate different starting days of the two linked blocks.
Starting with the block "Train 101" of the example there are connections to the block "Train 102" (Monday to Thursday) and to the cleaning task (Friday). Since all follow-up blocks can be carried out on the same day after the initial block, the dayOffset is equal to 0.
<blockConnections>
<blockConnection blockRef="blk_101">
<successor blockRef="blk_102" validityRef="vld_Mon-Thu" dayOffset="0"/>
<successor blockRef="blk_cleaning" validityRef="vld_Fri" dayOffset="0"/>
</blockConnection>
<!-- -->
<blockConnections/>
The block connections starting from the cleaning task is quite simple: There is only one successor and again both connected blocks are planned to start on the same operating day:
<blockConnections>
<!-- -->
<blockConnection blockRef="blk_cleaning">
<successor blockRef="blk_102" validityRef="vld_Fri" dayOffset="0"/>
</blockConnection>
<!-- -->
<blockConnections/>
The graphical representation of the rostering plan shows only one connection starting from block "Train 102" (back to "Train 101"), but it has to be taken into account, that there is a difference in length of time between block "Train 102" and block "Train 101" depending on the validity of block "Train 102":
<blockConnections>
<!-- -->
<blockConnection blockRef="blk_102">
<successor blockRef="blk_101" validityRef="vld_Mon-Thu" dayOffset="1"/>
<successor blockRef="blk_101" validityRef="vld_Fri" dayOffset="3"/>
</blockConnection>
<blockConnections/>
On operating days "Monday-Thursday" block "Train 102" continues directly to block "Train 101" of the next weekday, i.e. from Monday to Tuesday, from Tuesday to Wednesday, etc. So the dayOffset here is equal to 1.
Since there are no train runs on Saturday/Sunday, the block "Train 102" on Fridays can not be continued with block "Train 101" on Saturday. Instead, it is not scheduled for 3 days until the next Monday. This is indicated by the deviating second <TT:successor> element with the dayOffset of 3.