Warrants: NX Warrants

An NX Warrant is a computer generated Warrant. Rather than recording speed changes and other locomotive commands from a throttle where the recording notes the elapsed time between commands, an algorithm generates the speed changes and elapsed times for a smooth start up and slow down to a stop. To review information about Warrants see About Warrants.
In is necessary to know the Block Path lengths and the engine's speed characteristics in order to determine correct time and position for where the speed changes should occur. A speed profile for the selected engine/consist to provide track speeds is desirable. Lacking a speed profile, the Throttle Factor and Layout Scale are used for a rough estimate of track speed. If block lengths are not specified, you will be prompted to provide a length. When Warrant Speeds Are Modified profides more details about how Warrants modify recorded speeds.

Launching an NX Warrant

After selecting the menu item Create NX Warrant from the Warrants menu of the Control Panel Editor, or by clicking on the Create NX Warrant button in the Warrant List window, the Create eNtry/eXit Warrant window is displayed:

Warrants Preferences pane in in JMRI 4.10

Set the Route

First establish the route for the train by entering OBlocks in the following fields:

Blocks are chosen either by typing in the block name or dragging it from a displayed OBlock table (use the OBlock Pick List button). The origin and destination blocks can also be chosen by clicking on track icons that represent these OBlocks. To use this feature your panel must have your layout depicted by Indicator Track Icons placed there by Circuit Builder.

To specify a Warrant route by mouse clicks, simply click on a track icon on your Control Panel. The mouse clicks move successively through the Block Name fields of the Create eNtry/eXit Warrant pane. If you mis-clicked on an icon and/or want to change the block in one of the fields, just double-click the field and click on another icon.
Note that the icons must be Indicator Track Icons to have this feature. Creating and Editing Warrants also discusses choosing routes.

The Max Number of Blocks in Route field puts an upper limit on the length of the route the algorithm computes. If your layout contains loops, then an infinite number of routes can theoretically be counted. To minimize computation time, you need not use a number that is much larger than the number of blocks in the longest route. However, using too small a number can terminate the search prematurely before the route is found.

Pressing the Calculate button runs a computer algorithm to determine all the intermediate blocks and paths to make the route. If more than one route meets the criterion, you are presented with a list to review and select the route you want. Note, the Via and Avoid location fields may be used to restrict the list. Possibly you will be presented with a dialog stating that no route could be found. You can view a tree of all the possible searches the algorithm used to find the route. Typical errors are the Portals of the selected paths are mismatched for exit and entry. Also check that the paths have the needed portals for exit and entry.

Once the route has been chosen, the window changes to show choices for the running parameters of the NX Warrant:
Warrants Preferences pane in in JMRI 4.10

Set the Run Parameters

The required fields are Address and Max Throttle Setting. All the others are optional or have defaults.

Note, when editing a Indicator Track Icon (Edit Indicator Track popup.) there is a Display Train Name when occupied check box in the edit dialog. When checked the icon will display the Train Name field entered above.

The View Speed Profile button displays a table of the track speeds that will be used in the calculations for the Warrant. The table is comprised of the Roster Speed Profile merged with any speed measurements that have been made during the current session. If the table is empty, the values for Throttle Factor and Layout Scale in Warrant Preferences are used in the calculations. (Note, this was the only way it was done prior to Release 4.9.2.)

Next set values for the maximum speed the train should achieve when track conditions are at a Clear aspect.

NXWarrants ramp up and ramp down the train speed in increments to provide a prototypical appearance when leaving the Origin block and ending in the Destination block. The parameters for the increments to use are set by the Ramp Step Time and Ramp Step Throttle fields.

Next, set the direction of travel. It is important to set this correctly because the throttle commands will correspond to track conditions. Be ready to issue an Abort command from Warrant List Table if this occurs.

On the right is a list of some options to consider for running the warrant.

An NX Warrant can be issued for a manual operator. Here the route is allocated but no throttle commands are issued. The operator must acquire the throttle and drive the train.

At the bottom of the pane are three buttons:

The Script Algorithm

The NX Warrant script sets the direction, turns the light on, blows two horn/whistle blasts and starts to ramp up speed. There should be a reasonable estimate for block length know for each OBlock. If the length of the route is not known, you will be prompted to enter a length for the path through the block. The algorithm will ramp up to the maximum speed and ramp down to a stop in the last block. After stopping in the last block, the script blows one horn/whistle blast and turns off the light.

For a series of short blocks the length needed to ramp up or ramp down is distributed over as many blocks as are needed. For short routes, the algorithm may decide the maximum speed cannot be achieved without over-running the last block. In this case, the max throttle setting is modified so ramp up and ramp down can finish without over-running the last block.

The elapsed times to traverse each block is computed from what is known about the engine's speed profile and the length of the path in each block. Note! if the route includes a Dark block, i.e. no occupancy detection, it is important it's block length is known since in this case, synchronization cannot be done.

Saving NX Warrants to make them Permanent

When the Run NX Warrant button is pressed and the NXWarrant starts its run, the warrant is listed in the Warrant List table with the name NX(address). If the table is not visible, it will be displayed. Notice that the Edit button label for the warrant is Save.

If you press this button before the warrant completes, a Create/Edit Warrant Window for the NX Warrant will open. This window has a copy of the NXWarrant. After providing a name and any other information you want changed, press the Save button to make a permanent warrant.

Some Tips for Smooth Start Up and Slow Down

It is necessary to have a length specified for each path in a block. A rough estimate within 5% of the actual length is adequate. Each path inherits the length specified for the block, so it is only important to input a separate length for a path when its length is significantly less than the block length. Lengths can be set for OBlocks and for individual paths within a block in the CircuitBuilder Edit Path menu or in the OBlock tables.

The algorithm calculates the speed changes using the the step intervals for time and throttle setting specified in Warrant Preferences. These are the values that give a prototypical look when changing speeds for signal aspects and starting and stopping. The Warrants pane at Edit->Preferences->Warrants is where this and other Warrant parameters can be set.

Warrants Preferences pane in in JMRI 4.10

Warrant Preferences

From the general JMRI Preferences, select the Warrants tab and check the options set for: