JMRI: Warrant Speeds Help
Author: Pete Cressman
Keywords: JMRI help Modifying Warrant Speeds

# Warrants: When Warrant Speeds Are Modified

Regardless of the throttle setting and intended track speed in the command script of a Warrant, track conditions may occur that require a restriction of the track speed. "Stop" aspects of signals, occupancy or allocation to another Warrant will deny permission to proceed. Other aspects of signals or block limits may require a reduction of speed. For an overview discussion of Warrants, see Warrants.

## Warrants and Speed Restrictions

A train running under a Warrant must be aware of track conditions ahead. Signals may indicate reduced speed or permission to return to normal speed. Blocks may impose yard limit speed restrictions. Rogue trains may show up unexpectedly in the route. In our imagination, we can presume their detection means our warrant "engineer" sees a fuss. For each of these cases the warrant must look ahead, detect the need for a speed change and schedule the right time to do it - all the while making the change smoothly and completing it in prototypical fashion.

### Configuring Speed Restrictions

For a warrant to detect a signaled speed change the signal must be configured in the Occupancy Block Tables. The Signal Table there configures the entrance Portal to the OBlock that the signal protects. The warrant then uses the signal system configured for the signal to define the aspect speed.
Likewise, Block Speeds are configured in the Occupancy Block Tables. A column in the OBlock Table allows you to choose an aspect speed that the Warrant will enforce before entering the block.

When an occupancy sensor is activated ahead of the train on its route, the warrant will take note of it and bring the train to a stop before entering the block.

Finally, you can manually instruct the Warrant to ramp down to a stop using the Halt control command. - or issue an emergency stop with the E-Stop command, Also, you can ramp up from a stop and resume the train's former speed with a Resume command. With the exception of E-Stop, all these unscripted speed changes are made smoothly.

When a warrant ramps down a speed change due to a signal, block or rouge occupancy condition, That speed change remains in effect until the condition is removed. At that time the speed is ramped up to the previous "normal" speed. The precedence order is: rouge occupancy, signal aspect, block speed.

## How Signal Aspects and Block Speeds Modify a Train's Speed

When a speed restriction is required before entering a block, the speed change needs to begin at some point before entry.

When a Warrant is running and its train enters a block, it looks ahead to see if any speed changes are coming up. The look ahead distance must be adequate for the train to be able to stop should that be needed. The warrant calculates the look ahead distance to be what is needed to stop from its present speed. This distance may include several blocks. If a signal or block is encountered within this look ahead distance, and the aspect protecting the block indicates the speed must be restricted, then the warrant performs a "ramp down".

When a speed restriction is lifted, the problem is much simpler. The warrant can immediately begin a "ramp up" upon entering the block.

### A Note about Ramps

When a warrant ramps up or down, it does it stepwise. In order for it to done smoothly in prototypical fashion, it depends on the following parameters:

- Ramp Step Time The number of milliseconds between making throttle setting changes.
- Ramp Step Throttle Increment The initial throttle increment when increasing speed, or last increment when decreasing speed.

These are configured in Warrant Preferences. See Warrant Preferences for information about configuration of Warrant parameters.

### Parameters Needed for Look Ahead

Both the look ahead distance and the time when to begin the speed change require knowing the track speed. Thus to get the train to begin and end its speed changes at the proper points, and relating the throttle settings to the actual track speed, some crucial information is needed. Without such information a fast running engine may overrun the point where a speed change expects to be completed, or a slow running train may stop too far short of where it is expected.

- Distance the train must travel. Your wild guess is better than any default. Block Lengths are needed for distances. There is a length column in the OBlock Table. (Use menu Add Items -> Occupancy Blocks). Also the Paths column in the table opens its path tables. Each Path Table has a length column as well.

  Likewise the menus Circuit Builder -> Add/Edit Circuit OBlock and Circuit Builder -> Add/Edit Circuit OPaths in Circuit Builder have text fields to enter lengths.

  Inches or centimeters may be used for all of these fields.

  When no block length is specified error messages are written to the console and you may have trains over-running their stopping points. It is highly recommended that path lengths be specified. If the paths within a block vary widely, path lengths should be set. Otherwise, path lengths are inherited from the block length.

- Layout Scale is needed for distances when speed is expressed as Mph or Kmph. This is set from a drop down box at the Edit->Preferences->Warrants menu of the main PanelPro window
- Track Speed of the train. A correlation of the throttle settings to the actual speed of the train on the layout must be known. For this two methods are used.
  - A first approximation is the "Throttle Setting/Speed Factor" value at Edit->Preferences->Warrants. When used, this factor is a linear multiplier to relate throttle setting to track speed. Note this is a global value for all of the locomotives in your fleet and over the entire speed range of each. Obviously this may not function optimally. However, it could be satisfactory for your tastes.
  - For more precision a Speed Profile can be used for each locomotive. These provide track speed values that give more accurate calculations for time and distances. The Speed Profiler is found at Roster->Speed Profiling is used to create a speed profilr for each locomotive or consist.

### Getting Speed Profiles for your Trains

