Edit Superelevation Rule File
Edits an existing superelevation
rule file. When a rules file is opened with this tool it validates the file
against the schema.
You can access this tool from the following:
Superelevation Rule File
The superelevation calculator uses an XML-formatted rules file to calculate various aspects of superelevation. This file is used to calculate Max E rate for each curve of an alignment and the transition lengths needed to rotate the road bed from normal crown cross slopes to full superelevation cross slope (Max E).
The sections that follow describe:
- How the Superelevation Rules File is Applied During Calculation of Superelevation
- How the Edit Superelevation Rules File Command Works
- Writing Equations in the Rules File
- Example Equations
How the Superelevation Rules File is Applied During Calculation of Superelevation
The Max E Rate is calculated by one of two possible methods, a Rate Table or a Rate Equation.
If Rate Table is used, then the Design Speed is populated by looking at which rate tables exist in the Rule File.
If a user selects a Rate Equation, then the Design Speed selection is populated with the Speed elements that are in the Speeds collection under the equation. Speeds don't have to be simple numerical values. For example, a Rule file can be defined with speeds of "60 Urban", "Loop Ramp", or "All Speeds". Alphanumeric "speed" names can be useful when the Rate Equation determines the actual speed from another source such as a User Variable.
Transition calculations are also computed by one of two possible methods, a Transition Table or a Transition Equation.
If a Table defining transition lengths is used, then there must be a Transition Table defined for each possible speed (numeric or alphanumeric). Transition Equations may or may not use speed as a variable.
If the user is going to use Speed Tables for Transition calculations, then there must be a Transition Table defined for each possible speed. Transition Equations may or may not use speed as a variable.
Once the Max E Rate and Transition selections are made any runtime User Variables that are defined in the rules file are displayed in a pop-up dialog allowing the user to make changes to any/all of these values.
The code will calculate Max E Rate, Transition Length and station location of superelevation key points (Normal Crown, Zero Crown, Reverse Crown, and Full Super) for each curve.
Next, the code checks to see if the rules file has any custom key definitions. If so, it processes these. Custom key stations can replace any of the standard superelevation key points or add additional custom key stations such as at the 1% cross slope.
Once any key stations have been adjusted, the code will look for Transition Overlaps between reverse curves or back to back curves. If any of the superelevation definitions overlap or are less than the defined minimum separation distance, additional adjustments are made to the calculated stations as defined by the Transition Overlap Adjustments options.
Lastly, the superelevation values are copied from outside lane(s) to the rest of the lanes.
IMPORTANT NOTE: You can get a detailed superelevation report by selecting the SuperelevationCalculation.xsl report style sheet.
How the Edit Superelevation Rules File Command Works
The Edit Superelevation Rules File command is used to edit the XML rules file. While the XML file can be edited directly, it is recommended to make all edits through this interface to ensure proper formatting of the XML data. The editor will also validate a rule file against the proper XML schema and equation syntax when an existing rule file is opened.
The Create/Edit Superelevation Rules file dialog opens to a mostly blank definition that is not yet saved to an XML file. The name of the current XML file is shown in the dialog title. Prior to saving a file, this reports as Untitled.xml. We said mostly blank because the default dialog does come pre-loaded with the AASHTO Method 5 Rate Equation and AASHTO Relative Gradient Transition Length Equation. You can choose to keep and use these or delete them.
There are seven sections in the dialog. Each, along with its settings, are discussed below.
- General
Length - describes the units that the user is working in.</p>
Station rounding - A value of 0 defines no rounding. If a non-zero value exists, all calculated station values will be rounded to this value. For instance, if the value is 0.2, then a station of 10+23.48 will be rounded to 10+23.4.
Cross slope rounding - A value of 0 defines no rounding. If a non-zero value exists, all cross slope values will be rounded to this value. For instance, a value of 0.01 will round the cross slope of 2.3456% to 2.35%.
Create by corridor settings - These are optional settings that define the default methods that are used when creating superelevation with the Create Superelevation Sections tool by selecting a corridor. These default methods are automatically used, and the user is not prompted for any selections when using this workflow.
- Tables
Rate and Transition lookup tables are shown in this section. These tables are most commonly imported from existing SUP or SEP files. They can also be created and edited through the interface if necessary.
Rate tables define maximum cross slopes for different curve radii. A single rate table can have multiple radii/cross slope lookup tables each based on a different Design Speed.
Transition tables define transition lengths for different maximum cross slopes. A single transition table can have multiple eMax/transition length lookup tables each based on a different number of rotated lanes.
-
Equations
Equations are an alternative and more powerful way to determine eMax and Transition Lengths than are lookup tables. Virtually any equation can be written to calculate these values using constant values, lookup tables, variables from the software, and variables users can define at runtime. This provide a great deal of flexibility how eMax and Transition Lengths can be computed.
An equation calculates and returns the maximum cross slope for a curve in double precision format (e.g. 0.03 is returned and represents 3%) or a transition length in double precision format (e.g. 127.92).
The AASHTO Method 5 Rate Equation and AASHTO relative gradient Transition Equations are included by default as
examples.
For information on writing equations. See the <xref>Writing Equations in the Rules File</xref> topic.
-
Runout and Transition Options
These settings control how the values for eMax and Transitions are calculated. They are, typically set as a standard in the Rule file but can also be exposed to a user by a User Variable if it is desirable to change one or more of these values at run time.
- Runout Options, Fixed Length - when disabled, the runout length is calculated using the same gradient as the runoff section. When enabled, a fixed length runout length can be specified. If a more complex option is needed for to calculate the Runout, use Custom Key Stations.
- Transition Type -
Defines how the cross slope is transitioned to achieve the full superelevation
cross slope. The types describe the path of the outside point of a
superelevation lane plotted on a superelevation diagram.
Linear - no transition at vertices, all segments are straight.
Parabolic - creates a parabolic transition at each vertex. The length of the parabola is determined by the shorter of the values of non-linear Curve Length parameter and the shortest adjacent line segment.
Reverse Parabolic - fits a reverse parabola between the Normal Crown point and the Full Super point (the entire transition).
Reverse Biquadratic - same as Reverse Parabolic, but different equation.
Reverse Cubic - same as Reverse Parabolic, but different equation.
Reverse Parabolic Nonsymmetrical 1 - like Reverse Parabolic, but the length of the sag parabola is 45 and the length of the crest parabola is 55. Alternate parabola lengths can be defined using the configuration variables CIVIL_SUPER_REVERSE_PARABOLIC_NONSYMMETRICAL_1_SAG and CIVIL_SUPER_REVERSE_PARABOLIC_NONSYMMETRICAL_1_CREST.
Reverse Parabolic Nonsymmetrical 2 - like Reverse Parabolic, but the length of the sag parabola is 30 and the length of the crest parabola is 40. Alternate parabola lengths can be defined using the configuration variables CIVIL_SUPER_REVERSE_PARABOLIC_NONSYMMETRICAL_2_SAG and CIVIL_SUPER_REVERSE_PARABOLIC_NONSYMMETRICAL_2_CREST.
Reverse Parabolic Symmetrical - This symmetrical option utilizes the parabolic transition with no tangent and the length of each parabola is one-half the transition length.
- Non-Linear Curve Length - defines the maximum length of a parabolic transition.
- Percent on Tangent - Percentage of transition length that is not on the curve.
- Use Spiral Length - If enabled and a spiral exists, the spiral length will be used as the transition length rather than the calculated transition length. In this situation, the Percent on Tangent value will be ignored. If disabled, the calculated transition length will be used.
- Start Inside Lane Rotation with Outside - If enabled, the inside lanes will start rotating (early start) at the same location that the outer lane starts rotating, rather than starting at the point of reverse crown. If disable, the inside lanes start rotating where the outer lane reaches reverse crown. In other words, when the inside and outside lanes are planer or have the same cross slope.
- Lengths are Total Transition - If enabled, the transition length is from normal crown to full super (runoff + runout lengths). If disabled, the transition length is from level or zero crown to full super (runout length).
- Interpolate Tables - If enabled, then all e Rate and Transition Tables will be interpolated. Otherwise e Rate and Transition lengths will be the higher value.
- Curve Overlap Adjustments
These options define how superelevation stations are adjusted when the exit transition from one curve overlaps the entry transition for the next curve.
If multiple options (Slide, Shorten, etcetera) are defined for a curve type (reverse curve or curve curve), the one with smallest Minimum Transition Gap that is larger than the actual gap will be used. For example, if the actual gap is 0, and one option has an Minimum Transition Gap of 50, and another has an Minimum Transition Gap of 100, the one with an Minimum Transition Gap of 50 will be used.
- Curve Type - Type of curves that the adjustments defined on the remainder of the dialog relate to. There are two sets of adjustments; one for Reverse Curve and one for Curve Curve situations.
- Minimum Transition Gap - any actual gap between Normal Crown stations less than this amount will cause this option to be invoked (except for cases of multiple options as described above).
- Slide - the entire transition for each curve will be moved more into each curve until the Minimum Transition Gap is achieved. The Transition lengths are maintained.
- Shorten - the Full super points are maintained, and the transitions are shortened until the Minimum Transition Gap is achieved. The shortening is proportional to the transition lengths.
- Reverse Crown - (Curve Curve Adjustment Option only) - the road will transition planar down to reverse crown and then back up to full super. The Zero Crown and Normal Crown stations are eliminated.
- Planar - the road will transition planar from Full Super to Full Super. The Zero Crown and Normal Crown stations are eliminated.
- Custom custom equations can be defined to calculate the transitions between curves. For information on writing equations. See the Writing Equations in the Rules File below.
- Custom Key Stations
Custom Key Stations are either overrides of the standard transition stations calculated for superelevation, or they are additional stations to be added to the lane(s).
An existing superelevation key station can be cleared or voided by setting the equation for the respective variable type to FALSE.
Note: Equations for custom key stations are written for curve entry (NC - FS). Curve exit transition calculations are automatically mirrored.- Create Custom Key Station Equations - When enabled, custom key stations can be defined.
- Description - A description of what these custom key stations are for.
- Criteria - A logical expression that must evaluate to True for the Custom Key Stations to be calculated. A blank value does evaluate to True.
- Stations - List of existing Custom Key Stations.
- Variables - Opens the Equation Editor which is used to define new variables and equations. See the Writing Equations in the Rules File topic.
- New - Defines a new
Custom Key Station.
Equation - Equation defining the location of the new custom key station. This equation can use Global (built in) variables and local variables which are the results of equations defined in the Equation Editor. For example, a new transition length from full super to reverse crown could be calculated using a custom equation. Assume that result is stored in the variable named ReverseCrownLength. Then the equation defining the Zero Cross Slope key station would be FullSuperStation - ReverseCrownLength. FullSuperStation is a Global variable defined by the software. See the Writing Equations in the Rules File below.
Type - Defines the type of key station being defined. If the type of the key station is one of the standard types (Normal Crown, Zero Cross Slope, Reverse Crown, or Full Super), then it replaces the standard key station. If the type is Custom, then a new key station is added to the lane.
- Runtime Variables
Runtime Variables are variables whose values can be set by the user at runtime. The reason for these variables are to allow agencies to lock the rules files so they cannot be edited, but still allow the user limited access to change values or control the calculations during the process of superelevation creation.
Runtime variables can override the Runout or Transition options or define new values that can be used in other equations.
- Name - Name of the new variable.
- Description - Description of the new variable.
- Override - Defines how the variable is used. None is a custom variable is defined that can be used in eMax and Transition Lengths equations. The other options are used to override Runout or Transition settings. These include Interpolate Tables, Percent Transition on Tangent, Use Spiral Lengths, Lengths Are Total Transition, Transition Type, Non-Linear Curve Length, Start Inside Rotation with Outside, Runout Is Fixed Length, and Runout Length.
- Type - Defines the
type of custom variable.
Strings - presented to the users at run time as a key in field for free format input or as a combo box for selecting from a preset list.
Integers - presented to the users at run time as a key in field for free format input or as a combo box for selecting from a preset list. A minimum and maximum range can be defined.
Decimal - presented to the users at run time as a key in field (input will be validated). A minimum and maximum range can be defined.
Boolean - presented to the users at run time as a checkbox.
Default Value - the default(starting) value for the variable.
- Importing SUP/SEP files
The Import SUP and Import SEP tools are an assistant when setting up XML Rule files. The import process will not import and define all settings from the legacy file, but it will import the bulk of the tables.
Import SUP will bring in the existing Rate Tables and Transition Length Tables. The remaining settings need to be configured manually.
Import SEP will bring in the existing Rate Tables, Transition Length Tables, and Relative Gradient Tables. It does not import Rate Equations or Transition Length Equations. The remaining settings need to be configured manually.
- Writing Equations in the
Rules File
Equations are developed in the Equation Editor.
- Name - Name of the Rate Equations or Transition Length Equations. This is the name that will appear in the interface for the user to select when calculating superelevation.
- Equation - Defines the final value that will be returned. If this is a Rate Equations or Transition Length Equations the value will be the eMax rate or Transition Length. If this equation is for a Curve Overlap Adjustment or Custom Key Station the final value can be any variable that may be used in another equation defining those respective values. It is recommended to set this Equation value to a single variable that is computed in the Equation Variables section of the dialog as shown below with the TransitionLength variable.
- Show Variables and Operators - expands the dialog to show available operators and variables. Global, Local (Equation), and Runtime (User) variable as all shown. These are defined in more detail below.
- Equation Variables - This section of the dialog box defines variables that ultimately are used to calculate the final value for this equation.
Equation variables are used to generate an intermediate value used in an equation(s). These variables are used in the equations in the rules file and cannot be changed by a user at run time.
Variables can be defined by an equation or a table but not both. If the variable is defined by an equation, the equation is written in the Equation field. In the example the variable TransitionLength is defined by the equation 100*(WidthLane*NRotatedLanes)*MaxE*bw/gradient. In this example WidthLane, NRotatedLanes and MaxE are global variable provided by the software. Gradient and bw are local variable defined in this dialog. The gradient variable is read from a table (notice the blank equation). Select the Create/Edit button to open the table.
The table has two columns for an Input and an Output value. The Output value is the value of the variable, in this case the gradient. What the Input column represents is defined by the Input Variable Name setting. In this example the global variable Speed is used. So, for each curve the Speed is found in the Input column and the corresponding gradient is returned.
If the input variable is a number, then the output value will be interpolated based on the Interpolation Type (useLowerBound, linearInterpolation, useUpperBound). Otherwise, the input variable value must match one of the table's input values exactly.
When writing equations, the following are types of variables available.
- Global Variables - defined by the system or calculated during processing. Different global variables are available depending what type of equations are being calculated as shown in the following table.
- Local (Equation) Variables - defined in the rules file. These variables are used in the equations in the rules file and cannot be changed by a user at run time.
- Runtime (User) Variables - defined in the rules file. These variables can be changed by the user at runtime.
This is a list of the global variables:
Maximum eRate
Transition Length
Custom Key Stations
Transition Overlap Options
Global Variables
X X Radius - radius of curve X X Speed - design speed X X X InitialCrossSlope - normal crown cross slope X X NRotatedLanes - the number of lanes rotated from the pivot X X PivotType - 0 - Crown, 1 - Inside, 2 - Outside, 3 - Left, 4 - Right, 5 - Divided Inside X X WidthLane - Average lane width X MaxE X TransitionLength - calculated transition length value X SpiralExists - "true" if spiral exists, otherwise false X StartOfSpiral - station of spiral start X SpiralLength - length of spiral X StartOfArc - station of arc(curve)start X NCRadius - radius at which E rate calculation is normal crown slope (maximum radius) X RunoutStation - calculated start of transition X RunoffStation - calculated zero cross slope location X ReverseCrownStation - calculated reverse crown station X FullSuperStation - calculated location of full super X OutLength - transition length exiting first curve X OutFullSuper - first curve full super station X OutRunoffStation - first curve zero cross slope location X OutRunoutStation - first curve normal crown location X InLength - transition length entering second curve X InRunoutStation -second curve normal crown location X InRunoffStation - second curve zero cross slope location X InFullSuperStation - second curve full super station X Curve1StartOfArc X Curve1EndOfArc X Curve1EndOfSpiral - "False" value indicates no spiral X Curve1FullSuperStation X Curve1ReverseCrownStation X Curve1ZeroCrossSlopeStation X Curve1NormalCrownStation X Curve1MaxE X Curve2StartOfArc X Curve2EndOfArc X Curve2StartOfSpiral - "False" value indicates no spiral X Curve2FullSuperStation X Curve2ReverseCrownStation X Curve2ZeroCrossSlopeStation X Curve2NormalCrownStation X Curve2MaxE When writing equations, a variety of math functions, operators, and logical expressions can be used.
- Math Operators: +, -, /, *, ^ - power operator, %
- Math Functions: ABS, ACOS, ASIN, ATAN, CEILING, COS, COSH, FLOOR, LOOKUP, LOG, LOG10, MAX, MIN, MOD, ROUND, SIGN, SIN, SINH, SQRT, TAN, TANH, TRUNCATE.
- Logical Operators: IF, AND, OR, NOT.
- Conditional Operators:
<, <=, =, ==, >=, >, <>.
Take care when working directly in the XML file because "<" and ">" are special characters and must be written as "<" and ">" in raw xml. When writing equations through the dialog it will do the conversion for you.
- Values: FALSE, INFINITY, PI, TRUE.
- Logical Expressions: IF(logical expression)? execute if true : execute if false For example: equation="if(altDel == 0.0 and AltSuper == 0.0) ? Delta : altDel" Logical expressions can also be nested, so another IF statement can be inside the true and/or false execution statement.
- Example Equations
This section includes a variety of equations that demonstrate proper formatting.
- This example shows some nested mathematical expressions. (frictionFactor - hPI) / (5729.58*((1/MinRadius) - (1/rPI)))
- This example shows a simple use of an IF statement. if(R < MinRadius ? MaxERate : if(R >= NCRadius ? InitialCrossSlope : (EFD - F)))
- This example shows a more complex nested IF statement where a variable named LaneWidthIndex is set by the user as a Runtime Variable is evaluated to determine which transition length lookup table will be used. if(LaneWidthIndex == 1) ? LengthAt45mWidth : (if(LaneWidthIndex == 2) ? LengthAt5mWidth : (if(LaneWidthIndex == 3) ? LengthAt55mWidth : (if(LaneWidthIndex == 4) ? LengthAt6mWidth : (if(LaneWidthIndex == 5) ? LengthAt65mWidth : (if(LaneWidthIndex == 6) ? LengthAt7mWidth : (if(LaneWidthIndex == 7) ? LengthAt75mWidth : (if(LaneWidthIndex == 8) ? LengthAt8mWidth : (if(LaneWidthIndex == 9) ? LengthAt85mWidth : (if(LaneWidthIndex == 10) ? LengthAt9mWidth : (if(LaneWidthIndex == 11) ? LengthAt95mWidth : (if(LaneWidthIndex == 12) ? LengthAt10mWidth : (if(LaneWidthIndex == 13) ? LengthAt12mWidth : 0))))))))))))
- This example shows rounding a value to the nearest integer. The Round function has two parameters, the first is the value or variable to be rounded and the second is the number of decimals to round to (0=integer such as 3, 1=tenth such as 3.4, 2=hundredth such as 3.47). For example, Round(WidthLane, 0) will round the value in the WidthLane variable to the nearest integer.
