The overall plan with the lines mod is to have a timetable scheduling system which is integrated with the other advtrains functions, especially the stop rails. This is the concept for it.

This is currently a draft, and subject to discussion before I will start implementing it. Please bring in your ideas, suggestions or criticisms. Just add them under the relevant headline and sign them with your name (use the “signature” button in the editor toolbar)

• All times used in the timetable are Railway times
• Timetables should support trains stopping at a station regularily (with arrival,departure and minimum stop time), trains passing through a location without stopping and trains stopping at a location only when the departure time is not due (e.g. for a freight train to let another scheduled train pass)
• Locations for the timetable are always Station/Stop rails (even if it's just a pass-through point)
• The system should be able to measure the travel times between stations, and the user should be able to create and update the timetable for a train semi-automatically from the travel times
• For every line in the timetable, it should be possible to deposit an xATC program (when xatc is ready)
• A system for guaranteed connections should be thought of (possibly aided by xATC)
• (later) Splitting and joining trains should be supported somehow
• The timetable system should export all data transparently to LuaATC and to something queriable from a plain Luacontroller, so that various kinds of departure displays can be built at stations

A timetable is a structure consisting of multiple “timetable items”. Every timetable item belongs to a Location and an optional Track code, and identifies one stop rail that the train should stop at or pass.

The timetable item holds:

• The station code of the station to which the item belongs
• (optional) a Track code, if defined a stop rail matches only when this is equal to the Track property
• (optional) the scheduled arrival time (not needed for pass-through places; maybe it is sufficient to compute this via the travel time)
• the scheduled departure time
• a “Stop Mode”, which is one of “regular stop”, “pass-through without stopping” or “wait for departure time or pass through” *
• (for regular stop) the minimum stop time. Train waits at least this time before continuing, even if it is late (for this, a global default could be defined)
• the travel time from the previous timetable item (that is, the time that the train needs to physically travel the distance between the two locations)
• some flags (such as “reverse here”)

* The stop modes should get better names — orwell 2021/04/19 22:11

All arrival and departure times in the timetable are relative to the initial departure time of any given train. That means, the timetable only defines after how many minutes/seconds after its initial departure at the first location it should be where.

Every timetable has an unique name and is saved globally.

In view of the timetable recording and travel time update functions, it would be good to implement it as follows:

• The arrival time is always auto-calculated from the travel time. In the Timetable Editor, the user can set the Arrival time, but this is implicitly translated to the difference from the previous departure on saving.
• The departure time is only saved if the user explicitly changed it, for example to provide a connection or to enforce a train order on a railway line. If not, it is auto-calculated from the arrival time and the stop time.
• When the user changes the timetable entry slots (especially the offset), the defined departure times should be adapted so that the absolute time they represent does not change, as far as this is possible, to not break the timetable at that particular station. How this is implemented in detail is left open for now.

When a timetable is assigned to a train, the train forms a Service of the line the timetable belongs to. The train then gets an instance of the timetable.

In the timetable instance, the relative times are replaced by the actual absolute railway times by adding them to the planned initial departure of the train. The lines in the timetable instance gain additional “computed properties”:

• The expected arrival time - calculated by adding the travel time to the expected departure time of the previous line
• The expected departure time - the scheduled departure time or the “ready time”, whichever is later

The “ready time” is determined from the expected arrival time. For a normal stop, this is the arrival + stop time, for “wait for departure” just the arrival time. When guaranteed connections are involved, they might affect the ready time too. For pass-through items, for which the departure time is only an orientation and the train never stops, there is no “ready time”.

At arrival and departure at every place, the expected arrival/departure times for this place become known and are saved, they are then called “actual departure/arrival time”. Every arrival and departure cause the subsequent expected arr/dep times to be recalculated.

This expected/real times system forms the base for departure displays both in trains and in stations.

This could use a better name — orwell 2021/04/19 22:11

At the first station in the timetable, trains “enter” the timetable and get timetable instances. For this, the timetable defines a service interval by means of two times:

• Interval: “every xx;xx”
• Offset: “plus xx;xx”

For example, interval 05;00 offset 02;00 would result in a train every 5 minutes at minutes 02,07,12,17…

—

• Hard-clip the modulo operation at cycle (hour) borders would highly simplify the slot enumeration (you could then be safe to say “Cycle 345 Slot 2” and it's always at the same minute.
• Maybe we can also allow for a list of mm;ss times in the hour so that 3/3/4 minutes rhythms would be possible

— orwell 2021-05-22 13:16

We call such a possible initial departure time a slot.

When a train arrives at the timetable entry point, it picks the next slot and constructs its timetable instance from it. If the first timetable item has a minimum stop time, this is taken into account too.

It may be considered whether to add a “late departure threshold”, say the train arrives a few seconds after a slot has passed, instead of waiting for the next slot, it departs at the previous slot and carries an initial delay then.

The system must ensure that each slot for each timetable has maximum 1 train using it. Slots may however be missed, in this case a departure display could display “train cancelled”. So, advtrains must somehow keep a mapping which train is assigned to which slot.

A train can enter a timetable in one of two ways: either as follow-up to another service (another timetable), or initiated.

Follow-up service:

• Train arrives at the terminus of a line
• The timetable says that the train should continue as <new timetable id>
• train switches to new timetable and finds next departure slot

For such a follow-up service, the end point of the old timetable should obviously be the same as the start point of the new one.

Initiated:

• Either the driver manually or luaatc code activates the timetable to the train
• The train behaves as if it had no timetable until it sees the stop rail associated with the first timetable item
• The train stops at the first timetable item and finds the next slot.

To save players the hassle of creating timetables by hand, there should be a Timetable Recording feature. Ideally, recording timetables should be straightforward when an automatic train line using stop rails is already present. Of course, the player can always alter the timetable after it is created.

Current automatic railway lines typically use stop rails to define places for trains to stop at. The timetable system will build upon this existing functionality for recording of the timetables, For example, the ARS rules in the stop rail determine whether a train will stop at any given stop rail; this can be directly translated to the stop mode in the timetable item. The correct routing of trains is already provided by ARS.

Recording the timetable relies on having an existing, working train line set up using stop rails

• The player boards a train and enters the “Record Timetable” mode
• The train stops at the next stop rail and takes this as timetable start point.
• The train proceeds along the line as it would under regular service on the line, and records all stop rails it encounters as timetable lines
  • For stop rails where the train should stop (told from the ARS rules in the stoprail), the Stop Time from the stoprail is saved in the timetable
  • For stoprails where the train should not stop, the timetable item is in “pass-through” mode
• How the recording process is ended is to be decided, the options are:
  • The player manually aborts the recording and the last recorded item is the end item
  • The player sets the station code of the final stop during or before starting the recording
  • Another option in the stop rail says “Trains terminate here”

The timetable recorded this way then reflects the departure and travel times of the current line setup. The player can then adapt the timetable and/or the timetable of other trains to fit together and provide connections (most adaptions will probably made in the initial departure time of other lines so that no jams occur)

Probably, at one point or another, the travel times (times between stations) in the timetables will not be accurate anymore. This can happen when a line is rerouted, when more trains are added to a railway line and trains progress slower in overall, when there was a jam during recording which has been resolved afterwards, or other cases.

To remedy this, the trains which are instances of any given timetable can be configured to constantly measure and average the travel times on their line. Using the timetable editor, players can choose to apply the measured travel times to the timetable. This action will then change the arrival times at items in the timetable.

As for altering the departure times, there is to consider:

• Commonly, the departure time is just the arrival time + stop time. Here, it would update along with the arrival time automatically
• It may be that the player has explicitly set the departure time, for example to ensure a train order or provide a connection to another train, then the time should not be updated automatically but instead left and flagged if it is now before the arrival time.

See also the notes on the timetable items in the section above.

The timetable system by itself does not interfere with the interlocking system in any way. ARS, in conjunction with the Line and Routingcode on the train, remains the primary way to route trains through the track network.

However, in conjunction with xatc, it may be useful to make departures dependent on certain conditions in the interlocking system that need to be met. A popular problem example is the deadlock situation that occured on LinuxForks with the S31 at Trisiston station when that service was initially inaugurated:

• S31 stops at a dedicated terminal platform at Trisiston
• The S31 line is single-track, the next station Elders Valley was some time away
• So, it was not feasible to program a route the whole way from Elders Valley into the terminal platform at Trisiston as this would hold back mainline trains unnecessarily. So, shortly before the mainline junction there was an entry signal
• But when a S31 train was at the Trisiston platform and another train went from Elders Valley towards Trisiston, a deadlock occured because the train at Trisiston could not leave.
• We solved that problem by adding a passing loop shortly before the station.

The solution using the timetable system would be to delay the train departure at Elders Valley until the platform at Trisiston is free. So, a “can_depart” xatc hook on the timetable would check whether the platform section at Trisiston is occupied by a train, and allow departure only after that train had left. This solves the problem on a higher layer than interlocking would, and this is how it's done in real life too (except that the dispatcher has the responsibility to tell the EV train or the EV signalman that it must wait).

The timetable system user interface will provide the following features:

• Viewing a timetable
• Editing a timetable
• Viewing a timetable instance of a train (along with real and estimated departure/arrival times)
• Viewing departures and arrivals at a station / a track in a station

For Timetable viewing/editing, the user should be able to select a slot (on a per-cycle basis with cycle-relative times), to get shown the real departure/arrival times instead of pure relative times, which can be confusing if the offset is not 0.

It would be nice to have a tabbed interface for the timetable UI: this way you could open multiple editors/viewers at once and quickly switch between them to validate the edits.

… to be continued …