Advanced Trains

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== ARS (Automatic RouteSetting) ======

ARS, short for Automatic RouteSetting, is a system of rules for to accept/deny trains for certain actions. True to the name, it is used for automatically setting routes on signals. Additionally, it is used for deciding whether to stop trains at a [[usage:lines:stoprail|Station/Stop Rail]].

===== About Line Numbers and Routing Codes =====
See the article [[usage:using_stock:train_fields]] for info about these properties.

In case you're unfamiliar with Line Numbers and Routing Codes: You may recall the Line and Routingcode fields from the Onboard Computer, available from any driver's seat in the train. You've probably already used the text fields for text displayed inside and out of the train. Well, that information is for passengers, whereas Line and Routing Code are for the ARS system (and others, like Basic ATC, but this article is about ARS).

//Please note that Line Numbers and Routing Codes are case-sensitive, so RC FREIGHT is different from RC Freight.//

When ARS tries to match a rule for a Line Number, it will look for an exact match of the entire Line Number field.  

When ARS tries to match a rule for a Routing Code, it will look for that routing code anywhere in the whole routing code field of the train for a partial match.

You can set all the train properties such as Line Number and Routing Code (plus the texts) automatically with [[usage:atlatc:start|LuaATC]]; this is how you would change the LN at the end of the line if you're using different LNs for each direction of service or alternating short-run and full-run (many algorithms are possible with LuaATC after all).

===== The ARS Syntax =====
ARS rules are written with a text syntax into two important textboxes: The Route Editor on signals, and the "Trains stopping here (ARS Rules)" box on Station/Stop "rails" (tracks). ARS Rules for a signal will allow a route to be set automatically, while ARS rules for Station/Stop tracks will decide whether the train is going to stop at that station.

ARS rules are parsed from the input textboxes and placed into data structures inside Advtrains. If your ARS rules didn't parse, they don't get added. When the formspec is next shown, only the valid rules that successfully saved get added.

The syntax is straightforward. There are four types of rules: Line Number rules, Routing Code Rules, Train Length rules and the * rule. There is also the comment, which is any line that starts with a #, so you can write notes in your ARS rule list. Each rule is on its own line. Here's a valid LN rule, a comment, a valid RC rule, and one invalid line written out:
<code>
 LN 1
 # For operator Boris trains
 RC BorisDepot
 E
</code>

Invalid lines, which cannot be parsed as ARS rules, will be automatically converted to comments with a question mark prepended. For example, the E above will become "# ? E". When this happens, you made a syntax error.

There is also ! operator for negation of the rule, applicable only the LN and RC rules (there's no ''!*'' rule). If you start a line with a !, it only matches trains that do NOT have that LN or RC. Here's the rules for a passenger stop that doesn't allow trains with RC FREIGHT.
<code>
!RC FREIGHT
</code>

==== Train Length rules ====

This feature has been newly introduced in 2.7.0.

Train length rules match a train based on its length in meters (nodes). Such rules can for example be used to prevent routing trains into a siding that are too long for it, or to set different stop positions for short and long trains.

Train length is specified as a pair of minimum and maximum separated by a '-'. A single number specifies just the minimum (open end)

<code>
TL 0-6
# Matches trains up to 6m length
TL 6-12
# Matches trains between 6m and 12m
TL 12
# Matches trains 12m or longer
</code>

Fractional values are not supported.

===== Manage your RCs and LNs =====
The RC FREIGHT convention is used on LinuxForks server to identify freight trains to prevent them stopping at passenger stations.

It is incumbent on railway operators and network owners to manage LNs and RCs properly and make their meanings clear. Line Numbers may end up not being globally unique*, but it does not matter unless the systems using them are located nearby and may end up sharing tracks. Some RCs may be specific to junctions, telling the train which way to go at that specific point; others may separate types of traffic like passengers and freight; still others might identify that a train is out of service, or headed to the nearest depot available. Use what conventions and management makes sense to you.

*but station codes on the Station/Stop track need to be; thankfully there is an owner system for those that was introduced to stop people just putting anything in that overlaps and overwriting other peoples' station names unless you have ''train_admin'' (I digress, that's a topic for another wiki edit or forum post).

===== Multi ARS / Load Balancing =====

This feature has been newly introduced in 2.6.0.

ARS rules can now include a priority number. Specifying a priority for a rule enables the Multi-ARS mode. If the ARS rules of multiple routes match a given train (and all of these rules have a priority set), then all the matching routes will be requested simultaneously, and the first one that can be set without conflicts is being set.

Example:
<code>
Route 1 has rule:
  2 RC abc
Route 2 has rule:
  1 RC abc
</code>
The number (here 1 or 2) in the beginning is the priority, it can be any positive whole number. A train with routingcode abc will match both of these routes.

The signal will now attempt to set Route 2, and if unsuccessful Route 1. Route 2 is tried first because its priority number is smaller (it's like a ranking - 1st, 2nd, 3rd etc). If none of the routes can be set, the signal waits until any of them becomes available (just like in the single-route case) and set it.

Multi-ARS also works with the default route:
<code>
Route 1 has rule:
  RC def
Route 2 has rule:
  1 *
Route 3 has rule:
  2 *
</code>

Trains with routingcode def will go to Route 1. Any other train will go to either Route 2 or Route 3, whichever is available first.

Priorities are useless for station/stop rails and have no effect there.

===== Logical And =====

ARS rules normally are or-combined, that is, any of the rules need to match the train. However sometimes two or more conditions need to be fulfilled.

Consider this example for a stop rail:
  * only passenger trains should stop (freight trains have RC FREIGHT)
  * Line 2 trains should not stop, because they are an express service

Below rules are wrong:
<code>
!RC FREIGHT
!LN 2
</code>
This is because a line 2 train, although it doesn't match the "!LN 2" rule, nevertheless is not a freight train so it matches the !RC FREIGHT rule and stops anyway. The other way round, freight trains will also stop because they are not of line 2.

The correct rules are:
<code>
!RC FREIGHT
& !LN 2
</code>
The & symbol on the second line indicates that both conditions need to be fulfilled for the rule to match. Now only trains that are not freight trains AND are not of line 2 will stop.

Regarding the syntax, note that the & !LN 2 part must be on a new line. Also, there cannot be comments between a rule and its attached & clauses. This is a limitation of the ARS rule parser.

Conditions can also be attached to the default route this way, although this is probably only needed in special situations and should be avoided:
<code>
*
& !LN 2
</code>
A route marked like this will be used for any train that doesn't match explicit rules, EXCEPT if its line is 2.

===== Precedence in route selection =====

Rules are considered in this order:
  * Explicit rules: a rule of the form LN x, RC x, !LN x or !RC x (and its following & clauses) matches the train
  - The first matching route, if any rule has no priority
  - All matching routes (Multi-ARS), if all matching rules have a priority (in order of that priority)
  * Default routes: if none of the explicit rules matched, the routes set as default routes (*) (except if the following & clauses did not match the train)
  - The (only) default route, if there is a default route without priority
  - All default routes, if multiple exist and all of them have priority set

Rules without priority always take precendence over rules with priority. For simplicity, avoid mixing rules with and without priority.