Speed Profiles are maintained in the Roster and there is a tool that will create them at Roster->Speed Profiling The tool can measure a track speed for each step in the throttle. However, interpolation and extrapolation have been implemented so it is not necessary to go to such detail. Five or six data points well distributed over the throttle's range is quite sufficient.

## Automatic Speed Profiling

Since Release 4.9.2 track speed of an engine/consist is measured when that address is used for running a Warrant. A data point is recorded whenever a path with known length is traversed with a known throttle setting. The data is kept for the layout session and when the session ends this Session Speed Profile can be merged into the Roster Speed Profile. Warrant Preferences provides choices for how you may want to manage the merging of Roster Speed Profiles. See Warrant Preferences for how you want to manage the end of session behavior. The default is you are prompted for how you want to treat each Session Speed Profile.

### Track Speeds for Throttle Settings

If you used the Roster Speed Profiling tool most likely you ran an engine running light over a straight level track. With Warrant dynamic speed profiling, measurements are made over straight level track, but also upgrade, down grade, curved gently or severely, running light or pulling 30+ cars. The track speeds are not going to be all the same for a given throttle setting. When merging, new values are averaged with the old, with the intention of a composite speed profile that reflects average use.

At some point, merging this data may make a speed profile that is not monotonic increasing. (Certainly increasing throttle setting increases speed). When this anomaly occurs the speed profile is displayed and the cells where the profile is not monotonic are marked in red. You may edit the table to correct it. Whether to do this editing is your choice. Perhaps it is best to let the anomalies remain and have the profile resolve itself - or do the editing after letting more values accumulate. Of course, a value resulting when the train was shorted or was dragging a derailed car should be deleted.

#### Editing a Speed Profile

When given the opportunity to edit, either the value of a single cell can be changed or an entire row deleted. Replacing a value with 0.0, causes that speed step to be ignored. When a track speed is needed for a throttle setting there, an interpolated value is used. If values in both directions are 0.0, the row might as well be deleted.

## Aspect Speed Table and its Interpretation

Speeds are named in the aspects.xml files that signal masts use in the Signal Mast System. These speed names are also used in the Blocks tables. To control train speed, values must be assigned to these speed names. The Aspect Speed Map found at >Edit->Preferences->Warrants provides a value for each named speed. It is up to the user to assign a value to the name and a meaning to the value. On the Warrant Preferences Pane are four radio buttons to assign meaning to the values entered into the Speed Map Table.

When a signal or block defines an aspect speed by name, the warrant looks up the name in the Aspect Speed Table and uses the value there tp modify the speed of the train.

- Percent of Normal - The value is a percentage of the recorded ("Normal") speed. Any speed name that is restrictive must have a values less than 100. The warrant reduces the "Normal" scripted speed by this value as a percentage.
- Percent of Full Throttle - The value is an absolute throttle setting expressed as a percentage of full throttle. All speed names must be a number between 0 and 100. The warrant sets the modified speed to be the value as a percentage of the full throttle setting.
- Miles per hour - The value is the scale speed expressed as miles per hour. All speed names must be expressed as miles per hour. The warrant, using layout scale, converts the value to track speed and finds the corresponding throttle setting for the modified speed.
- Kilometers per Hour - The value is the scale speed expressed as Kilometers per hour. All speed names must be expressed as kilometers per hour. The warrant, using layout scale, converts the value to track speed and finds the corresponding throttle setting for the modified speed.

To sum up; if you are not fussy about being prototypical and always want to see speed change when signals are passed, use "Percent of Normal". If you have calibrated a sufficient Speed Profile for each of your engines you can use either of the last two speed interpretations which express throttle setting in terms of scale speed.

### The Signal Head Appearance Table

If signal heads are used on the layout, their appearances can be mapped to the speed names of signal masts in this table on the Warrant Preferences pane. For the above, the warrant maps appearance name to speed name to value.

One use of this is to use Virtual Signal Heads to dynamically influence the behavior of warrants. The appearance of these Signal Heads can be set either by panel icons or Logix. Since there are 8 possible Signal Head appearances, additional speed names can be created so a unique speed can be made for each appearance.

### Editing the Speed Map Table

Rows can be added or deleted. The default speed map has the names "Fifty" and "Sixty". These names only appear in signal mast systems for UP-2008 and BNSF-1996, so they can safely be deleted if you do use these signal systems. You only need but must have all the speed names that appear in the signal system you have configured for your layout.

If you add a new speed name for a signal head appearance, then add a row for that name in the Signal Map Table.

## Block Speed Names

A speed name can be set for each Block by selecting a name from the Speed Notch column of the OBlock Table. One use of this feature could be to enforce a yard limit speed. Unlike signal speed names, block speed names are bi-directional. NOTE: To return a Warrant's speed to normal when leaving a yard limit, the speed names of the OBlocks on either side of the yard block should set to "Normal". Use care when combining this feature with signals to avoid providing conflicting speed change messages.

To unset an OBlock speed name, choose the blank setting from the Speed Limit column. As with the absence of a signal, when there is no speed name the Warrant continues at its current speed.

Back to Warrants Help.