NXWarrants

An NXWarrant 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 NXWarrant

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.

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. The mouse clicks move successively through the Block Name fields of the Create eNtry/eXit Warrant window. 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, 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 be 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 NXWarrant.

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.

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. Lastly, there are some options for running. An NXWarrant 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. The buttons at the bottom are:

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 warrant's block synchronization adjusts the elapsed times so event time are relative to the entry of the 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 NXWarrants to make them Permanently Saved

If you press the Edit button on the Warrant List Table of the NXwarrant while it is still executing, the Create/Edit Warrant Window for the NXWarrant will open. Press the Copy button. After providing a name for the copy press Save to make a permanent warrant that can be edited later.

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 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

Setting Layout Scale of your layout should is needed so conversion to scale speeds is correct.

The default search depth (Max. Number of Blocks in Route) as mentioned above when looking for routes can be set next.

The value of the Throttle Setting/Speed Factor is used when no speed profile is available.

Ramp Step time increment and Ramp Step Throttle Increment regulate the smoothness and prototypical look of speed changes. For locos with no momentum, short times and smaller throttle increments make smoother ramps. For locomotives/consists with lots of momentum, longer periods should be used. Note: The throttle increment for one step of a 128 step throttle is 0.00794. The defaults are set for a modest amount of momentum, i.e. perhaps less than prototype but visually OK. Observe how trains behave starting up and stopping with NXWarrants and adjust accordingly.