Introduction > Design concepts

Design concepts
Cube Voyager is designed to be an integrated modeling system for transportation
planning applications. At the heart of the Cube Voyager system is a flexible control
language referred to as a scripting language. This provides a flexible environment and
grants control over all aspects of the modeling process.
The Cube Voyager system has four main assignment programs: Netwo rk , M atrix, Highway,
and Public Transpo rt . In addition, the system offers supplementary programs for common
transportation planning tasks, such as the Generatio n program for trip generation and the
Distributio n program for trip distribution. These supplementary programs provide an easy-
to-use interface to the basic four programs. Users may implement any model formulation
desired in the scripting language.
Cube Voyager has no hard coded mechanisms; users are free to change and modify
runs as they progress. Cube Voyager is an excellent choice for model applications
which require congestion feedback mechanisms.
Typically, transportation planning software is run as a series of independent programs,
any one of which could require a relatively large amount of input control data, and
consume a considerably large amount of computer resources. Some programs could
execute for hours, and operate most efficiently with large amounts of RAM. A user may
want to use Scenario Manager in Cube to run many scenarios which could require
running a large number of programs in successive order.
Cube Voyager is a library of programs that employ a language that allows the user to
write the script to provide instructions for performing all types of typical planning
operations. The script is stored in a file and then read when the system is executed. The
individual programs are activated according to the instructions in the script. Each
program is designed to perform certain operations, but only as specified by the user. A
typical application could involve a very complicated set of instructions, or can be as
simple as computing and/or printing a number from a file. It is the user’s responsibility to
design the process that is to be run.
The binary files generated by Cube Voyager are designed to reduce disk storage
requirements and reduce the amount of time spent on input/output. They have a
proprietary format that can not be used by other software, but they can be translated to
other formats by the user.
Introduction > Program features

Program features
Advanced features of the Cube Voyager software include:
• Integration with ESRI’s ArcGIS Engine allows reading and writing of supported file
structures directly to and from a personal geodatabase

• Full multirouting transit system

• Intersection and link constrained traffic assignments

• Flexible scripting language for model run specifications

• True 32-bit system designed for operating systems such as Windows XP & Windows 7.

• All calculations are performed in 64-bit floating-point arithmetic

• Seamless file format compatibility with existing transportation planning packages such as
TRANPLAN, MINUTP, TRIPS , TP+ and others.

• Database connectivity allowing data to be stored and edited in standard dBASE format

• Network calculator which can manipulate up to 10 network files concurrently

• Large problem sizes process efficiently (maximum zones=32,000, maximum

nodes=999,999, maximum links=999,999)

• Flexible matrix calculator with no practical limit on the number of matrices (999 internal
working matrices and up to 255 matrices on input and output files).

• Advanced plotting capabilities to create high quality plots for on-line printing or as plot file
images that can be plotted at a later time

• All data is stored as floating point values (a proprietary data compression scheme is
employed to save disk space)

• Capability to link with user-generated native code

Introduction > Minimum system requirements

Minimum system requirements

Cube Voyager requires a Windows XP, Windows Vista, Windows 7 or Windows 8
environment in which to function. The system utilizes RAM as needed; most
applications will not require any special RAM considerations. The exact amount of RAM
required can not be determined until an application actually runs and the combination of
user options is diagnosed. It is fairly safe to state that if a computer can run Windows, it
has enough RAM to run Cube Voyager.
About 10GB of disk space is required to install Cube Base and Cube Voyager. 100GB
or more may be required for model outputs. A typical application will require zonal data
files, networks, and matrices. Zonal data files are not very large, and network sizes will
depend upon the number of alternatives and variables that the user wishes to employ.
The largest networks will be only a few MB. The largest storage requirements will be
associated with matrices. A matrix will contain zones × zones cells of information. Each
cell value can be from 0 to 9 bytes in size, but Cube Voyager uses a proprietary data
compression technique that helps to reduce the sizes. The user can control the matrix
sizing.
Cube Voyager is designed to run in a multitasking environment. In such an environment,
there is a possibility that several simultaneous applications could try to access the same
data files simultaneously. This could possibly cause problems if one application is trying
to update a file while other applications are accessing it.
Getting Started > Installation

Installation
To install Cube Voyager, follow the steps outlined below:
• First, install the Citilabs license from the CD or download file.

• Once the license files are installed, Cube Voyager should automatically be selected during
the installation of Cube.

For more on installing Cube Base & licenses, see Chapter 2, “Getting Started,” in the
Cube Base Reference Guide.
Getting Started > Starting Cube Voyager

Starting Cube Voyager

This section describes various ways to start Cube Voyager:
• Starting Cube Voyager from Cube Base

• Starting Cube Voyager from Windows

• Starting Cube Voyager from the command prompt

Getting Started > Starting Cube Voyager > Starting Cube Voyager from Cube Base

Starting Cube Voyager from Cube Base

Cube Voyager is started from Cube when a model or standalone script is executed.
You may:
• Create a new Cube Voyager script, or open an existing one. Then, with the script open
in Cube Text Editor, select R un Curre nt File from the H o me ribbon tab. Voyager will launch
and directly run the script. For more on editing scripts, see Chapter 12, “Job Script Editor
Window,” in the Cube Base Reference Guide.

• Create a new Cube Voyager application or open an existing one. Then, with the
Application open, select R un from the H o me ribbon tab.

See Chapter 14, “Application Manager,” in the Cube Base Reference Guide for
general information on setting up an application in Application Manager. See
“Running an application in Application Manager” on page 767 of the Cube Base
Reference Guide and “Running a Cube Voyager, TP+, or TRIPS program” on
page 767 of the Cube Base Reference Guide for specific information on running a
Cube Voyager application or program from Cube.
• Create or open a Cube catalog in Scenario Manager. Then from the Ca ta lo g ribbon tab,
select R un .
When running an application or program in Cube from Application Manager,
Application Manager builds a task run file, and a full Cube Voyager script file of the
entire job, and sends the task run file to a program called Task M o nito r . Task Monitor is
also called from Scenario Manager. See Chapter 16, “Task Monitor,” in the Cube
Base Reference Guide for a detailed description of this program. Task Monitor sends
the Cube Voyager script file of the run to the Cube Voyager program to run and
monitors and display status information about the run as shown in the figure below.
Getting Started > Starting Cube Voyager > Starting Cube Voyager from Windows

Starting Cube Voyager from Windows

If Cube Voyager has been properly installed, it can be started from Windows Explorer:
• S ta rt > P ro g ra ms > Citila b s > Cub e V o y a g e r Mo d e ls a nd U tilitie s > Cub e V o y a g e r

• Alternately, S ta rt > R un , type or browse for VOYAGER.EXE (the default directory is

C:\Program Files\Citilabs\CubeVoyager), and click enter.

The Cube Voyager run monitor window will open and prompt the user for the following
data:
• The name of the s c rip t file that is to be run

• The wo rk ing d ire c to ry where the basic application data is stored. This is defaulted to the
directory where the job script file resides when a new job script file is selected.

• A p ro je c t p re fix (max of 4 characters)

• The desired he ig ht and wid th of a printed page

• A R un ID (character string) that will be printed at the top of every printed page

Cube Voyager has the following configuration options:

• Use either the B ro ws e or the Fa v o rite button to locate a job script file. Both buttons invoke an
Open File dialog box. The only difference is that the Browse button points to the current
directory, while the Favorite button points to the Windows Favorite directory. Users can
add frequently run job script files to the Favorite directory (using Windows Explorer) to
quickly locate them later in a Cube Voyager window, with the Favorite button.

• The E d it Inp ut File button can be used to open the current job script file in Cube for editing or
 running directly from Cube. See “Starting a model run” on page 708 of the Cube Base
Reference Guide.

• Click the H id e button to minimize this instance of Voyager to the Windows system tray
(instead of the Windows taskbar). This is useful when a script is executing, and the user
wishes to minimize window clutter.

• When this data is completed and the Start button is pressed, Cube Voyager begins
execution and the S ta rt and the Ca nc e l buttons become the P a us e and the A b o rt buttons,
respectively. The Pause button can be used to pause the execution, while the Abort button
allows for pre-mature termination of the execution.

• During execution, periodic messages will be written to the window. The window can be
minimized or left open as Cube Voyager is executing. When the application is finished, the
V ie w P rint File button can be pushed to view the resulting run print file.

• The N o tify W he n D o ne check box can be used to bring the Cube Voyager window back on
top when it’s done, if it has been minimized during execution. The default behavior is to
have the Cube Voyager window maintain its current status, minimized or maximized, after
the execution is completed.

• The Send Email When Done check box can be used to send an email to report on the run status at
the end of a run. When selected the following dialog box appears which allows the user to
provide the same information documented in the Cube Voyager SENDMAIL statement
under the Pilot program.

• The H id e S c rip t check box can be used to exclude the contents of the script from the Print
file.

• The W a it S ta rt button can be used to place this instance of Cube Voyager in wait mode for
use as a processing node for Cube Cluster. See Chapter 15, “Cube Cluster” for a detailed
description of this process.

• The A b o ut V o y a g e r button can be used to get License and maintenance information and the
version and date of all Cube Voyager programs as well as some standard machine
information as shown on the About Voyager dialog below.
Getting Started > Starting Cube Voyager > Starting Cube Voyager from the command prompt

Starting Cube Voyager from the command prompt

You can run Cube Voyager completely from the Windows Command Prompt (cmd.exe),
if such is available on your system. The path to VOYAGER.EXE should be added to the
PATH system variable, so that, it can be run from any working directories. The following
statement will initiate a Cube Voyager run from a command line with the appropriate
parameters and options:
Voyager.exe scriptfile [-Ppppp] [-PH:pageheight] [‑PW:pagewidth] [-Sworkdir]
[-Irunid] [/Start] [/StartTime:hhmm] [/EmailOn] [/NotifyOn] [/ViewPrint]
[/Hide] [/High] [/Wait] [/WinLeft:xx] [/WinTop:xx] [/WinWidth:xx]
[/WinHeight:xx]

Command line parameters:

• is the name of the file that contains the Cube Voyager script control statements. The
scriptfile
name may have a complete path in the typical operating system format. This file may be in
a different subdirectory than the -Spath argument. In some operating environments (such
as Windows), it may be necessary to provide a fully qualified file name (path\filename).

• pppp is a prefix (or project) that is pertinent to this application. Some files will always contain
these characters (maximum 4 characters) as part of their name. Most individual programs
will allow the prefix to be substituted directly for the ? character in their file names. The
characters must be those that are acceptable as part of filenames to the operating system,
and are not a Cube Voyager operator ('",+-*/&|). The program will generate a print file and
a var file with this prefix as its first characters. If the prefix is not designated, the program
will assign one based upon the following criteria:
If there is a pppp.PRJ file in the working subdirectory: the prefix will be set to the last
prefix in the file. If there is no pppp.PRJ, it will generate a file by that name. Warning:
Be sure that any pppp.PRJ file that Cube Voyager reads is a valid Cube Voyager
PRJ file.
The program automatically associates a unique sequence number with the prefix.
The pageht, pagewdth, and runid parameters can be reset dynamically by Cube
Voyager control statements within individual Cube Voyager programs. When set
within the individual programs, their effect may be valid for only that program.
• pagehtis the height (number of print lines) for a printed page of output. This will default to 58,
if the program can not find a height from the Cube Voyager PRJ file. The maximum value is
32767.

• is the maximum length a printed line can have. It may not be less than 72, nor
pagewdth
greater than 255. If it is not specified, and a width can not be found from the Cube Voyager
PRJ file, it will default to 132. Note that pagewdth will not cause longer length lines to be
truncated or folded; they will be written with the appropriate length. The primary use of
pagewdth is to assist in formatting messages and reports.
• workdiris the subdirectory that the application is to be run from. Normally, the user will log
onto the desired subdirectory, and workdir will not need to be specified. But, in some
operating environments, it may not be possible to log on to a subdirectory before starting
the program. (Windows may cause some problems in this area.) When the program starts,
it checks if workdir is specified, and if so, changes to that subdirectory before it processes
the other arguments (excluding filename).

• runid canbe used to specify a starting ID for the application. If ID is not specified, it will try to
obtain a starting ID from the Cube Voyager PRJ file with matching prefix.

Command line options:

• /Startfor example to auto start the run, also auto terminate when done unless /ViewPrint is
on

• /StartTime:hhmm to auto start the run at certain time

• /EmailOn to set Email check box on

• /NotifyOn to set notify on check box

• /ViewPrint to automatically bring up print file

• /HideScript to exclude the contents of the script from the Print file

• /Hide to hide the run dialog box completely when starting if auto start on

• /High to set the high priority check box

• /Wait to auto start in Wait Start mode as a cluster node

• /WinLeft:xx to set the window location and width/height or to restore screen size and
position when restart from Wait Start mode

• /WinTop:xx

• /WinWidth:xx

• /WinHeight:xx

As the Cube Voyager job is executing, periodic messages will be written to the Cube
Voyager run dialog if /Hide is not on. Pressing Ctrl-Break can be normally used to
prematurely terminate the run if the run dialog has been hidden. Otherwise, the Abort
button on the Cube Voyager run dialog can be used. When the Cube Voyager job is
completed, control will return to the windows command line interpreter.
General Syntax > Introduction to Cube Voyager control statements

Introduction to Cube Voyager control statements

Cube Voyager operates by reading control statements from a script (job) file. All control
statements have the same general format. Each statement begins with a control word to
tell the program what type of statement it is. Following the control word and one, or more,
spaces, are keywords and their values. A keyword is always followed by an equals (=)
sign, and then the value(s) to be associated with the keyword. There may be as many
keywords as are applicable to the control type. A statement can be continued onto the
next line by breaking it after a valid operator for the statement. If the last character on the
statement (prior to any comments) is a valid operator for the statement, the statement
MUST continue onto the next line. Valid continuation characters are: comma and
mathematical and logical operators: ( , + - / * ^ & | = ); the character must be one that is
in proper context for the statement.
General Syntax > Introduction to Cube Voyager control statements > Example

Exam ple
COMP a = b + c = ; invalid: = is not in proper context
COMP a = b + c + ; valid: + is logical at this point
d + e / f ; continuation of previous line
ZDATI=myfile, z=2-4, emp=21-30 pop=40- ; valid: - is logical here
48, ; valid: , is logical here
sfdus = 51-55 & ; invalid: & doesn’t fit here
mfdus= 61-65
General Syntax > Control statement syntax

Control statement syntax

This section describes the syntax, or components, of control statements. Topics include:
• Statement tokens (%...%) and (@...@)

• Comments

• Null blocks

• Control blocks

• Control fields

• Keywords

• Subkeywords

• Keyword values and documentation descriptions

• Expressions

• Variable naming convention (general syntax)

General Syntax > Control statement syntax > Statement tokens (%...%) and (@...@)

Statement tokens (%...%) and (@...@)

Any statement may contain tokens for substitution. There are two types of tokens: %...%
and @...@. When the Cube Voyager system reader routine finds a %...% token. the
entire token is replaced with the value from the environment, if there is a name in the
environment that matches the string between the token symbols (case insensitive). It
should be noted that the environment is a copy of the environment when Cube Voyager
began. Any Cube Voyager *SET statements will NOT have altered the environment.
When the system reader finds a @...@ token, the token is replaced with the contents of
the Cube Voyager variable that matches the string. If no matching Cube Voyager
variable is found, the token is not modified. A Cube Voyager variable is one that has
been defined within the Cube Voyager Pilot program, or has been added via a LOG
statement in a RUN program. The replacement occurs ONLY when the statement is
read, and is a literal replacement.
General Syntax > Control statement syntax > Statement tokens (%...%) and (@...@) > Example

Exam ple
ijk = @ijk@ ; retrieve value from Cube Voyager
xxx = @matrix.xxx@ ; retrieve value of xxx as set by prior matrix
PRINT LIST=’ijk from Cube Voyager PILOT=’, ijk ; will be OK
General Syntax > Control statement syntax > Comments

Comments
There may be comments appended to any control statement/line. Comments must be
preceded by a semi-colon (;). There may be any number of spaces before and/or after
the semi-colon; they are ignored. If a statement is continued onto subsequent lines,
each line may have comments. A semicolon (;) as the first character of a statement sets
the entire statement as a comment.
General Syntax > Control statement syntax > Comments > Example

Exam ple
FILEI NETI=myfile.nam, ; I/P network
ZDATI=zonal.dat ; Zonal data
; this entire line is a comment

In the previous example, the FILEI control statement is continued because a comma
follows the network filename. The statement could also have been coded as:
FILEI NETI=myfile.nam, ZDATI=zonal.dat ; I/P network, Zonal data

As a program reads each control statement, it is diagnosed, and listed to the system
print file, thus providing a document for the program application. Comments are very
helpful and should be used whenever it helps to clarify the application. If the first non-
blank character of a data record is a semi-colon, the record is not processed. Blank lines
can be used for spacing purposes. Blank lines following a line with a continuation
character are ignored, and the line following the last blank line is considered as the
continuation.
General Syntax > Control statement syntax > Null blocks

Null blocks
The null block is a section of the input stream that is not processed by the program; it is
skipped over when the program reads the control statement. The block begins with /*
and ends with */, and blocks may be nested. Therefore, care must be exercised when
null blocks are used; if another /* appears before the terminating */ is read, the program
assumes that there is another null block within the current one. This nesting allows the
user to block out a section of the control stream even if a section of the stream already
contains a null block. The rule is that each /* must have a matching */. A null block can
be used to block out stream terminators and even portions of a control stream specifying
other programs to be run. If a matching */ is not found, the end of the block is set to the
end of file on the control stream. Hint: to run only the first portion of an input stream,
place an unmatched /* record after the last desired statement.
General Syntax > Control statement syntax > Null blocks > Examples

Examples
FILEI NETI=myfile.nam, /* I/P network */ ZDATI=zonal.dat ; Zonal data ; ** valid,
but not recommend **
FILEI NETI=ipfile.net /* FILEO NETO=opfile.net */
FILEI NETI=myfile.nam, ; I/P network
/* ZDATI=zonal.dat ; Zonal data */
FILEO ... ; will be an error, because FILEI is to be continued.
General Syntax > Control statement syntax > Control blocks

Control blocks
A control block can be used to block a control statement. The standard format for a
control statement requires that the first word of the statement must be a valid control
word, and must be followed by at least one key word. The statement can optionally be
continued onto subsequent lines by use of a continuation character. Alternatively, a
control block can be used. A control block begins with the control word, white space,
and the {} character. All data up to the next {} character are considered as part of the
statement. If multiple lines are used, they need not contain continuation characters. The
statement will terminate with the {} character. Care must be taken: if there is no {}, the
remainder of the input stream will be appended to the current statement. If the
terminating {} is embedded within a literal string ('.. {} ..' or ".. {} .."), or it follows a
semicolon (;) on a line, it will not be recognized. Currently a control block may be on one
line, but planned revisions will probably preclude this capability. There is no reason to
have a control block on a single line, so it is advisable to not code them that way.
FILEI {
NETI = ... ; continuation character not required.
ZDATI = ...
}
FILEI {NETI = ... MATI = ... } ; not recommended – possible future change
FILEI {NETI = ... ; input network } ; invalid: comment precedes the {}.
FILEI {NETI = ... ; input network
} ; valid: the {} is on a separate line.
General Syntax > Control statement syntax > Control fields

Control fields
A field is a number, or character string, that stands by itself on a control statement. In this
system, fields are thought of as the characters that begin a word and continue until a
field terminator, or delimiter, is detected. The field does not contain the delimiter. The
standard field delimiters are blank, comma, equals sign, dash, or any mathematical
operator (+-*/|&). When a field is followed by a blank, the next non-blank character (if it
is one of the delimiters) is considered as the field delimiter. In many cases there need
not be a specific separator; the blank will suffice. Thus, A=B is the same as A = B, which
is the same as A= B. Likewise 1 2 3 4 5 is the same as 1,2,3,4,5 or 1, 2 3, 4 5.
Because many transportation-planning programs have traditionally used a dash as a
field separator, that tradition is carried over to this system. Dashes do cause some
ambiguity, however, because they are also the same as a minus sign. A dash is
therefore used to specify ranges of values, and to specify negative values, so care must
be taken. If a field is terminated by a dash, it is the beginning of a range. If a field is
begun by a dash, it is a negative value, unless it could also be construed as a range.
The rules applied when a dash is between fields are:
• If the dash touches the first field, or it touches neither field, it is a range.

• If the dash touches the second field without touching the first field, the dash is the sign for
the second field.

• If the dash touches the second field, and there is another dash between the first field and
the dash, it is a range with the second field being negative.

E xa mp le s o f numb e rs s p e c ifie d a s s ing le o r ra ng e v a lue s

E xp re s s io n Me a ning

1-5, 1- 5, 1 – 5 three ways of specifying range: 1 through 5.

1 –5 value 1, and value -5.

1 5, 1,5, 1 , 5 three ways of specifying: value 1 and value 5.

1,-5 error!

1 , -5 value 1 and value -5

13– 5 value 1 and range: 3 through 5.

-1-5 range: –1 through +5

-1--5 range: -1 through -5; descending, and could be

an error.

-8--5 range: -8 through -5, but doesn’t look nice.

-8 - -5 range: -8 through -5, but less confusing.

It should be noted that this syntax is somewhat different for numeric expression fields as
noted below; ranges are invalid in such expressions. Select expressions do allow
ranges for single variables, strings, and results of numeric expressions, so it is
suggested that parenthesis be used to remove any ambiguities in expressions. This is
described in more detail in “IF ... ELSEIF ... ELSE ... ENDIF” on page 54.
General Syntax > Control statement syntax > Keywords

Keywords
All control information is entered by coding a keyword followed by an equals sign (=)
and then the value(s) to be entered for the keyword. Keywords may sometimes specify
vector data (multiple values for successive entries in a curve or array). When a vector
keyword is specified, the data is entered beginning at the first location in the array.
Optionally, the vector keyword may be subscripted, so that the values are loaded into
the array beginning at a specified location. A subscript is specified by inclosing it within
square brackets []. When a keyword is subscripted, there may be no special characters
prior to the right bracket (]); the subscript must fill the space between the [].
Most keywords that are subscripted are specific to the program, and the subscript must
be an integer constant. Some programs allow certain vectored keywords to have a
variable as the subscript; this is usually only when the keyword is on a COMP (or similar
type of statement).
Some keywords allow double subscripts to indicate a matrix of rows and columns. In
such cases, there are two sets of brackets [row][column]. For example: capacity
stratified by lanes (row) and spdclass (column). The row index sets the row where the
data is to load and the column index sets where in the row the data loading is to begin. If
there is no column designation, it is assumed to be one. One is the minimum value for
rows and columns. If there is more input data than is allowed in a row, the data spills into
the next row (beginning at that row’s column 1), but it will not fill beyond the end of the
array. In certain cases, three-dimensional arrays are allowed, but they are rare, and will
be more fully defined in the specific program documentation.
General Syntax > Control statement syntax > Keywords > Examples

Exam ples
LINKI= LIINKI[3]= NOX[2][7]= NOX[3]= ; single value format
VAL=10,20,30,35,40,50 ; VAL[1]=10, VAL[2]=20, …, VAL[6]=50
VAL[55]=770, VAL[83]=1200,1250 ; VAL[83]=1200, VAL[84]=1250
VAL(2) ; invalid, the subscript must be [2]
General Syntax > Control statement syntax > Subkeywords

Subkeywords
Some keywords (internal level 2) may have further descriptive keywords (level 3)
associated with them, and each of those sub keywords may possibly have another sub
keyword (level 4) associated with them. Level 4 is the maximum. A level 2 keyword may
be used at any time, but a level 3 keyword may be used only following a level 2, 3, or 4,
keyword. A level 4 keyword may be used only following a level 3 or 4 keyword. A sub
level keyword applies only to the prior higher ranking keyword. An example is the
Network program FILEI statement. The layering is as follows:
General Syntax > Control statement syntax > Subkeywords > Example

Exam ple
(1) FILEI
(2) LINKI=
(3) EXCLUDE= ; These are same level (3), and can be
(3) VAR= ; used only if LINKI has proceeded them.
(4) TYP= ; These subkeywords
(4) BEG= ; are all at
(4) LEN= ; the same level, and
(4) MIN= ; can not be specified
(4) MAX= ; unless VAR= is
LINKI=myfile, var=a, beg=1,len=5,
var=dist, beg=14, len=3,
var=street, beg=6,len=5,typ=c,
LINKI[2]=myfile2.dbf, var=a,b,dist,name; DBF file

In this example, the comma following typ=c on the third line is not necessary, since LINKI
is a valid FILEI invoking keyword. The typ=c applies only to street. With the comma, the
four lines form a single FILEI statement. Without the comma, they form two FILEI
statements.
General Syntax > Control statement syntax > Keyword values and documentation descriptions

Keyword values and documentation descriptions

What may follow the = for a keyword depends upon the criteria for the keyword. In the
documentation, each keyword description begins with a criteria list enclosed within |...|.
Any of the following letters (case sensitive) within the criteria list indicate what type of
data must be entered for the keyword.

Le tte r D e s c rip tio n

C Character -- any valid text string, but only the first

character is used.

D Double — Double-precision real numbers.

F Filename -- filenames in a format acceptable to the

operating system. If the name is to contain any
special characters that may be in conflict with the
system delimiters, the name must be enclosed within
double quotes. (Single quotes may be used, but if
the operating system allows single quotes in the
filename, double quotes are required). If a filename
contains a question mark (?), the ? is immediately
revised to PPPP, where PPPP is the Cube Voyager
prefix that has been set by the user. In some cases, if
the filename does not contain an extension (.ext), the
program may want to append an appropriate
extension (.NET, .MAT, .DBF, etc.). To preclude the
program from appending an extension, the file name
should end with a dot (.) (For example, MYFILE.)

I Integer -- numbers that are entered without decimal

points. If a decimal point is entered, the value will be
processed as the nearest integer.

R Real -- numbers that may contain decimal points. If

the number is to be entered with a negative exponent
(for example, 1.23E-2), the system reader doesn’t
know if the dash is an exponent sign or a field
separator. With such values, the entire field must be
enclosed within '...' (for example, '1.23E-2'). This
same restriction does not apply to constants within
an expression because ranges are not allowed.
Real numbers are entered as single precision
values: precision is restricted to the 6-7 most
significant digits (system dependant).

? Boolean Response -- true/false character. Programs

may accept various responses depending upon the
native language of the user. In English, for example,
a true response could possibly be any of (Yes,1,
True), and the negative response could be (No, 0,
False); only the first character will be processed.

N Numeric expression -- expressions that will result in a

number. See “Numeric expressions” on page 33 for
details of expressions.

s selection expression -- a special form for

 establishing complex selection criteria; usually IF
statements. The expression must be enclosed within
(...). See “Selection expressions” on page 42 for
details of expressions.

S String -- text string, usually used for naming or

identifying something. If the string is to contain any of
the delimiter characters (including space), it must be
enclosed within '...'. If it is to contain a ', it must be
within "...".

Other characters in the criteria list provide more information about the keyword. Possible
characters and their meanings are:

Cha ra c te r D e s c rip tio n

a Ascending order — Values must be listed in

ascending order.

K Trigger keyword -- The program recognizes the

keyword directly without specification of the control
statement. Therefore, you may specify trigger
keywords as the first word on a statement; the
program treats the entire statement as if the first
word was the appropriate control statement.

P Pairs -- The values may be entered as single

values or as pairs of numbers (two numbers
separated by a dash.)

V Vector -- The keyword is vectored; multiple values

may be entered. An index may be appended to
the keyword to indicate the loading point in the
keyword array. An index should not be appended
if a number does not follow V, and any index may
not exceed the value of the number.

# If a number follows V, it is the maximum index

allowed for the keyword array. For example, V100
means the highest index may be 100.

* The repetition operator * may be used to enter the

same value multiple times for a V keyword. The
data are loaded into successive locations in the
vector.

[n] If [n] follows n, the keyword is doubly dimensioned,

and the [n] is the size of the second dimension. For
example, V10[20] means the array referenced as
the keyword has 10 rows with 20 columns each.
General Syntax > Control statement syntax > Expressions

Expressions
Expressions are either numeric formulas or selection criteria. Selection expressions may
contain embedded numeric expressions.
This section discusses:
• Numeric expressions

• String expressions

• Selection expressions
General Syntax > Control statement syntax > Expressions > Numeric expressions

N umeric expressions
Numeric expressions are written as traditional formulas, and contain operands
separated by operators. Standard hierarchy rules are followed; computation is
performed from left to right, and expressions within (…) are evaluated to a single value.
The hierarchy table for operators is as follows (with importance increasing in level):

Op e ra to r S y mb o l Le v e l

Addition + 1 (in strings, "+" is

a concatenator)

Subtraction - 1

Multiplication * 2

Division / 2

Modular % 2

Exponentiation ^ 3

Operators are preceded and succeeded by operands, which may be numeric constants,
character constants, variables, functions with their associated arguments enclosed
within (...), and sub numeric expressions enclosed within (...),
Numeric constants are entered as standard floating point numbers in the “US” format:
[ddd] [.] [ddd] [fmt[sn]ddd], where:

[ddd] optional digits (0-9)

[.] optional decimal point (a

period)

[fmt] optional e or E

No “thousands separator” or other digit grouping is accepted. Constants are entered as

strings enclosed in '...'.
A program that deals with a variable number of matrices may have the work matrices
referenced by using MW[W] or MW[W][X]. Usually, matrices are referenced within a J
loop (J refers to the destination, or column, cell in the matrix), but that is not always the
case. At times, it may be beneficial to use a computed variable to indicate which work
matrix to reference, and/or which cell in the matrix to reference. When that format is
used, it is the user’s responsibility to ensure that the computed subscripts are within the
correct ranges. Unpredictable results could be obtained, or the program could fatally
terminate, if the subscripts are incorrect.
Expressions are allowed in the MW index on both the left and right side of an equation,
and follow these rules:

Func tio n D e s c rip tio n

MW[W] The Jth cell in work matrix W

MW[W][X] The Xth cell in work matrix W

Both W and X can be a hard-coded constant, a variable, or a computational expression

that will be evaluated during the execution of the statement. Most programs will detect
an invalid index, and terminate with a fatal condition.
Built-in functions are predefined processes that return a value to the expression; they
must be followed by one, or more, expression arguments enclosed within parenthesis ().
The number of arguments must match the requirements of the function. The standard
functions include (this list may be expanded over time):
• Numeric functions

• Trig functions

• Lookup functions
General Syntax > Control statement syntax > Expressions > Numeric expressions > Numeric functions

Num eric functio ns

Func tio n D e s c rip tio n

ABS(x) Absolute value

CmpNumRetNum(V1,OP,V2,R1,R2) Compare number V1 to number

V2 based on OP and return R1 if
result is true and R2 if result is
false. Valid operators OP are
string and can have any of the
following values:
Equal to: '=' or '=='
Not Equal to: '!=' or '<>'
Less than or equal to: '<='
Greater than or equal to: '>='
Less than: '<'
Greater than: '>'
V1, V2, R1 and R2 can be
numeric expressions or numeric
values. This expression can be
nested.
NOTE: If the arguments are
expressions, the expressions
must be resolved before the
function is called to determine
which value is returned.

CURRENTTIME() This function will access the

current local time in number of
seconds since 1/1/1970,
precision down to milliseconds.
This function returns a double-
precision floating-point number. It
may in turn be passsed as the
value (x) to
FORMATDATETIME(x,w,dec,str).
For more on usage, see Example
using CURRENTTIME() and
FORMATDATETIME().

EXP(x) Exponential e to the x (-103 < x <

88)

EXPDIST(x,m,t) Probability density (if t=0) or

cumulative probability (if t>0) at x
given an exponential distribution
with mean m.

EXPINV(p,m) Inverse of exponential cumulative

function at probabiliy p given an
exponential distribution with mean
m. (0 ≤ p ≤ 1).

GAMMADIST(x,a,b,t) Probability density (if t=0) or

cumulative probability (if t>0) at x
given a gamma distribution with
 shape parameter a and scale
parameter b. (a>0, b>0)

GAMMAINV(p,a,b) Inverse of gamma cumulative

function at probabiliy p given a
gamma distribution with shape
parameter a and scale
parameter b. (a>0, b>0, 0 ≤ p ≤ 1)

INLIST(n,str) Returns 1/0 to indicate if the value

of n is found/not found in any
normal paired list represented in
str. If str contains illegal syntax, or
non-numeric values, the function
will try to ignore such errors, and
perform the search on only valid
values. Please note that the size
of str may depend upon the
specific program in which INLIST
is used; the PARAMETERS
MAXSTRING= might be required
if str is long. Str can be
dynamically modified in the
program.

INT(x) Truncated integer value

LN(x) Natural logarithm (x > 0)

LOG(x) Common logarithm (x > 0)

LOGNORMDIST(x,m,s,t) Probability density (if t=0) or

cumulative probability (if t>0) at x
if x has a lognormal distribution—
that is, if LOG(x) follows a normal
distribution with mean m and
standard deviation s.

LOGNORMINV(p,m,s) Inverse of lognormal cumulative

function at probabiliy p given a
lognormal distribution— that is, the
logarithms of values follow a
normal distribution with mean m
and standard deviation s.
(0 ≤ p ≤ 1)

MAX(x,y,...) Maximum value from the list

MIN(x,y,...) Minimum value from the list

NORMDIST(x,m,s,t) Probability density (if t=0) or

cumulative probability (if t>0) at x
given a normal distribution with
mean m and standard deviation
s.

NORMINV(p,m,s) Inverse of normal cumulative

function at probabity p given a
normal distribution with mean m
and standard deviation s. (0 ≤ p ≤
1)

POISSONDIST(x,v,t) Probability density (if t=0) or

cumulative probability (if t>0) of x
occurrences given a Poisson
 distribution with mean and
variance v.

POISSONINV(x,v) Inverse of Poisson cumulative

function at probability p given a
Poisson distribution with mean
and variance v. (0 ≤ p ≤ 1)

POW(x,y) Power (x=base, y=exponent)

RAND() Return a random floating point

number between 0 and < 1

RANDOM(n) Return a random integer between

0 and n‑1, n is an integer between
1 and 2147483647

RANDSEED(n) Initialize the random number

generator with n, where n is an
integer between 1 and
2147483647, so a repeatable
series of random numbers can
be generated from the rand() and
random() functions

ROUND(x) Rounded integer value

SQRT(x) Square root (x > 0)

General Syntax > Control statement syntax > Expressions > Numeric expressions > Trig functions

Trig functio ns

NOTE: Trig functions are applied to values that are in degrees. To convert radians to
degrees:

Degrees=Radians*180/ð

Func tio n D e s c rip tio n

ARCCOS(x) Returns the ARCCOS of x.

ARCSIN(x) Returns the ARCSIN (inverse SIN) of x.

Example VAR2=ARCSIN(0.5) would
return a value of 30. ARCSIN(SIN(x))=x

ARCTAN(X) Returns the ARCTAN of x.

COS(x) Returns the COS of x.

SIN(x) Returns the SIN of x where x is in

degrees. Example VAR1=SIN(30) would
return a value of 0.5.

TAN(x) Returns the TAN of x.

General Syntax > Control statement syntax > Expressions > Numeric expressions > Lookup functions

Lo o kup functio ns

Lookup functions are defined by a LOOKUP control statement. The statement must
contain the source of the lookup data, the name to give the function, and optional
parameters to control the actual lookup of data. See “LOOKUP” on page 57 for a details
about the control statement.
Each program may have a list of functions that are unique to the specific program.
Those functions will be described with the specific program documentation. In some
cases, the user will be allowed to define specific functions for use by the program.
Functions that look up a value in an array or in a set of curves are examples of user
functions.
General Syntax > Control statement syntax > Expressions > Numeric expressions > Examples of valid expressions

Examples of valid expressions

x + 1
(1.5/distance) + (sqrt(AreaType)*abs(FacilityType]) )
Street + ',' + City + DUPSTR(' ',3)
SUBSTR(street,4,6)
FORMAT(volume,8,2,',')
STRPOS('cd','abcde')
INLIST(32, '10-15,25,31-35')
CmpNumRetNum(V1,'>=',V2,V1-V2,V2-V1)
General Syntax > Control statement syntax > Expressions > String expressions

String expressions
String expressions result in string values. String values are specified between single
quotes (e.g., 'abcde'). If a sting contains a single quote character, those strings should
be enclosed inside back quotes (e.g., `abc'de`). Character/ String functions can be
used in the expression.
General Syntax > Control statement syntax > Expressions > String expressions > Character/ String functions

Character/ String functio ns

Func tio n 1 D e s c rip tio n

DELETESTR(s1,n1,n2) Deletes n2 characters in s1

starting at n1 (1 is the first
character); if n1 or n2 is < 1, then
return s1.

DUPSTR(str,n) Duplicates str n times; result

must be less than 100 chars.

FORMAT(x,w,dec,str) Formats number (x) with width=w,

decimals=dec, format=str.
The str pattern can contain any
characters, but will only be used
if it contains any single, or string
of, m, d, or y characters. When
there are one or more m, d, or y
characters in the pattern, it
causes x (first argument) to be
treated as a date value in the
format of yyyymmdd, and its
corresponding month, day, year
elements formatted in place of
the m, d, or y characters. Width
(w) is the maximum length of the
resulting string and must be less
than or equal to 40. Single m, d,
or y characters mean single
digit or double digits depending
on the value. Two or more of the
same special characters mean
formatting to 2 digits with leading
zero if needed.
The only exception is for year,
where yy means 2 digit year;
anything else will be substituted
with a 4-digit year.
For example: yy/mm/dd will
result in 07/02/13 if x=20070213.
"abc m:d:y" would result in
"abc 2/13/2007". If multiple
occurrences of any of the y, m,
or d occur, the result will contain
multiple value substitutions.
"dd/mm/yy abcm" will result in
"13/02/07 abc2".

FORMATDATETIME(x,w,dec,str) This function formats a date/time

value (x, which can be returned
from the CURRENTTIME()
function) according to the
formatstring (str). The result is a
string.
Width (w) is the maximum length
of the resulting string and must
be less than or equal to 40. Dec
 is the number of decimal places
to display in the seconds value.
The formatstring (str) is a string
that provides a template for the
resulting string. It can contain
any characters, but any single,
or string of, y, m, d, h, n or s will
be substituted with the year,
month, day, hour, minute and
second values, respectively.
Single character means single
digit or double digits depending
on the value. Two or more of the
same special characters mean
formatting to 2 digits with leading
zero if needed.
There are two exceptions to this
rule. For year, yy means 2 digit
year; anything else will be
substituted with a 4-digit year.
For hour, three or more h
characters together mean
printing the total number of hours
in the datetime value. This form
is useful when printing elapsed
time between 2 datetime values
but should not be used when
printing a real date since it will
be the number of hours since
January 1, 1970.
For more on usage, see
Example using
CURRENTTIME() and
FORMATDATETIME().

INSERTSTR(s1,s2,n) Inserts s1 into s2 at n; if n < 2,

return s1+s2; if n > length of s2,
return s2+s1.

LEFTSTR(s1,n) Returns n characters from the

left side of s1; if the length of s1
is less than n, or n is < 0, returns
s1.

LTRIM(str) Deletes leading spaces from

str.

REPLACESTR(s1,s2,s3,n) Replaces n occurrences of s2

with s3 in s1, where n is the
number of replacements, 0
means all; if n < 0, then no
replacements, returns s1.

REPLACESTRIC(s1,s2,s3,n) Same as REPLACESTR

above, but ignores case when
searching for s2 within s1.

REVERSESTR(s1) Reverses s1.

RIGHTSTR(s1,n) Returns n characters from the

right side of s1; if the length of s1
is less than n, or n is < 0, return
s1.

STR(v,w,d) Converts the variable v to a

 string that is w characters wide,
with d decimal places. w must
be less than 30, and d less than
w - 2.

STRLEN(str) Returns the length of str.

STRLOWER(str) Sets str to lowercase for

immediate use; str is not
permanently changed.

STRPOS(str,str2) Returns the position in str2

where str begins. If str does not
exist in str2, returns 0. Both
strings are case sensitive.

STRPOSEX(s1,s2,n1) Returns the position of s1 in s2,

but starts the search from
position n1 in s2 instead of from
the beginning of s2. Returns 0 if
not found; if n1 < 1 or n1 > length
of s2, returns 0.

STRUPPER(str) Sets str to uppercase for

immediate use; str is not
permanently changed.

SUBSTR(str,b,n) Extracts a substring from str,

beginning at position b, and
continuing for n characters. b
must be greater than 0.
Returns an empty string if b is
less than 1, if n is less than 1, if
the length of str is less than 1, or
if b is greater than the length of
str.

TRIM(str) Deletes trailing spaces from str.

VAL(str) Returns the numeric value

contained in str.

1 str is either a character constant '...', or a character variable

General Syntax > Control statement syntax > Expressions > String expressions > Example using CURRENTTIME() and
FORMATDATETIME()

Exam ple using CURRENTTIM E() and FORM ATDATETIM E()

StartTime=currenttime()
SLEEP TIME=1.234
EndTime=currenttime()
LowETime1 = EndTime - StartTime

; LowTime, HighTime are other DateTime values

; LowETime2, HighETime are other elapse time values

print list=' Current Date/Time=',formatdatetime(currenttime(),40,2,' yyyy-mm-dd

hh:mm:ss')

print list=' Low Date/Time=',formatdatetime( LowTime,40,3,' yyyy-mm-dd yy-m-d'),

formatdatetime( LowTime,40,3,' hh:nn:ss h:n:s'),
formatdatetime( LowTime,40,3,' hhh:nn:ss')
print list=' High Date/Time=',formatdatetime(HighTime,40,3,' yyyy-mm-dd yy-m-d'),
formatdatetime(HighTime,40,3,' hh:nn:ss h:n:s'),
formatdatetime(HighTime,40,3,' hhh:nn:ss')
print list=' Low Elapse Time=',formatdatetime( LowETime1,40,2,' hhh:nn:ss')
print list=' Low Elapse Time=',formatdatetime( LowETime2,40,2,' hhh:nn:ss')
print list=' High Elapse Time=',formatdatetime(HighETime ,40,2,' hhh:nn:ss')

Result:
Current Date/Time= 2013-07-23 20:07:17.72
Low Date/Time= 2013-02-03 13-2-3 04:07:09.485 4:7:9.485 377748:07:09.485
High Date/Time= 2013-11-20 13-11-20 13:27:49.485 13:27:49.485 384717:27:49.485
Low Elapse Time= 000:00:01.23
Low Elapse Time= 004:05:06.79
High Elapse Time= 098:17:56.79
General Syntax > Control statement syntax > Expressions > Selection expressions

Selection expressions
Selection expressions are used to specify criteria for selecting something. The
expression is always enclosed within (...), and, when evaluated, results in a single true
or false value. The syntax is similar to standard C language, but there are some
exceptions. The expression may contain nested and/or a series of comparisons. The
following comparison operators are used to determine the relationship between the
expressions on either side of the operator (the left expression is A, and the right
expression is B):.

E xp re s s io n D e s c rip tio n

A =B A equals B.

A == B A equals B.

A != B A is not equal to B.

A >= B A is greater than, or equal to, B.

A <= B A is less than, or equal to, B.

A >B A is greater than B.

A <B A is less than B.

A <> B A is not equal to B.

With the = operator, B may be expressed as a series of values, and/or ranges. For
example: I=1-5,15,30-99,212 means if I is 15, or 212, or falls within any of the ranges.
A or B can be a numeric expression enclosed within (...). For example:
(((a+b)/3 * k) = 0.5-1.9,27.2)

Further, ranges are supported only with the = operator. To exclude certain ranges, use
the not (!) operator, such as !(I=2-16). For example, to exclude indices 2 through 16, the
following two expressions are incorrect (resulting in checking if variable not equal to
-14):
IF (variable != 2-16)
...
; Incorrect

IF (variable <> 2-16)

...
; Incorrect

The correct syntax is:

IF (!(variable = 2-16))
...

The range equal operator also works with strings, such as Name='S','U','X'-'Z'. String
comparison is based on the ASCII code value of each character and is done from the
left to right until the right-side string is exhausted. In other words, the number of
characters compared is the string length on the right side. For example,
('abcde' = 'ab') is equivalent to ('ab' = 'ab'), which is true.
On the other hand,
('ab' = 'abcde') is false.
For a full length string comparison (exact match), compare both ways as below:
((‘abcde’=’ab’) & (‘ab’=’abcde’))
One should never use an empty or null string on the right side of a comparison
expression. It will always be true for equality comparison and false for other types of
comparisons.
Since a blank, ' ', is less than any printable character in ASCII code value, we can check
if a text field is not empty using the following expression:
(LTrim(TextFld) > ' ')
Comparisons can be logically combined with other comparisons by using the AND
operator (&&) or the OR operator (||). When logical combinations are made, it is wise to
enclose them within (...); it is not always necessary, but it helps to eliminate ambiguity. A
comparison enclosed within (...) can be preceded with the NOT operator (!) to cause the
comparison result to be inverted. For example: !(i=5-10,12) means if I is not within the 5-
10 range, nor is it equal to 12. AND and OR can currently be specified as single & and |,
but this could change in the future.
General Syntax > Control statement syntax > Expressions > Selection expressions > Example of complex selection

Exam ple o f co m plex selectio n

( (i=1-10,37 && j=150,201-299) || (j=1-10,37 && i=150-201-299) ||
( (I=j & !(i=87-100,203) ) || ((a+sqrt(5*j)) >= (j + sqrt(6/a)) ) ))
General Syntax > Control statement syntax > Expressions > Selection expressions > Examples of keyword variables

Exam ples o f keywo rd variables

int = 1
float = 1.35, 1.23E2
name=abcde, 'this is a name'
NETI=?2005.net, ; expands to PPPP2005.net (prefix = PPPP)
"d:\test\alta\myfile.ext",
..\subd?\ALTA?.net ; expands to ..\SUBDPPPP\ALTAPPPP.NET
General Syntax > Control statement syntax > Expressions > Selection expressions > Examples of expressions

Exam ples o f expressio ns

n + 1
(1.5/i) + (sqrt(MW[3])*abs(MW[m][j-1]) )
Street + ',' + City + DUPSTR(".-",3)
SUBSTR(street,4,6)
Inlist(I,’1-5,99,888-993,5002,6,13’)
Inlist((k*2+j), CBD) ; CBD must be a string variable
Randseed(12345)
Rand()
Random(I) ; if (I<2) will return 0.
General Syntax > Control statement syntax > Variable naming convention (general syntax)

Variable naming convention (general syntax)

Variables used in expressions must have a valid name. There are some basic rules that
must be followed in assigning a name to a variable. Some programs might relax the
rules a bit, but to prevent any problems, the following rules should be adhered to.

R ule D e s c rip tio n

Length: Any reasonable length; network

variables may not exceed 15
characters. If a database file (.dbf) is to
be written, the program will truncate the
name to 10 characters (the maximum for
the dbf).

Valid Characters: A-Z, a-z, 0-9, _$#@

Case: Insensitive.

First Character: Any of the valid characters, except 0-9.

Temporary variables: Convention is to use underscore ”_” as

the first character.

Variables are also used to reference items specific to a program. In a network-

processing program, they could reference the variables associated with a network. In a
matrix program, they could reference certain matrices. They also may reference
variables defined specifically for the program (that is, I, J, M, etc.), or variables defined
by the user in a prior assignment control statement. Usually, variable names can be
most any length, but if the variable is to be associated with an input or output file, its
length must be restricted to no more than 15 characters. If a file variable is to be
referenced directly, it must be preceded with a prefix to indicate which file to use.
Input file variable prefixes are always in the format 'TI.#.', where:

P re fix D e s c rip tio n

T File type (L=Link, N=Node, M=Matrix,

Z=ZonalData).

I Indicates Input

# Index (explicit or implied) number of the file type

named on a FILEI control statement.

The possible filename variables formats (illustrated by example) are:

File na me fo rma t D e s c rip tio n

MI.3.varname refers to the matrix named varname found
on the file designated by MATI[3]= on the
FILEI control statement. If varname is a
number, it refers to a relative matrix on the
file

NI.3.varname refers to the variable named varname

found in the node portion of the network file
designated by NETI[3]= on the FILEI
control statement.

LI.2.varname refers to the variable named varname

found in the link portion of the network file
designated by NETI[2]= on the FILEI
control statement.

ZI.5.varname refers to the array named varname

generated by the file designated by
ZDATI[5]= on the FILEI control statement.
Zonal data are read into zonal arrays;
each variable is an array with zones cells.
Usually, the reference to a zonal value
would also include a subscript; for
example, ZI.5.POP[I].

NOTE: LI.name and NI.name are used when there is only one NETI allowed in the
program (currently applies to only the Highway program).
General Syntax > Standard control statements

Standard control statements

This section discusses details about specific control statements. Topics include:
• Control statement introduction (general syntax)

• COMP

• CONSOLE

• FILEI

• FILEO

• GLOBAL

• ID

• IF ... ELSEIF ... ELSE ... ENDIF

• LOG

• LOOKUP

• PRINT

• PRINTROW

• READ

• SORT
General Syntax > Standard control statements > Control statement introduction (general syntax)

Control statement introduction (general syntax)

Many programs will share the same type of control statements; however, the data
entered on them may vary between programs. This section briefly describes the
common format of statements that are used in many of the Cube Voyager programs. All
statements follow the format that the statement type is identified by the first word that
appears on it. Usually, the first word is the ControlWord. However, in some cases it is
more expedient (and/or convenient) for the user to start the statement with one of the
special keywords that is acceptable for that type of statement. Those keywords (termed
“trigger” keywords) are identified in their respective program detailed descriptions. The
general format for describing Control Statements in this document is:
ControlWord

Key1 Key1 Key1 (Key2 Key2 (Key3 Key3) ) Key1 (Key2) ...
ControlWord is the statement type and must be the first keyword on each statement,
unless the statement contains “trigger” keys, and the first keyword is a trigger keyword
followed by an equals sign. See the keyword description below for details about trigger
keys, denoted by K within the |...|.

Ke y D e s c rip tio n

Key1 A keyword that must be followed by an equals

sign and appropriate value(s).

Key2 A keyword that is valid only if it follows the values

for its Key1, an equal level Key2, or any key3 or
key4 (for the same Key1).

Key3 A keyword that is valid only if it follows the values

for its Key2, an equal level Key3, or a key4 (for the
same Key2).

The parenthesis () are used only to indicate the key level; they are not coded on the
statement. A keyword must always be followed by an equals sign and appropriate
value(s).
The following example illustrates the hierarchy of control statement description:
CTLWRD

AAA BBB (CCC DDD) EEE FFF (GGG (HHH III) JJJ (KKK) )
This description indicates that AAA, BBB, EEE, and FFF are all valid keywords. They
must be followed directly by an equals sign and the associated values, and may appear
any place a keyword is allowed. CCC and DDD are valid level 2 keywords, and may
appear only following the values for either BBB, CCC, or DDD. GGG may follow the
values for FFF, GGG, HHH, III, JJJ, and KKK. HHH and III are level 3 keywords, and
may appear only following the values for GGG, HHH, or III. KKK is also a level 3
keyword and may appear only after the values for JJJ or KKK.

Ke y wo rd v a lue s D e s c rip tio n

AAA=3 BBB=5 DDD=2 Valid.

EEE=25,FFF=Y

AAA=3 DDD=2 BBB=5 Invalid: DDD must follow BBB or

CCC

KKK=27 Invalid: KKK must follow JJJ.

FFF=Y HHH=5 Invalid: HHH must follow GGG

BBB=5 CCC=6 DDD=7 CCC=8 Valid.

BBB=9
General Syntax > Standard control statements > COMP

COMP
COMP statements are used to dynamically assign values to variables and/or matrices.
COMP statements contains one, or more, keywords with associated numerical and/or
character expressions. Each expression results in a number or a character string; its
mode is usually determined by the first term in the expression. If the first term is a
number, or numeric variable, it is a numeric expression, or if the first term is a character
function or literal character string (beginning with a quote), it is a character expression.
Every term within the expression must be known to the expression at the time the COMP
statement is to be compiled. Often a variable is defined by its presence as a keyword in
another COMP statement. If there are multiple expressions on a COMP statement, they
are solved in left to right order.
K = j + 2 ; defines K as a numeric variable.
name=' ' ; declares name as a variable that is 4 characters long.
namx=substr(name,1,3)+'abcde'+str(k,4,1) ; declares namx as a character variable
that is 12 characters long.

All numeric variables that are declared by the user in this manner are internally treated
as double precision floating point variables.
Some programs (mostly those involving zonal matrices) may allow the use of INCLUDE
and EXCLUDE keywords on the COMP statement. When the statement contains either, or
both, of these keywords, it means that the statement will be subjected to a zonal filter
before being processed. The zonal filter will refer to either I (origin zone) or J (destination
zone); the program definition will clarify which. If an INCLUDE is present, the zone number
will be checked against the zones in the INCLUDE list. If it fails the INCLUDE list
specifications, the statement is bypassed. Then, if there is an EXCLUDE, the zone is
checked with the EXCLUDE list. If it meets the EXCLUDE list specifications, the statement is
bypassed.
General Syntax > Standard control statements > CONSOLE

CONSOLE
A CONSOLE statement is used to set certain switches relative to dynamic display of
messages in the message area of the window.

S ta te me nt D e s c rip tio n

CONSOLE Causes all subsequent text written to the

ONLINE=Y standard print media to also be written to the
console.

CONSOLE Turns off the ONLINE=Y switch

ONLINE=N

CONSOLE Causes text to be written to the console.

MESSAGE=text
General Syntax > Standard control statements > FILEI

FILEI
FILEItells the program which input files to process. In most cases, if there is no FILEI
statement, the program will assume a default statement, or simulate certain required
defaults. Typical keywords on a FILEI statement are NETI, MATI, and ZDATI. When the
program accepts FILEI vectored keywords, such as MATI in various programs, the
keyword may contain [i]. If [i] is not specified, [1] is assumed. Most times the statement
may begin with the keyword itself, thus eliminating the need to code FILEI. The exact
format of the FILEI statement will vary between programs.
FILEI MATI=?01.mat, ?02.mat, ?03.mat,
NETI=??.mat
MATI[1]=?01.mat, MATI[2]=?02.mat, MATI[3]=?03.mat NETI=??.mat
; this would be the same as the above FILEI statement.

Some FILEI keywords may allow sublevel keywords that are associated with the file
keyword. In some programs, all FILEI statements must be in the beginning of the control
stream, because later control statements may reference variables that are to come
directly from the files. The documentation for each program will indicate where the FILEI
statements are valid. Generally, programs delay opening FILEI files until absolutely
necessary, but it is wise to form the habit of placing all FILEI statements first in the control
stream.
Hint: It is relatively easy to miscode FILEI statements by either omitting or including line
delimiters. For example:
FILEI MATI[1]=… ; this is single FILEI statement
MATI[2]=… ; this is a single FILEI statement
MATI[5]=…, ; this is a FILEI statement with continuation
Abc=def ; but this is probably an invalid FILEI continuation

NOTE: Application Manager automatically writes all FILEI statements to the script file
when you define input file boxes. If you use Application Manager, do not manually edit
the file path or file name elements of the FILEI statements, as both the script file and the
application’s .app file stores this information. Editing the file path or file name will result in
a mismatch between the file that the script uses when it runs and the file Application
Manager opens when you double-click an input file box. (See Chapter 14, “Application
Manager,” in the Cube Base Reference Guide.)
General Syntax > Standard control statements > FILEO

FILEO
FILEO is the counterpart to FILEI; it names the output files that the program writes. If there
is no FILEO statement, some programs will generate an appropriate statement. The exact
format of the FILEO statement varies between programs.

NOTE: Application Manager automatically writes all FILEO statements to the script file
when you define content for output file boxes. If you use Application Manager, do not
manually edit the file path or file name elements of the FILEO statements, as both the
script file and the application’s .app file stores this information. Editing the file path or file
name will result in a mismatch between the file the script writes during runs and the file
Application Manager opens when you double-click an output file box. (See Chapter 14,
“Application Manager,” in the Cube Base Reference Guide.)
General Syntax > Standard control statements > GLOBAL

GLOBAL
Alters the size of a page on the standard print media. Keywords include:
• P A GE H E IGH T

• P A GE W ID T H

The keywords are trigger keywords; you need not specify “GLOBAL.”
GLOB A L k e y wo rd s

Ke y wo rd D e s c rip tio n

PAGEHEIGHT |KI| Resets the maximum number of lines on

a page, so that the system knows when
to start a new page with appropriate
headers. The value must be in the range
10-32767. Hint: If the print file is going to
be viewed primarily on-line (instead of
actually being printed), it is suggested
that PAGEHEIGHT be set to a large
number to reduce the number of
interspersed page headers. The
PAGExxxx values can also be set when
Cube Voyager is initially launched from
its menu.

PAGEWIDTH |KI| Resets the maximum number of

characters to be printed on a single line.
Usually this value is either 80 or 132 to
accommodate most character printers. It
only comes into play when certain
reporting processes need to know the
width of a print line, so it can form the
report properly. The value must be in the
range 50-250.

If these parameters are specified, they remain in effect through subsequent programs
until revised.
General Syntax > Standard control statements > GLOBAL > Example

Exam ple
PAGEHEIGHT=32767 ; preclude insertion of page headers
General Syntax > Standard control statements > ID

ID
An ID statement is used to revise the page headings for each printed page. The length
of the ID text will be truncated to 60 characters. The ID is specified as: ID=newid string.
The ID is revised in one of two ways: with the ID statement, and (in some programs) by a
COMP ID=text expression. ID statements in Cube Voyager Pilot program are dynamic;
they cause the ID to be revised when the statement is processed in the Cube Voyager
operations stack. ID statements in the application programs cause the ID to be revised
only when the statement is encountered in the statement reading and editing phase prior
to actual program execution. This can cause the sign-on ID to be revised at a time
different than what might be expected. Because of this situation, it is suggested that ID
statements be used before a RUN statement. That way, the sign-on page for the
application program will contain the desired ID.
General Syntax > Standard control statements > ID > Example of improper ID location

Example of improper ID location

RUN PGM=MATRIX
ID=this is the MATRIX ID
ENDRUN
RUN PGM=HIGHWAY
ID=this is the HIGHWAY ID
ENDRUN

In this situation, the first page (sign-on) for the Matrix application will not contain the “this
is the MATRIX ID” as its header, but the first page of the Highway section would contain
it. If the RUN and ID statements were reversed, the sign-on IDs would be correct.
When ID is specified as the destination in a COMP statement, the ID can be computed,
and it is revised at that time (but will not be reflected in the headers until a new page is
required). In the COMP statement, parts of the ID can be computed. This would most
likely be used in a Cube Voyager loop situation:
General Syntax > Standard control statements > ID > Example of Computing the ID

Exam ple o f Co m puting the ID

LOOP PASS=1,5
COMP ID=’This is Pass’+str(PASS,2,0)
RUN PGM=
…
ENDRUN
ENDLOOP
General Syntax > Standard control statements > ID > Example

Exam ple
ID=This is the new Page Header
General Syntax > Standard control statements > IF ... ELSEIF ... ELSE ... ENDIF

IF ... ELSEIF ... ELSE ... ENDIF

IF statements control the flow of user defined operations for those programs that provide
for them. IF is followed by a selection expression enclosed within (...). The expression is
evaluated and will result in a true or false condition. For each IF statement, there must be
a matching ENDIF later in the input stream. Between the IF and its matching ENDIF,
optionally, there may be any number of ELSEIF statements, and one ELSE statement. The
ELSEIF statement has the same format as the IF statement. Program flow is determined
by the results of the condition evaluations of the IF and ELSEIF statements, and the ELSE
statement. Flow is outlined as:
• IF/ELSEIF expression is true — The statements following the statement are executed until an
ELSEIF, ELSE, or ENDIF is encountered. The next statement executed is the one following the
associated ENDIF statement.

• IF/ELSEIF expression is false — The next statement to be executed is the next associated
ELSEIF, ELSE, or ENDIF statement.
General Syntax > Standard control statements > IF ... ELSEIF ... ELSE ... ENDIF > Example

Exam ple
IF (I<0)
s1...
ELSEIF ( I>=0 & I<5 )
s2...
ELSEIF (I==8)
s3...
ELSE
s4...
ENDIF

For varying values of I, the statements would be executed as:

V a lue o f I S ta te me nts e xe c ute d

-1 S1

3 S2

9 S3

>9 S4

If, in the example, there were no ELSE statement, then any time I is greater than 8, no
statements between the IF and the ENDIF statement would be executed.
A variation of the IF statement (sometimes referred to as a simple or short IF) is one in
which a single control statement is appended after the IF expression. In such cases, the
program automatically generates the required ENDIF. This shortcut statement is provided
to help reduce the amount of coding required. Note: if a short IF is used and the
statement appended to the statement is not acceptable in that context or is mis-
structured, the error diagnostic stated about the line may be somewhat confusing. This
is because the system can not always fully ascertain exactly what the problem is. It is
diagnosing an IF statement, but the appended statement has errors, so it doesn’t know
exactly where to place the blame because it is diagnosing the IF statement at the time.
Note that there is no corresponding short ELSEIF statement and no control statements
may directly follow ELSEIF or ELSE or ENDIF statements on the same line or they will be
ignored by the processor.
IF ( i == 1) counter=0
IF ( i == zones) print ...
IF (j==3 & k==5) k=3 ; This statement will be OK, ENDIF generated.
cnter = cnter + 1 ; and this is OK
ENDIF ; This will fail, because there is no associated IF.
IF (j==3 & k==5) k=3, ; This statement will be OK
cnter = cnter + 1 ; and this will continue it
; Generated the ENDIF here
ENDIF ; So, this will be an error.
General Syntax > Standard control statements > LOG

LOG
Writes values to the log file. Keywords include:
• P R E FIX

• VAR

Cube Voyager maintains a file called the log file; it has a filename with an extension of
.VAR. Whenever a RUN statement is encountered, Cube Voyager updates the values in
the .VAR file with the values for all the variables that Cube Voyager is maintaining plus
the values that were logged by any programs. If a program is requested to LOG any
values, the program appends values to the .VAR file, and Cube Voyager retrieves the
values when the program terminates.
The values in the .VAR file can be accessed in two different ways: 1.) in Cube Voyager,
the variable can be accessed directly; 2.) in other programs, the values can be retrieved
by the use of the @…@ token process. In the latter case, the value from the .VAR is
substituted directly into the control statement as it is read. A LOG statement is used to
have a program write values to the .VAR file. The variables in the .VAR file can be
retrieved by other Cube Voyager programs (including the Pilot program) in the same job.
Examples may help to clarify this process.
RUN PGM=MATRIX ; (Cube Voyager tests the value from MATRIX):
ZONES=5
MW[1] = 1
TOTMW1 = TOTMW1 + ROWSUM(1)
LOG VAR=TOTMW1
ENDRUN
IF (MATRIX.TOTMW1 == 0) ABORT MSG=’Nothing in MW1’
RUN PGM=HIGHWAY ; (HIGHWAY obtains a value from MATRIX):
.
X = @MATRIX.TOTMW1@
.
ENDRUN

The records that are written to the file are written as PREFIX.VAR=value. The current
version of Cube Voyager truncates .VAR string values with embedded or trailing spaces
at the first space when it reads the values. This is scheduled for revision in a
subsequent release of the system.
LOG k e y wo rd s

Ke y wo rd D e s c rip tio n

P R E FIX |S| Sets the prefix of the logged

variable(s). This string is added to
the start of the names of all
variables that follow PREFIX. If
PREFIX is not specified, the
program name will be used. This
 could be confusing if different
applications of the same program
log the same values.

VAR |S| Indicates which variables will have

their values written to the .VAR file.
General Syntax > Standard control statements > LOG > Example

Exam ple
RUN PGM=MATRIX
.
LOG PREFIX=MATRIX1, VAR=TOTMW1, AVEMW
LOG VAR=GRANDTOTAL ; will be written as MATRIX1.GRANDTOTAL=#####
General Syntax > Standard control statements > LOOKUP

LOOKUP
A LOOKUP statement is used to define a lookup function and to enter data for the
function. Keywords and subkeywords include:
• FA IL

• FILE

• IN T E R P OLA T E

• LIS T

• LOOKU P I

• N A ME
m
LOOKUP
m RESULT

• NEAREST

• R

• SET UPPER

• S IZE

• T OLE R A N CE

The statements are not dynamic; they are processed at the appropriate time by the
program, prior to their actual use. Lookup functions are referenced from within numerical
expressions. When the function is referenced in an expression, the correct number of
arguments enclosed within parenthesis must follow it. The function returns a single value
to the expression solver. A lookup array is allocated and initialized with the data
referenced by the LOOKUPI, FILE or R keywords. In most cases, a lookup statement will
define a single set of lookup data, but if a LOOKUP subkeyword follows the NAME, the
function will be defined as one that requires at least two arguments (curve number and
the value to be searched for). This latter format is useful for entering friction factors for
use in the Distribution program. Data referenced by LOOKUPI or FILE keywords can be
either in DBF, MDB, or delimited ASCII format.
A new wizard feature has been added to Cube to automate the coding of a LOOKUP
function when linking a DBF file to a LOOKUPI file box in Application Manager. See
Chapter 12, “Job Script Editor Window,” in the Cube Base Reference Guide for
information about this wizard.
LOOKU P k e y wo rd s

Ke y wo rd S ub k e y wo rd T ype D e s c rip tio n

FAIL |RV3| Defines the results to be returned by the

function if the lookup value is not
contained within the data.
 By default, if the value is less than the
lowest value in the table, the result for
the lowest value in the table is returned,
unless FAIL[1] is explicitly specified.
If the value is greater than the highest
value in the table, the result for the
highest value in the table is returned,
unless FAIL[2] is specified. If the
value is not found within the data,
FAIL[3] (default value is 0) is returned.
If a call to the function has more
arguments than is required, the
argument following the required
arguments is the value that will be
returned if the lookup fails for any
reason. Note that versions prior to 1.5.5
did not return the extreme results of the
data for low and high failure; they
returned FAIL[1] and FAIL[2],
respectively. If FAIL[1-2] were not
specified, they were set to 0.

FILE |F| Name of the file that contains the data to

be associated with the function. This
keyword must be specified, unless R or
LOOKUPI is specified. FILE, R, and
LOOKUPI are mutually exclusive.

INTERPOLATE |?| Indicates if the returned function value is

to be the result of interpolating between
rows in the lookup table. The default
value is false, meaning that there must
be a direct match in the table.

LIST |?| Indicates if the program is to format and

list the lookup table.

LOOKUPI |I| The # of the FILEI LOOKUPI[#] file

where this LOOKUP statement is to
obtain values. Note that FILE, LOOKUPI
and R are mutually exclusive. The data
formats supported for LOOKUPI= and
FILE= when referencing data from an
external file are ASCII and DBF. ASCII
data MUST be delimited with either
spaces or commas.

NAME |S| Name of the lookup function that the

statement defines.

NAME LOOKUP |S| Used when data for one, or more,

curves is to be obtained from a single
data record. The LOOKUP keyword
must be indexed [1-n], and its value
must be followed by RESULT=value.
The values provided for the LOOKUP
and RESULT keywords are either the
field numbers in the input data (ASCII,
DBF, or MDB data) or the field names
when the input data is in DBF or MDB
format. The LOOKUP index indicates
the curve number and the LOOKUP
value indicates which column or field in
the input data file holds the lookup
 values for the indexed curve. The value
following the RESULT keyword indicates
the field number or name on the data
record where the return value for the
curve on the LOOKUP index is to be
found. The use of the LOOKUP keyword
implies that the call to the lookup
function must contain at least two
arguments (a curve number, and a
value to be searched for). For example
on the LOOKUP statement with
NAME=FUNC1, LOOKUP[1]=1
RESULT=2, a call to this function like
X=FUNC1(1,5) implies for curve 1 (first
argument in the function call), lookup a
value of 5 (second argument of the
function call) in the data field defined by
the LOOKUP value (the first field in this
example) and return the value from the
field in the data file defined by the
RESULT value (the second field in this
example). The returned value from the
function would be placed in the variable
X.

NAME RESULT |S| Field number or name of the field from

the data record that contains the result
to be returned when the function is
called.

NEAREST |?| Specifies that the function should return

a value based on the nearest value
found in the table to the lookup value
when an exact match cannot be found.

R |SV| Used in place of the FILE or LOOKUPI

keywords to enter data records for the
function. If R is specified, FILE or
LOOKUPI may not be specified. FILE,
LOOKUPI and R are mutually exclusive.
Any number of R records can be
entered. The string values following R
represent data records that are in the
same format as the FILE records would
be. Each R value must be enclosed
within single quote marks '...'. A single
R= may specify the entire file, or
multiple R= records may be entered.
See “Example: Double value function —
Typical friction factor curves” on
page 65 for an example showing the
use of LOOKUP to define friction factor
curves for the usage of R= to read data
directly from the body of the script file.

SETUPPER |?| Specifies that the function is to simulate

an upper limit for a lookup row when
only a single value is entered for the
row. This option is useful when the data
is input with single values, and the
function can not find an exact match,
and it is to return a value based upon
the lower of two ranges. For example, a
curve is entered with single values that
 begin at 1 and increment through 10 by
1. A lookup for 1.5 would fail. If
INTERPOLATE were true, the return
value would be computed, otherwise
the return would be error. In such cases,
if SETUPPER were true, the result for 1
would be returned. SETUPPER takes
precedence over INTERPOLATE, and
only comes into play for rows without
both limits explicitly provided.

SIZE |I| Optional variable that specifies the total

number of entries in a LOOKUP array.
The value should be the number of
resulting values to be searched for
multiplied by the number of records. As
of v4.1 of Cube Voyager and TP+
systems, this keyword is no longer
required as the memory allocation
process is now automated to optimize
within the resources of the computer it is
using. However, it is maintained to
insure backward compatibility with
previous versions of the software.

TOLERANCE |R| Specifies a tolerance to be applied to

the lookup value. This can be useful
when the lookup value is the result of a
computation and due to processor
differences there may be differences in
the level of precision associated with
the result.

Lookup functions are referenced in numerical and selection expressions. When a

function is referenced, it is supplied a lookup argument within parenthesis, and the
function returns a value for the argument. The returned value is obtained by searching
the lookup function data table for the lookup argument. The table is composed of rows of
data.
If the LOOKUP subkeyword is in effect, the call to the function requires at least two
arguments: the lookup curve number and the lookup argument. Otherwise, the function
requires only one argument: the lookup argument. If the function can not find a match for
the lookup curve number, FAIL[3] is returned, regardless of the value of INTERPOLATE. If
the argument is less than the lowest value for the lookup number the return value is set
to FAIL[1]. If the argument is higher than the highest value, the return value is set to
FAIL[2]. If the value is not found in any range, the return value is set to FAIL[3] unless
INTERPOLATE is set to true. If interpolation is used, the return value is the result of
interpolating between the high limit of the lower row and the low limit of the upper row.
For either a single or double value function (functional call with 1 or 2 arguments) and
additional argument value can be provided. If this optional argument is provided ANY
failure will not return the FAIL value defined by the FAIL keyword or its default values but
the value for this optional argument will be the returned value on any failure. This in
effect gives you the ability to override the default FAIL values for specific situations.
Possible data records include:
• Data records when LOOKUP subkeyword is NOT used and data source is ASCII:

Each data record must have at least two fields delimited by white space, or commas
or may be separate fields on a DBF file. The first field on a record is the lookup result,
and the fields following it are the lookup values. If two numbers are separated by a
dash, they form the low and high limits of a row. Numbers not separated by dashes
are entered as both the low and high limits of a row. Ranges may not overlap, but the
upper limit of a row may be equal to the lower limit of the next row. If the argument
matches a high limit of a row and the low limit of the next row, the result is obtained
from the upper row. (For example, first row limits=1-2, second row limits =2-3. The
result for 2 would be obtained from the second row.)
• Data records when LOOKUP subkeyword is not used and data source is DBF or MDB:
Only the first two fields on the DBF or MDB lookup file will be used. The first field is
the lookup result and the second field is the lookup value. The first two fields should
be numeric fields but character fields are ok as long as the content can be converted
to numerics, otherwise the program will report a lookup input error.
• Data records when LOOKUP subkeyword is used:
Each data record may have any number of fields delimited by white space, or
commas or may be separate fields on a DBF or MDB file. The data for each LOOKUP
is obtained from the record according to the field numbers or names specified for the
LOOKUP and RESULT keywords. If either field number exceeds the number of fields on
the record, there is no row generated for that curve. If both fields exist, they form a row
with the low and high limits equal to the value from the LOOKUP field.
When the lookup format designates multiple curves, special consideration is given to
blank fields. Blank fields are not treated as zeroes, but indicate there is no data point.
For example, assume the following records:
T, v1, v2, v3
1, 101, 201, 301
2, 102, 202, 302
3, 103, , 303
4, 104, 204
5, , , 305

There will be no data points for T=3,V2, T=4,V3, T=5,V1, and T=5,V2. The V1 curve
will have points for T=1-4, the V2 curve will have points for T=1-2,4, and V3 will have
points for T=1-3, 5. The result for a lookup of T=3 in V2, will depend upon the options of
the LOOKUP statement (SETUPPER, INTERPOLATE, or none).
Be aware that this situation exists only for comma delimited and dbf data; space
delimited records don’t have any way to designate null fields; the first empty field
indicates the end of the record, and no more points appear on the record. With space
delimited records, the T=3 record would appear as “3 103 303”, which would be
interpreted as points for V1 and V2; V3 would be blank.
General Syntax > Standard control statements > LOOKUP > Example: Single value function

Exam ple: Single value functio n

COPY FILE=C:\LOOK1.DAT ; this is the data for the function
1 2 3 4-8 23
15 50
2 1
3 9-10
ENDCOPY
LOOKUP NAME=DISTRICTS, FILE=C:\LOOK1.DAT LIST=Y

The lookup table will be represented as:

Lo we r Limit U p p e r Limit R e s ult V a lue

1 1 2

2 2 1

3 3 1

4 8 1

9 10 3

23 23 1

50 50 15

DISTRICTS(6) results in the value 1.

DISTRICTS(9) results in 3.
DISTRICTS(50) results in 15.
General Syntax > Standard control statements > LOOKUP > Example: Single value function using LOOKUPI

Exam ple: Single value functio n using LOOKUPI

FILEI LOOKUP[1]=C:\LOOK1.DAT
LOOKUP NAME=DISTRICTS, LOOKUPI=1 LIST=Y
General Syntax > Standard control statements > LOOKUP > Example: Double value function — Typical friction factor
curves

Exam ple: Do uble value functio n — Typical frictio n facto r curves

The traditional format for friction factors has been one in which the first field on an input
data record is the time value, and the subsequent fields are the factors for the various
purposes that are being distributed. This example illustrates that typical process.
Because the Cube Voyager distribution process is generic, it is possible to have times
that are below the minimum time and greater than the highest time. The normal (default)
process would return a 0 for those values (from the FAIL values), but that may not be
what is expected. In most situations, users may wish to have values for times that
extend beyond the limits of the values entered.
For example: a table might have factors for times from 1 through 100, but there are
zone-to-zone times that are greater than 100 minutes. The time matrix might also have
very large values, or possibly zero, for zone-to-zone movements for which there is no
path (inaccessible). Thus, if a time of 110 is encountered, the friction factor obtained
from the lookup would be the FAIL[2] value; this may not be what was wanted. A similar
situation would occur if the time were less than 1, but greater than 0. To circumvent
these potential problems, be sure to include a record for a very low time value (say
0.01), and a record for the highest time value that you feel is reasonable. The factors of
the two first records should be the same, and the factors for the last records should also
be the same.
The lookup values can be set so that only trips within a certain item range can be
distributed. The limits of the curve would control this operation; a friction value of 0 will
preclude distribution between the zones.
LOOKUP NAME=FF, ; typical Friction Factor table
LOOKUP[1]=1, RESULT=2, ; Curve 1 lookup value is in field 1
; Result (FF) for curve 1 is in field 2
LOOKUP[2]=1, RESULT=3, ; Curve 2 lookup value is in field 1
; Result (FF) for curve 2 is in field 3
LOOKUP[3]=1, RESULT=4, ; Curve 3 lookup value is in field 1
; Result (FF) for curve 3 is in field 4
FAIL=2000,1,0, ; return 2000 if any lookup < 0.01
; return 1 if any lookup > 120
INTERPOLATE=Y, ; interpolate to obtain values
R= '0.01 1200 1000 800',
'1 1200 1000 800',
'3 300 500',
'4 100 100 100',
'5 50',
'120 50 100 100'
FFX = FF(1,3) ; RESULT = 300
FFX = FF(3,150,888) ; RESULT = 888 since 150 > highest value in field 1
FFX = FF(2,2) ; RESULT = 750
/* to find 2 in field 1, you must interpolate between 1 and 3
then interpolate on same basis between 1000 and 500 in field 3
*/
The lookup table will be represented as:

Curv e Lo we r Upper R e s ult

# Limit Limit V a lue

1 0.01 0.01 1200

1 1 1 1200

1 3 3 300

1 4 4 100

1 5 5 50

1 120 120 50

2 0.01 0.01 1000

2 1 1 1000

2 3 3 500

2 4 4 100

2 120 120 100

3 0.01 0.01 800

3 1 1 800

3 4 4 100

3 120 120 100

General Syntax > Standard control statements > LOOKUP > Example: Double value function — LOOKUP with DBF
LOOKUPI file

Exam ple: Do uble value functio n — LOOKUP with DBF LOOKUPI file
FILEI LOOKUPI[1] = "C:\CUBETOWN\TAZ\TAZ.DBF"
LOOKUP LOOKUPI=1, ;references the input DBF file
NAME=TAZ, ;name for this function
LOOKUP[1]=TAZ, RESULT=ACRES, ;lookup a value in TAZ return
;a the value from ACRES
LOOKUP[2]=TAZ, RESULT=POPULATION,
LOOKUP[3]=TAZ, RESULT=AGE_5_14,
LOOKUP[4]=TAZ, RESULT=AGE_15_17,
LOOKUP[5]=TAZ, RESULT=ENROL_ELEM,
LOOKUP[6]=TAZ, RESULT=ENROL_HS,
LOOKUP[7]=TAZ, RESULT=TOTAL_JOBS,
LOOKUP[8]=TAZ, RESULT=RET_JOBS,
LOOKUP[9]=TAZ, RESULT=SERV_JOBS,
LOOKUP[10]=TAZ, RESULT=OTH_JOBS,
INTERPOLATE=F
; example of use: v=TAZ(10,25)
; look for 25 in the TAZ field and returns the OTH_JOBS value
General Syntax > Standard control statements > LOOKUP > Example: Double value function — Using LOOKUP to get
constants and populate internal arrays with the values

Exam ple: Do uble value functio n — Using LOOKUP to get co nstants and po pulate internal arrays with
the values
FILEI ZDATI[1] = "C:\MTA_GEN\STEP1.DBF"
FILEI LOOKUPI[1] = "C:\MTA_GEN\CFACS.DAT"
cc=zi.1.cc ;cc = county code (1=LA,2=OR,3=RV,4=SB,5=VN)
; lookup county correction factors O&D Survey
LOOKUP LOOKUPI=2 LIST=Y NAME=CFAC,
LOOKUP[1]=1, RESULT=2,
LOOKUP[2]=1, RESULT=3,
LOOKUP[3]=1, RESULT=4,
LOOKUP[4]=1, RESULT=5,
LOOKUP[5]=1, RESULT=6,
INTERPOLATE =N
; dimension user arrays to 5
array c0=5 cv=5 c2=5
; fill arrays for factors by county
LOOP cc=1,5
c0[cc]=CFAC(cc,1)
cv[cc]=CFAC(cc,2)
c2[cc]=CFAC(cc,3)
ENDLOOP
/* ;external LOOKUPI file in this example
1 3.4108 3.4137 3.7070 3.4132 3.2278
2 0.6088 0.6767 0.6505 0.6389 0.6759
3 0.5665 0.6518 0.5778 0.5757 0.6642
*/
General Syntax > Standard control statements > LOOKUP > Example: Double value function — Using LOOKUP with DBF
data in a trip Distribution application

Exam ple: Do uble value functio n — Using LOOKUP with DBF data in a trip Distributio n applicatio n
RUN PGM=DISTRIBUTION PRNFILE="DISTRIBUTION.PRN"
FILEI ZDATI[1] = "TRIP ENDS.DBF"
FILEI MATI[1] = "TRAVEL TIMES.MAT"
FILEI LOOKUPI[1] = "FRICTIONFACTORS.DBF"
FILEO MATO[1] = "PERSON TRIP TABLE.MAT",
MO=1-4, NAME='Home_Based','NonHome_Based','School',’EI_Trips’
; Set a maximum number of iterations and convergence criterion
PARAMETERS MAXITERS=99, MAXRMSE=5
; Link the input production and attraction values to internal variables
SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1,
P[2]=ZI.1.P2, A[2]=ZI.1.A2,
P[3]=ZI.1.P3, A[3]=ZI.1.A3,
P[4]=ZI.1.P4, A[4]=ZI.1.A4
; Put the travel time matrix into a working matrix for distribution
MW[20]=MI.1.TIME
; Put the friction factors into a LOOKUP for distribution
LOOKUP LOOKUPI=1,
NAME=FRICTIONFACTORS,
LOOKUP[1]=TRVLTIME, RESULT=HOMEBASED,
LOOKUP[2]=TRVLTIME, RESULT=NONHOME,
LOOKUP[3]=TRVLTIME, RESULT=SCHOOL,
LOOKUP[4]=TRVLTIME, RESULT=EXT_INT,
INTERPOLATE=T
; Distribute trips using a standard gravity model formulation
GRAVITY PURPOSE=1, LOS=MW[20], FFACTORS=FRICTIONFACTORS
GRAVITY PURPOSE=2, LOS=MW[20], FFACTORS=FRICTIONFACTORS
GRAVITY PURPOSE=3, LOS=MW[20], FFACTORS=FRICTIONFACTORS
GRAVITY PURPOSE=4, LOS=MW[20], FFACTORS=FRICTIONFACTORS
ENDRUN

Where the FRICTIONFACTOR.DBF file contains:

General Syntax > Standard control statements > PRINT

PRINT
Formats data items and writes them as a single line to the standard printed output, a file,
or both. Keywords and subkeywords include:
• CFOR M

• CS V

• FILE
m APPEND
m PRINT
m REWIND

• FOR M

• LIS T

• P R IN T O
m PRINT
m REWIND

The size limit of a single data item (or print field) written a PRINT statement is 50,000
characters. This facilitates transferring large amounts of data between files, for example.
Certain print modes, however, restrict the field width — see Defining a numeric print
format, and Defining a character print format.
The program prints one line for each PRINT statement. The length of the printed line is
determined by the formatting of each listed item.
P R IN T k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

CFORM |S| Optional. Default format for subsequently

appearing character strings, except for literal
values, specified with the LIST keyword.
Explicit formats defined for particular items
take precedence. This default format is
effective until the program reads the next
CFORM value. See “Defining a character print
format” on page 76.
Default value is 0.

CSV |?| Optional. Flag indicating whether to print the

output file in CSV format (with commas
between the LIST items). Possible values:
• T — Print in CSV format, with commas
between each LIST item

• F — Do not print in CSV format

Default value is F.
FILE |F| Optional. File where the program writes the
formatted list.
If not specified, the program writes the
standard printed output file. If specified, the
program writes only to the specified file unless
subkeyword PRINT is set to T.
The program writes each formatted list to one
record. Thus, the end-of-file character is at the
end of the last record. You might need to add
a “\n” to the end of the file if you concatenate
the file with another file.

FILE APPEND |?| Optional. Flag indicating whether to overwrite

or append to the specified file. Possible
values:
• T — Append the formatted list to the
specified file.
• F — Overwrite the existing file when
writing the formatted list.
NOTE: If set to T for a file at least once in a
step, then all PRINT statements executed at
that step will append to that file, even if other
statements set APPEND to F.
Default value is F.

FILE P R IN T |?| Optional. Flag indicating whether to write

record to standard printed output in addition to
specified file. Possible values:
• T — Write the record to the standard
printed output in addition to the specified
file
• F — Only write the record to the specified
file
Default value is F.

FILE R E W IN D |?| Optional. Flag indicating whether the program

repositions to the start of the file before writing
contents. Possible values:
• T — Reposition to start of file before
writing formatted list. Program overwrites
previous contents.
• F — Write to the current position in the file.
REWIND is dynamic; therefore, you can control
the rewinding on each PRINT statement.
Default value is F.

FORM |S| Optional. Default format for subsequently

appearing numbers specified with the LIST
keyword. Explicit formats defined for particular
items take precedence. This default format is
effective until the program reads the next
FORM value. See “Defining a numeric print
format” on page 74.
Default value is 10.2.

LIST |KS| Optional. List of items (variables, strings, and

expressions) to format and write to a printed
line. Enclose expressions in parentheses.
Specify no more than 500 items.
 To assign an explicit format to a particular item
in the list, place the format in parentheses next
to the item. The format only applies to that
item. See “Defining a numeric print format” on
page 74 and “Defining a character print format”
on page 76.
For example:
I, J, ITEM1(6), 'abcde', (sqrt(4))
(8C), 'i='(8R), I(L).
Append appropriate subscripts to any array
and matrix variables in the list. If you do not
specify a subscript, the program will supply
one, depending on the variable, program, and
phase. Subscripts may be constants,
variables, or valid expressions. For example:
P[i*3‑1].
NOTE: MW[n] normally implies MW[n][J],
where J is the current value of J.
The PRINT statement recognizes four special
character strings as special control
characters:
• "\n" — new line control
• "\f" — new page control
• "\t" — tab control
• "\\" — ignore new line control
For example, a literal string may contain the
newline character string ("\n" ; lowercase), to
generate a new line at that location (the \n will
not be printed).
As long as a PRINT statement has at least one
LIST item, the program automatically inserts a
newline character prior to the first item. You
can override the automatic newline character
by making the first LIST item a literal string that
begins with the “\\” characters. The \\ will not be
printed, and the printing will continue from the
current line position.
(continued)

LIST NOTE: Because special characters are

(continued) treated as these special controls, problems
can arise when printing strings for a system
path due to the "\" character. For example,
upon reading LIST="C:\n2020\output\"
the program would treat the embedded \n as
the new-line control and insert a new line at the
location. Because the special control is case
sensitive and directory folder names are not,
you can avoid this issue by using
LIST="C:\N2020\output".
In some cases, you might prefer to form
character variables using the string functions
of a COMP character expression and include
those variables in the list. The string functions
might provide some flexibility that is better
suited to the specific task.

PRINTO |I| Optional. Index number of the FILEO PRINTO

file where the program writes this output.
 Setting the Index to 0 will send the output to the
“User Progress Messages” box in Task
Monitor.

PRINTO P R IN T |?| Optional. Flag that indicates whether to write

record to standard printed output in addition to
specified PRINTO file. Possible values:
• T — Write the record to the standard
printed output in addition to the specified
file

• F — Only write the record to the specified

file
Default value is F.

PRINTO R E W IN D |?| Optional. Flag indicating whether the program

repositions to the start of the file before writing
contents. Possible values:
• T — Reposition to start of file before
writing formatted list. Program overwrites
previous contents.
• F — Write to the current position in the file.
REWIND is dynamic; therefore, you can control
the rewinding on each PRINT statement.
Default value is F.
General Syntax > Standard control statements > PRINT > Examples > Examples

Exam ples

• Report a mixture of numeric and character variables.

PRINT FORM=0 LIST=I, J, TOTAL(6.2CS) 'ABCDE'(6.3), FORM=LRCD,
LIST=N, JLOOP_J;

• Use LIST keyword without the control statement name.

LIST= I(6) J(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001, APPEND=T

• Output to file and rewind file at the end.

PRINT FORM=6.0CDLRS LIST=I, J, TOTAL1, TOTAL2 FILE=PRINTFIL.002, REWIND=T

• Interpret sqrt(6) as a variable “sqrt” with form=6

PRINT FORM=LRS LIST= 'I =', I, ' J=', J, ' MW[1]=', MW[1][1], MW[1][2],
MW[1][3],
time+dist/sqrt(xyz), (sqrt(6))

• Output directly to CSV format

FILEO PRINTO[1]=c:\data\mydata.csv
If (I=1) PRINT CSV=T LIST=’I’,’J’,’TIME’,’COST’,’DISTANCE’ PRINTO=1
PRINT CSV=T LIST=I(6.0L),J(6.0L),MW[1](8.4L),MW[2](8.4L),MW[3](5.2L) PRINTO=1
General Syntax > Standard control statements > PRINT > Defining a numeric print format

Defining a numeric print format

You can specify numeric print formats with the FORM keyword or the LIST keyword. For
either keyword, you code numeric print formats as:
w.dBCDELRST

where:
• w — Total field width. Maximum value is 30. If you specify a value greater than 30, the
program uses a width of 30.

• d — Number of digits printed after the decimal point. The program sets d to 0 if the format
begins with w and you do not specify d. Maximum value is 15. If you specify a value greater
than 15, the program uses 15 digits after the decimal point.

• B — Display zero-value numbers as blanks. B overrides D, if both are coded.

• C — Insert commas into numbers.

• D — Display zero-value numbers as a pair of right-justified dashes.

• E — Display numbers in scientific format. Field width must be at least 9, otherwise the
program resets the format to the default value (10.2). The smallest format is 9.1E, which
prints as +1.2E+123. If you set d to 0, the program uses the maximum decimal (w-8). If there
are more post-decimal digits than this maximum value, then the program reduces the post-
decimal digits to w-8. You may specify B or D along with E; the program ignores other
format codes when you specify E.

• L — Trim numbers on the left and print the result beginning with the left-most digit. The
result will be left justified and only as long as required.

• R — Replace a number’s trailing 0s (right side of decimal point) with spaces. The program
replaces zeros after normal formatting and removes decimal point if there is no trailing 0.

• S — Insert a space before the digits of any numbers formatted with L.

• T — Truncate numbers on the left if they cannot fit the field width. Normally, the program
formats such numbers with all asterisks.

All characters are optional. The BCDELRST characters (case insensitive) may be in
any order, but must follow w.d, if w and d are specified. The program ignores characters
other than B and D specified with E. Citilabs recommends that you use a varying length
format unless you must align reported values. The program attempts to accommodate
fixed formats: When values do not fit the specified field width, the program drops
commas, and then reduces the number of decimal places; finally, the program reformats
with scientific notation (1E+ppp), if possible, otherwise the program truncates.
If printing an unknown range of values, specify a width adequate to accommodate all
possible ranges. For delimited output, FORM=16.4LRS is probably adequate. When printing
fixed fields, do not specify L, R, and S.
General Syntax > Standard control statements > PRINT > Defining a character print format

Defining a character print format

You can specify character print formats with the CFORM keyword or the LIST keyword.
For either keyword, you code character print formats as:
w.dCDBTLR

where:
• w — Total field width. Set to 0 to indicate that the field width depends on the string length.
Specify w anywhere in the format string; any number not preceded by a period specifies w.
If a format string specifies multiple w values, the program uses the last value.

NOTE: If the format specifies L, w must be wide enough to accommodate the string.

• d — Number of leading spaces printed (or dashes, if D specified). Specify d anywhere in the
format string; any digit preceded by a period specifies d. If a format string specifies multiple
d values, the program uses the last value. Valid values range from 0 through 15. The
default value is 0.

• C — Center-justify text item. Program applies T first. C overrides L or R.

• D — Print dashes (-) in the d characters preceding the field.

• B — Replace blanks with underscore characters (_).

• T — Trim leading or trailing spaces from text item. If L is specified, delete leading spaces. If
R is specified, delete trailing spaces. If both L and R are specified, delete leading and
trailing spaces and center-justify text item.

• L — Left-justify text item.

• R — Right-justify text item (truncating beginning characters if length exceeds field width).

All characters are optional. The CDBTLR characters (case insensitive) may be in any
order. Citilabs recommends using a varying length format unless you must align
reported values. The program attempts to accommodate fixed formats. When text does
not fit the specified field width, the program truncates.
General Syntax > Standard control statements > PRINTROW

PRINTROW
Formats and prints all cells or selected cells of a matrix row to the main print file.
Keywords include:
• BASE1

• FOR M

• J

• MA XP E R LIN E

• MW

• T IT LE

Row formatting can be quite voluminous; use this statement judiciously.

None of the PRINTROW keywords are “trigger” keys. You must code all on a PRINTROW
statement.
P R IN T R OW k e y wo rd s

Ke y wo rd D e s c rip tio n

BASE1 |?| Optional. Flag indicating row format when

using non-varying print format (that is, FORM
does not contain L). Possible values:
• T — Begin every printed line with a zone
number ending in 1.
• F — Begin each printed line with
appropriate zone number based on
FORM and page width.
MAXPERLINE takes precedence over BASE1:
if MAXPERLINE is specified and is not
modular ten, BASE1 has no effect.
For example:
PRINTROW MW=1-2, 8 FORM=LRD
TITLE='form=LRD'
PRINTROW MW=1-21 FORM=8 BASE1=Y
MAXPERLINE=10

FORM |S| Optional. Default format for row values. See

“Defining a numeric print format” on page 74.
Default value is 20.5LRD
The default value (20.5LRD) provides efficient
reporting while maintaining precision. (The L
in the format value triggers varying-formatted
numbers separated by a single space.)
Three spaces precede zone values ending in
1, providing zone distinction. For printing
traditional integer boxes, set FORM to 7D.
See also “PRINT” on page 69.

J |IP| Optional. List of zone numbers formatted for

printing. Program sets excluded zones (those
 not listed) to zero.
Specify the list as a set of single numbers or
dash-separated pairs of numbers that give a
range. Delimit each number or pair with a
comma.
For example J=1,3-5,10,12-20 selects
zones 1,3 through 5, 10, and 12 through 20 for
printing.
Valid values range from 1 to the number of
zones. Default value is all zones.

MAXPERLINE |I| Optional. Maximum number of columns

printed on a line.
By default, program allows any number of
values to be printed on a line, provided line
length does not exceed the standard page
width. If MAXPERLINE is specified, program
ignores page width.

MW |IP| Optional. List of work matrices to print.

Program prints matrices in ascending order,
regardless of specified order.
Specify the list as a set of single numbers or
dash-separated pairs of numbers that give a
range. Delimit each number or pair with a
comma.
For example MW=1, 3-10, 13 selects work
matrices 1,3 through 10, and 13 for printing.
Default value is no work matrices.

TITLE |S| Optional. Title printed at the beginning of each

MW. The program truncates titles longer than
fourteen characters.
Enclose the value within quotes ('...') or literal
marks ("...").
You may specify only one title per
PRINTROW statement, even if printing
multiple MWs.
By default, the program prints no title.

For neat-appearing reports, Citilabs suggests specifying FORM without the LD, setting
BASE1 to true, and setting M AXPERLINE to some integral of 10.
General Syntax > Standard control statements > PRINTROW > Example

Exam ple
PRINTROW mw=1-2,8 form=LRD title='form=LRD'
PRINTROW mw=1-21 form=6D base1=y maxperline=10
General Syntax > Standard control statements > READ

READ
Switches reading of control statements to a different file. Keywords include:
• FILE

• ne ws tring

• o ld s tring

The format is:

READ FILE=filename, oldstring=newstring, oldstring=newstring, ....

R E A D k e y wo rd s

Ke y wo rd D e s c rip tio n

FILE File to be read. When the end of

file is encountered on that file,
reading of control statements will
continue with the statement
following this READ statement.

ne ws tring Character string that will replace

oldstring in the records in FILE that
contain oldstring. Newstring is case
sensitive; it will be replaced
directly.

o ld s tring Character string (not case

sensitive) that is to be replaced by
newstring. As each record is read
from the file, it is scanned to see if
oldstring exists in it. If it does, the
string is replaced with newstring,
and the scan is continued. If either
oldstring or newstring contains any
special characters it must be
enclosed with '...'. It is suggested
that strings always be enclosed
within '...', but it is not mandatory.

READ statements can be nested up to five levels. A nested READ may not point to a file
that is already in the nest. There is no specific limit to the length and number of
replacement strings. The replacement process is designed to not allow a replacement
string to replace an earlier replacement. Replacements are done in the left to right order
as specified in the READ statement.
READ statement is processed differently, depending on, if it is used in a PILOT script or
as part of a Voyager program, such as MATRIX. When the READ statement is used in a
PILOT script, Voyager checks for the existence of the read file, before starting the run. If
the file did not exist Voyager will fail. Any variables declared within the file will be set
before the start of the run. When READ statement is inside other programs such as
MATRIX, HIGHWAY, etc., the read files are checked and the statements inside the files
are read only during the run.
General Syntax > Standard control statements > READ > Example

Exam ple
READ FILE=BUSLINES, ‘MODE=5’ = ‘MODE=3’
General Syntax > Standard control statements > SORT

SORT
Sorts an array, or series of arrays. Keywords include:
• ARRAY

• N U MR E CS

The format is:

SORT ARRAY=name, name,… NUMRECS=x

S OR T k e y wo rd s

Ke y wo rd D e s c rip tio n

ARRAY |S| Names of the arrays to be sorted. All names

must be declared in an ARRAY statement or
as a DBI AUTOARRAY name. A name may
be preceded by a “+” or “–” sign to indicate
the order of sort to be applied for that array
(within the series of arrays). If a leading +
sign is used, the sign and name must be
enclosed within quotes (for example,
'+myarray'). A “+” means ascending, and
a “–” means descending. If there is no sign
for the first name, ascending is assumed.
Signs need not be specified, but if they are,
a signed array may not follow an array
without a sign. Unsigned arrays are carried
along in parallel with the sorted records. All
the arrays in a SORT statement must be
declared with the same size.
For example, if one wanted to see a sorted
listing of the number of households per
zone, two arrays would be required:
ZONENO and HH. The SORT statement
would be SORT ARRAY=-HH,ZONENO.
This would sort the HH array in a
descending order and keep the ZONENO
array records parallel to it.

NUMRECS |S| Specifies the number of records to sort; it

may be either the name of a variable, or an
integer number. It may not exceed the length
of the arrays.
General Syntax > Standard control statements > SORT > Example 1

Exam ple 1
SORT ARRAY=A,B,C
; Sort on ascending values in A, carry B & C along with A
SORT ARRAY=-A,B,C
; same as above, but sort order for A is descending
SORT ARRAY=-A,'+B',-C,D,E
; sort on descending on A, ascending B, descending C
SORT ARRAY=-A,B,'+C'
; *** ERROR *** signed name (+C) follows unsigned (B)
General Syntax > Standard control statements > SORT > Example 2 (Matrix, Fratar, Distribution, Generation)

Exam ple 2 (M atrix, Fratar, Distributio n, Generatio n)

ARRAY ZONENO=ZONES, HH=ZONES, INCOME=ZONES
.
.
ZONENO[I] = I
HH[I] = ZI.1.HH[I]
INCOME[I] = ZI.1.INCOME[I]
.
.
SORT ARRAY=-INCOME,-HH,ZONENO
LIST=’ Zone Income HHs’
JLOOP
PRINT FORM=8, LIST=ZONENO[J], INCOME[J], HH[J]
ENDJLOOP
General Syntax > Standard control statements > SORT > Example 3 (Network)

Exam ple 3 (Netwo rk)

ARRAY AN=LINKS, BN=LINKS, VMT=LINKS ; NETI must be a binary network
PHASE=LINKMERGE
_L = _L + 1
AN[_L] = A
BN[_L] = B
VMT[_L] = V_1 * DISTANCE
ENDPHASE
/* note:
The User has to keep count of the records entered into the arrays
If links are deleted, the number of entries will be less than the
original number of links.
*/
PHASE=SUMMARY
SORT ARRAY=-VMT, AN,BN, NUMRECS=_L
LOOP _K=1,30 ; only want to see the highest 30
LIST=AN[_K](6),BN[_K](6),VMT[_K](10.2c)
ENDLOOP
ENDPHASE
General Syntax > Voyager Return Codes

Voyager Return Codes

Cube Voyager and all Voyager programs will terminate with a return code. The code
indicates the final status of the run, and is displayed in the print file.
V o y a g e r R e turn Co d e s

Co d e Me a ning

0 Program returned successfully

1 Program returned successfully, with warning

2 Program returned with failure

3 Terminated by user

4 or greater Unspecified error

Should you receive code 4 or greater, Citilabs recommends contacting the Support staff
if you have questions. Please visit http://www.citilabs.com/cubeoutputsupportform.html
or contact generalsupport@citilabs.com.
Pilot Program > Using Pilot program

Using Pilot program

The Pilot program is the basic driver for Cube Voyager application programs, but it is
also a calculator by itself. Most users will use Pilot only to invoke the individual programs
in the order desired. Pilot can check the return codes of the individual programs, invoke
system commands, and even perform complex mathematical computations, either for its
own use or to pass on to the application programs. Through the use of loops and
conditional branching, application programs can be run in any order desired.
This section discusses:
• Output files

• Process

• Statement tokens (%...% and @...@)

Pilot Program > Using Pilot program > Output files

Output files
A project file, pppp.PRJ, is maintained (generated, if necessary) in the working sub-
directory. It contains certain values that help the program to establish unique project
identifications between applications that are run at separate times, and those that might
be run simultaneously in a separate thread in a multitasking environment. Each
application run generates a print and a variable file. The file names are ppppnnnn with
extensions of PRN and VAR, respectively. The pppp portion of the name is the project
prefix obtained from the P argument on the command line. The nnnn is a sequential
number assigned in conjunction with data obtained from the project file. The variable file
will contain a list of all the variables and their values that are in the Vars array when the
program terminates. If there are no specific Vars to be written; this file will be deleted.
Otherwise, the VAR file is renamed to pppp.VAR. Consequently, there will be only one
VAR file for each prefix.

NOTE: If Cube Voyager does not seem to sign on correctly, or indicates strange
filenames or default parameters, most likely the pppp.PRJ file has been corrupted. In
such cases, the remedy is to delete the pppp.PRJ file and restart the process. Cube also
uses .PRJ files, and it is possible for the user to confuse the two and store Viper
configuration information into a Cube Voyager .PRJ, and vice versa.
Pilot Program > Using Pilot program > Process

Process
Recent changes in recommended planning analysis dictate that the simple serial
processing may become inadequate. There will need to be “recursive” applications that
are driven by intermediate results. Ideally, this process could be written into a large
program, and handled as such. But there are disadvantages to that approach (not
discussed in this document). A typical simplified highway application would require that
the following steps be run (after the network and trip end data have been compiled and
checked):
1. Build paths, and add distribution parameters (terminal and intrazonal times).

2. Distribute trip ends according to the paths and user functions.

3. Adjust person trip matrices to account for non-model characteristics, peak period factors,
and auto occupancy.

4. Assign trips to the network.

After the application of a series of programs to accomplish this has been completed, you
would have to verify the results, and decide if the process needs to be rerun with
adjustments, or if the results are satisfactory. The decision process usually will include
some type of numerical analysis. If the results of the analysis are not satisfactory, the
process may be repeated with some adjustments in the input data, or parameters.
Typically, the repeat process is just that: the input data and/or parameters are modified,
and the process is resubmitted.
Cube Voyager simplifies this process by allowing the user to program the process to
adjust the data and/or parameters and automatically repeat the entire process, or just
selected portions of it. In the simple case, if the final speeds are not acceptable, the
process could be looped until speeds come into a reasonable balance, or until it is
decided that a proper balance can not be achieved. That is only a simple portion of the
capabilities of Cube Voyager. As the user learns more of its capabilities, he/she will find
that he/she can control the process in many innovative ways.
The input is comprised of computational, flow control, program, and system statements.
The program begins by reading and editing the Cube Voyager specific statements. The
non-Cube Voyager statements (system statements, and the statements that follow a
RUN statement until its terminating statement) are not edited by Cube Voyager.
When all Cube Voyager statements have been edited for basic syntax, and have been
stored in the control stack, the program builds a list of variables and their values from all
the COMP and LOOP statements and the variables found in the optional VARI file. The
list is stored in the Vars array. It then begins processing the control stack at the
beginning. Each stack statement is executed, and flow branches to the next appropriate
stack statement. When the end of the stack or an EXIT statement is reached, the
program terminates.
Stack statements fall into several categories:
• Computational statements — Cause variable values to be updated. Typical control statements are:
COMP (often invoked by simply: var = )
• — Help to determine which statement is to be performed next. Typical flow
Flow control statements
control statements are:
m
GOTO
m
:LABEL
m
ONRUNERRORGOTO
m
CLEARERROR
m
LOOP BREAK CONTINUE ENDLOOP
m
IF ELSEIF ELSE ENDIF
m
EXIT
The program provides the user with the capability to react to fatal returns from
Citilabs’ programs. When a “RUN PGM=program” statement is executed, the
program sets a return code that indicates what type of messages it issued. The return
code is either 0 (No messages), 1 (Warning messages), 2 (Fatal messages), or 3
(program aborted); this value is stored in a variable named RETURNCODE. If
RETURNCODE is greater than 1, the run is automatically terminated. However, if the
user has set the string variable named ONRUNERRORGOTO to point to a legitimate
label statement in the script, the run will continue at the labeled statement if the return
code is 2.
At the labeled statement, the user can further control what is to happen with the run.
Typically, the user will issue a message, and possibly continue the run. To continue,
the user will have to clear the internal RETURNCODE variable, or subsequent tests of
the run status may cause termination. The CLEARERROR statement is used to reset
the internal return code; it can not be cleared by setting RETURNCODE=. The
CLEARERROR statement also provides a keyword to allow the user to resume
executing script at the point following the RUN statement that caused control to be
switched to the label specified by ONRUNERRORGOTO.
• Program statements — Execute a Cube Voyager program. A program statement always begins
with:
RUN PGM=
• — Program initiates an operating-system command. A system statement is
System statements
one in which the first field begins with a *, and is at least two characters long. Typically,
system statements are used only in pure DOS applications; they will function within
Windows applications, but their use is not recommended.
Pilot Program > Using Pilot program > Process > Example

Exam ple
*COPY *.DAT d:

Warning : Do NOT use a system statement to initiate another Cube Voyager application.
With the capabilities of these statements, the user can cause the stack to be processed
in almost any order desired. With the flow control capabilities, stack segments can be
repeated until desired results are achieved. A typical example would be the repeated
application of a series of programs beginning with trip distribution and progressing
through assignment. If the adjusted speeds from the assignment program differ too
much from the speeds that were used in the distribution process, the series should be
repeated. Another example could be the repeated application of a program with a
slightly different set of parameters, or different input files. It is up to the user to control the
flow.
Pilot Program > Using Pilot program > Statement tokens (%...% and @...@)

Statement tokens (%...% and @...@)

Any statement may contain tokens for substitution. There are two types of tokens: %...%
and @...@.
If a Cube Voyager control statement contains a %...% token, the token is replaced by
the value of the operating system (OS) environment variable between the % signs. If
there is no matching variable name in the environment, the token is unchanged (the
variable name is case insensitive). It should be noted that the environment is a copy of
the environment prior to the execution of Cube Voyager. (NOTE: Any *SET statements
will NOT alter the environment; it is suggested that *SET statements not be used.)
There is not much use for %...%, but there might be times where it can be quite helpful.
The @...@ tokens are processed only when the statement is being processed by a
program called via the RUN PGM= statement. When a program is called, it is provided
access to the .VAR file with the current values from the Cube Voyager Vars array. The
program can update the file when it terminates, but the Vars array is not updated until
Cube Voyager is back in control. If the program reads a control statements that contains
a @...@ token, the token is replaced by the value of the file variable named between the
@ signs. (NOTE: the token is replaced literally at the time the program reads the
statement; a subsequent change to that variable will not alter the value as read.) If the
named variable does not exist in the Vars file, the token is unchanged.
Pilot Program > Using Pilot program > Statement tokens (%...% and @...@) > Example

Exam ple
MAX_LOOP = 20
LOOP loop_cnt=1,20
RUN PGM=program
ID = This is the @loop_cnt@ out of @MAX_LOOP@
ENDRUN
ENDLOOP

In this example, MAXLOOP had to be set because LOOP currently accepts only
constants for it limits. To keep it entirely generic, MAXLOOP could be set into the
environment (SET MAXLOOP=20) prior to launching Cube Voyager; then the sample
could be coded as:
LOOP loop_cnt=1,%MAXLOOP%
RUN PGM=program
ID = This is the @loop_cnt@ out of %MAXLOOP%
ENDRUN
ENDLOOP

The READ statement (see Chapter 3, “General Syntax”) also has capabilities for setting
replacement strings in control statements. READ statements are recognized in all Cube
Voyager applications.
Pilot Program > Control statements

Control statements
This section describes the control statements available in the Cube Voyager Pilot
program.

Co ntro l s ta te me nt D e s c rip tio n

*command Perform an OS system command with OS

window minimized

BREAK Break out of current loop

CLEARERROR Clear a run error to allow continued

processing

COMP Compute variables

CONTINUE Continue to end of loop

CONVERTMAT Convert Matrix files

COPY ... ENDCOPY Copy records to a file

DOWNLOAD Download specified file(s) from a URL

EXIT Exit current phase

FILEI Specify input file with existing variable

values

FILEO Specify output file PRINTO[#]=fname

GOTO Jump to a specific control statement

IF ... ELSEIF ... ELSE ... Standard IF block

ENDIF

LOOP ... ENDLOOP Setup a user loop

NEWPAGE Control new-page processing

ONRUNERRORGOTO Jump to a specified :label when an error

condition is encountered

PARAMETERS Specify basic parameter values

PRINT Print variable values

PROMPT Pause execution and wait for user input

REPORT Turn reports on/off

RUN ... ENDRUN Runs a specified program

SENDMAIL Send mail with attachments based on

conditions of the run

SLEEP Pause program execution for specified

amount of time
Pilot Program > Control statements > *command

*command
A statement whose first field begins with a *, and is more than 2 characters long, is
considered as a command for the operating system. Cube Voyager will invoke the
COMSPEC processor to execute the command. The command will return a code that
will be stored in the ReturnCode variable. It is the user’s responsibility to test
ReturnCode, since Cube Voyager does not know the meaning of the return codes. It
should be noted that some system commands return 0, even if they are unsuccessful.
For example: “COPY source dest” will return a 0, even if one of the filenames is
illegitimate.

NOTE: The *command will be executed in a minimized command window. This prevents
disruption of the display, allowing other tasks to be performed more comfortably while
the script is running. If it is required that the command window appear on the display,
use the alternate **command rather than *command; for example, '**pause' rather than
'*pause'. The '**' approach will be appropriate if the command requires some interaction
with the user, or perhaps if it displays some progress which the user always wants to be
able to view.
Pilot Program > Control statements > *command > Example

Example
*DEL ABCD*.TMP
*IF EXIST OLD.NET DEL OLD.NET

Or:
**DEL ABCD*.TMP
**IF EXIST OLD.NET DEL OLD.NET
Pilot Program > Control statements > BREAK

BREAK
BREAK can be used to break out of a LOOP ENDLOOP block. It must be within a LOOP block.
When BREAK is encountered, flow immediately branches to the statement following the
appropriate ENDLOOP statement. The contents of the LOOP variable are not altered.
Pilot Program > Control statements > BREAK > Example

Exam ple
LOOP i=1,3
IF (condition)
statements
ELSE
BREAK ; get out of loop
ENDIF
ENDLOOP
Pilot Program > Control statements > CLEARERROR

CLEARERROR
Keywords include:
• COD E

• R E S U ME

The CLEARERROR statement is used primarily in conjunction with the variable

ONRUNERRORGOTO. When the statement is encountered, it automatically resets the
internal error code value to 1 and the resume switch to false. It is then the user’s
responsibility to set those values with the keywords.
CLE A R E R R OR k e y wo rd s

Ke y wo rd D e s c rip tio n

CODE |I| Internal error code is reset to this

value. Can be a value of 0,1.

RESUME |?| If the value is True (1), and the program

detects that it is in an error recovery
process set by ONRUNERRORGOTO,
control will switch to the statement
following the RUN statement that
caused control to switch to the
recovery process.
Pilot Program > Control statements > CLEARERROR > Example

Exam ple
ONRUNERRORGOTO = 'MYERROR'
:STEP1
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR

:STEP2
RUN PGM=….
ENDRUN

:STEP3
RUN PGM=
ENDRUN

:MYERROR
PRINT LIST='Special Message'
CLEARERROR CODE=0 RESUME=T
; At this point, control will return to :Step2
Pilot Program > Control statements > COMP

COMP
var=expression
ID=expression
Lambda=expression, etc.
COMP statements compute numeric values and store the value into the var on the left
side of the equals sign. Results can be either numeric or character strings (obtained
when literal text '...' or text functions are in the expression). It is not permissible to
change the mode of a variable during an application. A variable must be defined before
it can be used within an expression; it must have appeared as a var= in a statement
prior to the expression. The program is designed with this check, to ensure that an edit
can be made prior to beginning processing. It could be a big waste of time, if, in the
middle of a complicated loop, the program had to abort because it couldn’t find a variable
at that time. However, this causes a problem with using variables returned from a Cube
Voyager program invoked by the RUN PGM= statement. Cube Voyager does not know
the mode of the variable and can not edit it prior to actual application. To avoid this
problem, Cube Voyager automatically assumes any variable that contains a dot (".")
within its name as numeric.
• Varis the variable that is to have a new value computed for it. If the variable matches a
name in the Vars array, the result will be updated after the COMP is completed. If it does
not exist in the Vars array, it is added as a new variable that can be referenced in
subsequent control statements.

• ID is a special case variable that allows the user to compute a new ID. Because of the
potential conflict with the Cube Voyager system ID control statement, ID may not be the
first keyword on a COMP statement. If the result of the expression is not numeric, then the
resulting character string is copied to the system ID area. In any event, ID then becomes a
working variable.

• is a special case variable, and Lambda must also be a variable within the expression.
Lambda
When this form is specified, the program solves the expression for various values of
Lambda between 0 and 1.0 in hopes of determining a Lambda that will result in a value of
0. The logic for searching is as follows:
m
Set a min and max Lambda (0 and 1.0)
m
Divide the difference between min and max into equal intervals.
m
Solve for all the interval points between min and max.
m
Find the interval that surrounds 0; if none do, it is an error. If more than one interval
surrounds 0, the solution is ambiguous, and it is an error.
 m
Reset the min and max Lambdas to the interval points that contain 0.
m
If the interval size is not within the accepted tolerance, repeat steps 2-5.
m
When the interval size is within tolerance, perform a straight line interpolation to zero.
Store the results into Lambda.
This is not a perfect solution, but if the expression is appropriate (does not contain
any transverse slopes, and crosses zero one time), a Lambda between 0 and 1 will
be found. The current process works on a bisecting principal for developing the test
ranges and uses an tolerance interval of 0.000001. For obvious reasons, an
expression that contains Lambda as an expression multiplier without any other terms,
will always result in Lambda = 0. A division by Lambda will cause program failure
when Lambda is tested for 0.
The statement need not have COMP, it may begin directly with var=.
Pilot Program > Control statements > COMP > Example

Exam ple
COMP i=matrix.time_to_cbd/100 + sqrt(loop)
i=3, j=6, k=9, ijk=1*100+j*10 + k
Lambda = 1.2 - lambda * ...
COMP ID='This is a new ID for loop' + str(loop_cntr,3,0)
Pilot Program > Control statements > CONVERTMAT

CONVERTMAT
Command for converting matrix files between the Cube native 'TPP' format and the
open matrix format 'OMX'. More information on the open matrix format can be found at
https://github.com/osPlanning/omx
CON V E R T MA T k e y wo rd s

Ke y wo rd T ype D e s c rip tio n

FROM |F| Name of the file that contains

the matrix that needs to be
converted.

TO |F| Name of the file that contains

the converted matrix.

T O>COMP R E S S ION |I| Level of compression to be

applied for the output file.
Valid values are 0 to 9. Higher
the value, higher the rate of
compression and slower
conversion speeds. Default is
0.A good compression/speed
balance seems to be 4.

T O>FOR MA T |S| Format of the output matrix file.

Can be either 'TPP' or 'OMX'.
Default is 'OMX'
Pilot Program > Control statements > CONVERTMAT > Example

Exam ple
CONVERTMAT FROM="C:\Cubetown\Base\PERSONTRIPS.MAT"
TO="C:\Cubetown\Base\persontrips.omx" FORMAT=OMX COMPRESSION=0
Pilot Program > Control statements > CONTINUE

CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements.
When CONTINUE is processed flow immediately branches to the ENDLOOP statement in a
LOOP ENDLOOP block. It must be within a LOOP block.
Pilot Program > Control statements > CONTINUE > Example

Exam ple
LOOP i=1,3
IF (condition)
statements
ELSE
CONTINUE ; jump to ENDLOOP
ENDIF
ENDLOOP
Pilot Program > Control statements > COPY ... ENDCOPY

COPY ... ENDCOPY

Keywords include:
• FILE =filename

Copies records from the input file to a specified file.

All the records following the COPY statement, up to, but not including, its matching
ENDCOPY statement are copied. The copied records and the ENDCOPY are not processed
by Cube Voyager. If there is no matching ENDCOPY, the end of file is considered as the
ENDCOPY. The actual COPY takes place when the COPY statement is processed (it can be
bypassed or repeated). If there are any COPY or ENDCOPY statements between this COPY
statement and its ENDCOPY, they are copied as a data records to the designated file. The
copy process does not scan the records for special features (/*...*/ %...% etc.).
If there is no filename, or the filename is invalid, the error is not diagnosed until the COPY
statement is actually processed. For that reason, it may be better to place most COPY
statements near the beginning of the input file. The primary use of COPY is to allow the
user to include small data files within the input file, so that they can be always be
associated directly with the control statements.
If the COPY fails, ReturnCode is set to 255; an IF statement can be used to test the
results.
COP Y a nd E N D COP Y k e y wo rd

Ke y wo rd D e s c rip tio n

FILE |F| Name of the file onto which the

records are to be copied. Must be
an acceptable name for the
operating system.
Pilot Program > Control statements > COPY ... ENDCOPY > Example

Exam ple
COPY FILE=temp1; copy lookup file for HIGHWAY
.
.
ENDCOPY
COPY FILE=temp2 ;copy with imbedded COPY
... will be copied to temp2
COPY FILE=temp3 ; " " " " "
... " " " " "
ENDCOPY " " " " "
ENDCOPY signals that the prior record was last
IF (ReturnCode==255) ...
Pilot Program > Control statements > DOWNLOAD

DOWNLOAD
Keywords include:
• CLE A R FILE O

• FILE O

• URL

Downloads a file from the internet from the specified URL.

D OW N LOA D k e y wo rd s

Ke y wo rd D e s c rip tio n

CLEARFILEO |?| <1> is a switch to indicate if the local file should be cleared
prior to beginning the download.
If the file is cleared and the download fails for some reason
then the file will not exist on the local machine. If
CLEARFILEO=0 then the local file will be overwritten by a
successful download but if the download fails then the original
local file will remain in its original form.

FILEO |S| Local path and file name for the download.
Example:
'C:\CITIDOWNLOADS\myfile.dat'

URL |S| URL for the target file to download.

Example:
URL=
'ftp://www.citilabs.com/outgoing/yourfile.dat'
The site address component (ftp://www.citilabs.com) is not
case sensitive but the path and filename component is
(/outgoing/yourfile.dat).
Pilot Program > Control statements > EXIT

EXIT
Terminates the program.
Pilot Program > Control statements > EXIT > Example

Exam ple
IF (expression) EXIT
Pilot Program > Control statements > FILEI

FILEI
Keywords incude:
• V A R I=filename

Specifies an input file for Pilot variable initialization. This statement is executed before
any step is run, no matter where it is specified in the script.

NOTE: See “FILEI” on page 50 for general information about FILEI and for important
limitations when using Application Manager.

FILE I k e y wo rd s

Ke y wo rd D e s c rip tio n

VARI |KF| Specifies the name of the file which is to

be read to initialize variables. If not
specified, no file is read. The data
extracted from the file are stored in the
Vars array. If duplicate variables are
encountered, the latest one read
prevails. Each record from the file
contains two fields: a variable name,
and its value. The fields may be
separated by any number of space(s),
with, or without, an = sign. The names
may be any reasonable variable
names.

The statement need not contain the FILEI control word; it may begin directly with VARI.
Normally, VARI is not used; it is used only if there are many variables to be initialized.
This could be the case if the application is the continuation of a previous application. A
var output file will always be written at the termination of the application.
Pilot Program > Control statements > FILEI > Example

Exam ple
VARI=XXXX.VAR
Pilot Program > Control statements > FILEO

FILEO
Keywords include:
• P R IN T O[#]=filename

Specifies an output file for the PRINT PRINTO capability when printing from Pilot.
FILE O k e y wo rd

Ke y wo rd D e s c rip tio n

PRINTO |KF| Specifies the name of the file where the

output from the PRINT statement is to be
directed

The statement need not contain the FILEO control word; it may begin directly with PRINTO.
Note, all PRINTO index numbers must be unique throughout the script. When adding a
Pilot box in Application Manager and linking a file to the PRINTO file box, you must ensure
that the index numbers used do not overlap with prior PRINTO indices from prior Pilot
steps.

NOTE: When processing the first step, the Pilot program opens all the PRINTO files
specified in any script. Therefore, statements intended to create files in folders that do
not already exist will fail.
Pilot Program > Control statements > FILEO > Example

Exam ple
FILEO PRINTO[1] = "C:\Data\My File.CSV"
IF (L1=1)
PRINT CSV=T LIST='ITER','DIFF','P_DIFF',
PRINTO=1
ELSE
PRINT CSV=T, FORM=L, LIST=L1,CONV.DIFF(8.0L),CONV.P_DIFF(6.2L),
PRINTO=1
ENDIF
IF (ABS(CONV.P_DIFF)<0.05 & L1>1) BREAK
*COPY Trips_by_Mode.mat LAST.MAT/Y
Pilot Program > Control statements > GOTO

GOTO
Jumps immediately to a named statement.
GOTO label

When GOTO is processed, flow immediately branches to the target statement, named
“:label.” Each GOTO statement must have an associated :label statement. Use care when
the :label statement is within a different IF or LOOP block. The target statement must begin
with a semicolon (:).
Pilot Program > Control statements > GOTO > Example 1

Exam ple 1
GOTO hwybuild
GOTO :hwybuild
Pilot Program > Control statements > GOTO > Example 2

Exam ple 2
GOTO hwybuild
:hwybuild

IF (expression) GOTO :hwybuild ;It is permissible to go backwards.

Pilot Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF

IF ... ELSEIF ... ELSE ... ENDIF

Performs certain operations based on conditions.
There are two forms of this control statement:
• A single statement:
IF (expression) statement

• A block of statements:
IF (expression)
ELSEIF (expression)
ELSE (expression)
ENDIF

You must predefine any expression variables in an earlier COMP VAR statement. (The
program automatically defines any variables not predefined, but with a dot (.) in their
name as numeric variables.)
You may nest but not overlap IF ... ELSEIF ... ELSE ... ENDIF blocks. They may not overlap
LOOP ... ENDLOOP blocks.

You may append the following control statements to a single IF statement:

• BREAK

• COMP

• CONTINUE

• EXIT

• GOTO
Pilot Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF > Example

Exam ple
; Single IF examples:

IF (matrix.time_to_bcd < 200000) simple statement

IF (expression) EXIT

; Typical IF block:

IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) )

statements
ELSEIF (loop_cntr > 10)
statements
ELSEIF (loop_cntr > 5 && diff.time < 32)
statements
ELSE
statements
ENDIF
Pilot Program > Control statements > LOOP ... ENDLOOP

LOOP ... ENDLOOP

Initializes a variable, compares the variable to a constant, and branches to the statement
following the LOOP block if the comparison fails.
LOOP blocks may be nested, but they may not overlap other LOOP blocks or IF blocks.
LOOP Var = Begin, End, Incr
Statement set
ENDLOOP

where:
• Var is the required user-specified name of the loop-control variable. The module does not
protect the value of Var during the loop; computation, program, and other LOOP statements
may alter the value of Var.

• Begin is the constant value to which the module initializes Var. You must specify a value.

• End is the constant value that the module compares Var to when processing the ENDLOOP
statement. You must specify a value.

• Incr is the constant the module adds to Var before processing the ENDLOOP statement.
If the result of the comparison is true, the program branches back to the statement
following the LOOP statement. If it is false, control is passed to the statement following
ENDLOOP.
Processing of the ENDLOOP statement depends on the value of Incr:
• If Incr is positive, when the value of Var is less than or equal to End, the module goes to
the statement following LOOP, otherwise the module goes to the statement following
ENDLOOP.

• If Incr is negative, when the value of Var is greater than or equal to End, the module goes
to the statement following LOOP otherwise the module goes to the statement following
ENDLOOP.

The module tests the ENDLOOP condition (without incrementing the variable value) when
initializing the loop-control variable. If the test fails, the module does not perform any
statements within the LOOP block.
Pilot Program > Control statements > LOOP ... ENDLOOP > Example 1

Exam ple 1

Executes the code within the LOOP block 10 times.

LOOP iter=1,10
.
.
ENDLOOP
Pilot Program > Control statements > LOOP ... ENDLOOP > Example 2

Exam ple 2

A nested loop, with the innermost loop executing twice for each value of variable xyz:
10,8,6,4,2.
LOOP xyz=10,1,-2
LOOP abc=1,2
.
.
ENDLOOP
ENDLOOP
Pilot Program > Control statements > NEWPAGE

NEWPAGE
Controls the printed output when the program invokes an external process. Keywords
include:
• a fte rp g m

• a fte rs y s

• b e fo re p g m

• b e fo re s y s

All NEWPAGE variables are Boolean items that require a true or false type of value. Once
a variable is set, it remains in force, until a new value is encountered. The ...sys
variables can help provide cleaner output when a system command is performed. The
page counter will not be adjusted for the system output. The ...sys variables are ignored
if the system command contains a redirection ”>” symbol.
N E W P A GE k e y wo rd s

Ke y wo rd D e s c rip tio n

afterpgm |?| Starts a new page after a PGM returns.

aftersys |?| Starts a new page after a system

command.

beforepgm |?| Sets the line counter so that the invoked

PGM will start on a new page.

beforesys |?| Starts a new page before performing the

system command.

Example:
NEWPAGE beforepgm=y afterpgm=n beforesys=y aftersys=y
Pilot Program > Control statements > ONRUNERRORGOTO

ONRUNERRORGOTO
ONRUNERRORGOTO is a string variable that can be set to point to a legitimate label
statement in the script. Use this feature to react to fatal returns from Citilabs’ programs.
When a “ RUN PGM=program” statement is executed, the program sets a return code
that indicates what type of message the program returned on closing. The codes
returned are:

Co d e D e s c rip tio n

0 = No The job ran to completion successfully.

messages

1 = Warning The job ran to completion but generated one or

messages more warning messages.

2 = Fatal The job failed to run to completion and generated

messages on or more fatal error messages.

3 = Program The job was aborted by user conditions with the

aborted ABORT statement.

This code value is stored in a variable named RETURNCODE.

If the RETURNCODE value is greater than 1, the run is automatically terminated.
However, if the user has set the string variable named ONRUNERRORGOTO to point to a
legitimate LABEL statement in the script, the run will continue at the labeled statement if
the return code is 2. See “GOTO” on page 103 for a description of defining a LABEL.
At the labeled statement, the user can provide additional statements to further control
what is to happen with the run. Typically, the user will set up a PRINT statement to write a
message to the run print file or use a PROMPT statement to issue a message, and
possibly request a response from the user to continue the run. The user may now also
send an e-mail or text message to report results based on a run error. See “SENDMAIL”
on page 118 for an example of using these statements together.
To continue the run, the user will have to clear the internal RETURNCODE variable, or
subsequent tests of the run status may cause termination. The CLEARERROR statement is
used to reset the internal return code; it can not be cleared by setting RETURNCODE=.
The CLEARERROR statement also provides a keyword to allow the user to resume
executing script at the point following the RUN statement that caused control to be
switched to the label specified by ONRUNERRORGOTO.
It is suggested that the script statements to be processed on the return of an error
message be placed at the end of the run script and “jumped” to with the
ONRUNERRORGOTO Statement. Note that an EXIT statement should be used just prior to
the :label referenced by the ONRUNERRORGOTO. Placing an EXIT statement prior to the
:label will allow the program to terminate without executing the statements for the error
condition when the script runs successfully without any errors. Refer also to the
CLEARERROR statement (see “CLEARERROR” on page 95).
Pilot Program > Control statements > ONRUNERRORGOTO > Example 1

Exam ple 1
RUN PGM=MATRIX
ENDRUN

At this point the job will terminate because there was an error in the Matrix program (no
operations).
Pilot Program > Control statements > ONRUNERRORGOTO > Example 2

Exam ple 2
ONRUNERRORGOTO = 'MYERROR'
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR if the MATRIX step fails
RUN PGM=….
ENDRUN
EXIT ; if program gets to this point then exit, no errors were encountered
:MYERROR
PRINT LIST='Special Message'
; Run will terminate from here with a final completion code of 2
Pilot Program > Control statements > ONRUNERRORGOTO > Example 3

Exam ple 3
ONRUNERRORGOTO = 'MYERROR
:STEP1
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR if the MATRIX step fails
:STEP2
RUN PGM=….
ENDRUN
:STEP3
RUN PGM=
ENDRUN
EXIT ; if program gets to this point then exit, no errors were encountered
; or all errors cleared
:MYERROR
PRINT LIST='Special Message'
CLEARERROR CODE=0
GOTO STEP3
Pilot Program > Control statements > ONRUNERRORGOTO > Example 4

Exam ple 4
ONRUNERRORGOTO = 'MYERROR'
:STEP1
RUN PGM=MATRIX
ENDRUN
;At this point control will transfer to :MYERROR if the MATRIX step fails
:STEP2
RUN PGM=….
ENDRUN
:STEP3
RUN PGM=
ENDRUN
EXIT ; if program gets to this point then exit, no errors were encountered
; or all errors cleared
:MYERROR
PRINT LIST='Special Message'
CLEARERROR CODE=0 RESUME=T
; At this point, control will return to :Step2
Pilot Program > Control statements > PARAMETERS

PARAMETERS
Specifies basic parameter values for the Pilot run. Keywords include:
• MA XS T R IN G

• V A R D E CIMA L

<…> is the program default value.

P A R A ME T E R S k e y wo rd

Ke y wo rd D e s c rip tio n

MAXSTRING |KI| Specifies the maximum length to use for

all string variables. Versions 3.0, and
lower, had a maximum length of 127
characters, and violations of this length
were not detected. This proved to be too
short for some users who were
developing strings with considerably
longer path names in them. Now the user
can specify what the longest string
variable is to be (up to 1000 characters). If
one has many string variables, a large
value could cause excessive RAM to be
allocated. (We have seen users’ jobs
with more than 200 string variables.)
Specifying a reasonable length will help
to preserve RAM, and if a string really
needs to be longer than 250, this
parameter must be specified. If a variable
is computed to exceed this length, a fatal
error message will be issued.
Default value is 255. Maximum is 1000.

VARDECIMAL |I| Specifies the decimal place precision for

numeric variables passed between Pilot
and individual program modules, using
the LOG statement and @...@ tokens
(see “Statement tokens (%...% and
@...@)” on page 91). This will allow the
user to increase the precision of the
passed values as needed.
If the parameter is specified multiple
times, the value from the last occurrence
will be used. This value also controls the
decimal precision of variable values
logged in each program module so that
small values can be passed back to
Pilot.
Default is 5. Minimum is 0, maximum 15.
Pilot Program > Control statements > PRINT

PRINT
Formats and prints a line of information.
The standard Cube Voyager PRINT statement can be used. Please see “PRINT” on
page 69.
Pilot Program > Control statements > PRINT > Example 1

Exam ple 1
LIST= ITER(6) TIMEPERIOD(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001
PRINT FORM=6.0CDLR LIST= ITER, TIMEPERIOD,TOTAL1,TOTAL2 FILE=PRINTFIL.002
Pilot Program > Control statements > PRINT > Example 2

Exam ple 2
PRINT PRINTO=1 FORM=6.0CDLR LIST=ITER, TIMEPERIOD, TOTAL1, TOTAL2
Pilot Program > Control statements > PROMPT

PROMPT
Keywords include:
• ANSW ER=

• QU E S T ION =

• W A IT =

Poses mid-run questions that can alter the flow of the job. When encountering a PROMPT
statement, the program lists a question (defined by the QUESTION keyword) and the
possible answers (defined by the ANSWER keyword) and waits for a response. The
response must select one of the answers. The program will not continue until a proper
selection is made. The ANSWER number is returned to Pilot in the variable named
ReturnCode, which the user can test via an IF statement.
The use of the keyword PRNFILE on the RUN statement allows the user to redirect the
print file for any job steps. When the PROMPT dialog box opens, the user can peruse the
output from any of the previous step(s) to decide how to respond to the question.
P R OMP T k e y wo rd s

Ke y wo rd D e s c rip tio n

ANSWER |S5| Possible answers. The same rules about

quotes in QUESTION also apply here.
There may be up to 5 ANSWERs.

QUESTION |KS| Question to prompt the user with. Enclose

with quotes ‘…’ or "…"; if it contains any
delimiters, it must be within quotes.

WAIT |R| Number of seconds to wait before

automatically continuing using ANSWER
[1] as the response. If the user makes a
choice before WAIT seconds have
expired, the program will not continue until
a valid choice is made. 0< WAIT < 50000
When running in command line mode, as
soon as a valid number is entered, the
program continues with that selection
without requiring a press of the Enter key.
To gain more response time in command
mode, enter an invalid key; the program
will then wait until a valid number is
entered, and WAIT is disabled.
When in windows mode, a dialogue box is
opened, and the user can make a choice
and then click on the OK button to proceed.
Once any choice is made, WAIT is
disabled.

When Pilot is launched a Windows dialog box opens, and the user responds by
selecting a button.
Pilot Program > Control statements > PROMPT > Example

Exam ple
PROMPT QUESTION=’What do you want to do?’,
ANSWER=Continue, ; 1
‘Break out of Loop’, ; 2
ABORT ; 3
IF (ReturnCode==3) abort
IF (ReturnCode==2) break
RUN PGM=MATRIX PRNFILE=myfile.txt
.
.
ENDRUN
PROMPT QUESTION=’Examine myfile.txt to determine response to’,
ANSWER=’Sum Too High’,
‘Sum Too Low’,
‘Sum Acceptable – Get Out of Loop’
IF (RETURNCODE==3) break
Pilot Program > Control statements > REPORT

REPORT
Keywords include:
• S T A CK

• T R A CE

• VARS

R E P OR T k e y wo rd s

Ke y wo rd D e s c rip tio n

STACK |?| Writes the internal stack. This is mostly

used for program debugging, but can
be useful for relating TRACE
information to internal notation. STACK
is static; if set to true, writes occur at the
beginning of stack processing.

TRACE |K?| Controls the listing of the stack

statements as they are processed.
TRACE can be turned on and off at any
time, thus controlling the amount of
output as desired. Each statement will
be listed with an internal number, the
control statement name, and, in most
cases, additional information. TRACE
is a trigger key.

VARS |?| When set to true, the program lists the

current variables and their values from
the VARS array.
Pilot Program > Control statements > REPORT > Example

Exam ple
REPORT Vars=y
REPORT Trace=y ; turn stack tracing on
REPORT Trace=n ; turn stack tracing off
Pilot Program > Control statements > RUN ... ENDRUN

RUN ... ENDRUN

Loads and executes a program.
• CT LFILE =name

• MS G

• P A R A ME T E R S

• P GM=name

• P R N FILE =name

• R E D IR E CT IN

• R E D IR E CT OU T

Pilot loads and executes the program specified by PGM . Pilot attaches any control
statements between the RUN and ENDRUN command to the specified program. Only the
specified program will read and edit these statements.
ENDRUN signals the end of the RUN statement. Though optional, Citilabs recommends
always using ENDRUN. A system command (*....) or another RUN statement also signals
the end of a RUN statement.
You can disable a RUN statement by changing it to !RUN. However, a !RUN statement
requires a corresponding ENDRUN. You can also disable a RUN statement by placing the
statement in a null block (/* .... */) or by using a GOTO statement.
Pilot expects to load a Cube Voyager program; the associated DLL and TDF files must
be directly accessible. If you are running a non–Cube Voyager program, you may use
additional keywords. The program name may be a standard OS file name (path is
optional, but is recommended for non-TRIPS programs). The program may be a TRIPS
program, a Cube-related program, a client-developed program to run in accordance with
Citilabs specifications, or a standard OS executable RUN file.
R U N k e y wo rd s

Ke y wo rd D e s c rip tio n

CTLFILE |F| Optional. File be used as the program’s standard input. If

CTLFILE is not specified, it is assumed that the data
follows the RUN statement (up to, but not including, the
next ENDRUN statement), and the those records are
copied to a temporary file. If there are no data records
following the RUN statement, CTLFILE is ignored.

MSG |S| Optional message that can be printed when the program
runs. For readability, Citilabs recommends 100
characters or less.

PARAMETERS |SV| Optional. Parameters that the program expects to find on

the invoking command line. If a parameter will contain
any special characters (comma, space, dash, math
 operator, semi-colon), enclose the parameter within
quotes (‘…’ or "…"). If a parameter is to contain quotes, the
quoted parameter must be enclosed by the opposite
quote.
For example, if the program requires ‘abc’ to be passed
to it, it should be coded as "’abc’", or if it requires "def
ghi", it should be coded as ‘"def ghi"’. Parameters may
be coded as a series of values, or, in most cases, as
one string of many parameters enclosed within one set
of quotes.

PGM |S| Program to be run. Pilot determines if it is a Cube

Voyager program by searching for both “program.DLL”
and “program.TDF” in the directories discovered in the
following order:
• Directory from which Pilot was loaded
• Current directory
• Windows system and then the Windows directories

• Directories that are listed in the PATH environment

variable
If the program is not located that way, it assumes that it is
a non-Cube Voyager program and tries to locate it by
applying a somewhat different set of criteria to determine
the full name for the program, and to locate the directory
where it resides.
If program has no file extension and the last character is
not a dot (.), append “.exe” to program.
If program contains path information (has a \ or :), use that
path
If program does not contain path information, locate the
program by searching the directory from which Pilot was
loaded, and then the directories as registered with the
operating system
If program*.exe is found, look in that directory for the
latest version of the program by assuming program#.exe
and use the highest # file. Thus, if name.exe, name1.exe,
and name3.exe are all found, name3.exe will be
assumed.

PRNFILE |F| Optional. File where the program expects to write its
standard system print output. PRNFILE will be ignored if it
is determined that a TRIPS program is being run.

REDIRECTIN |?| Optional. Switch to indicate that CTLFILE is to be directed

into the program.

REDIRECTOUT |?| Optional. Switch to indicate that the program is to direct

its output to PRNFILE, if PRNFILE is also specified.

If it is determined that a TRIPS program is being run (by the presence of &FILES OPRN
keyword in the CTLFILE), PRNFILE, REDIRECTIN, and REDIRECTOUT are ignored.
The RUN statement is designed to allow easy integration of non-Cube Voyager
programs directly in line with a standard run and to have the “printed” output of the
program directly incorporated into the standard Cube Voyager print file. There may be
programs whose basic operations will not allow this type of integration. In those
situations, it is possible that the use of the Pilot * statement will allow the direct running of
the command.
The RUN statement for non-Cube Voyager programs generates a system command that
is structured and executed based upon the following decision table.
• If PGM is a TRIPS program (contains &FILES OPRN=):
pgm ctlfile parameters >tprn

• If PGM is not a TRIPS program:

RDI RDO p rnfile Ge ne ra te d c o mma nd

F F T pgm ctlfile prnfile

parameters

F F F pgm ctlfile parameters

F T T pgm ctlfile parameters

>prnfile

F T F pgm ctlfile parameters

>tprn

T F T pgm prnfile parameters

<ctlfile

T F F pgm parameters <ctlfile

T T T pgm parameters <ctlfile

>prnfile

T T F pgm parameters <ctlfile

>tprn

NOTE:

1. If ctlfile has no length, it is not placed on the command line

2. tprn is a temporary file which is copied to the Cube Voyager print file.

3. DRI/RDO = redirectin/redirectout
Pilot Program > Control statements > RUN ... ENDRUN > Examples

Exam ples
RUN PGM=program parameters=datain, dataout
Command: Path\program.exe datain dataout

RUN PGM=abc.exe ctlfile=datain prnfile=dataout parameters=’abc’

Command: Path\abc.exe datain dataout abc

RUN PGM=ME ctlfile=datain parameters="/m=20" "/demo"

Command: Path\MVESTM70.EXE datain /m=20 /demo

RUN PGM=ME ; ctlfile follows this statement; will be copied to tfile

Command: Path\MVESTM70.EXE tfile

RUN PGM="c:\util\pkzip.exe" parameters="junk.zip t*.",

"-v –c", prnfile=zip.txt, redirectout=t
Command: c:\util\pkzip.exe junk.zip t*. -v –c >zip.txt

RUN PGM=MATRIX ; standard Cube Voyager run

Pilot Program > Control statements > SENDMAIL

SENDMAIL
Immediately sends an e-mail. Keywords include:
• A T T A CH ME N T S

• CC

• FR OM

• ME S S A GE

• P A S S W OR D

• P OR T

• S MT P S E R V E R

• S U B J E CT

• TO

• U S E R N A ME

Use SENDMAIL to transmit the status of a job or job step to a recipient. The keywords
SMTPSERVER, FROM , TO, and SUBJECT must be specified; the others are optional. E-mail
messages can also be sent as text messages to a cell phone.
S E N D MA IL k e y wo rd s

Ke y wo rd D e s c rip tio n

ATTACHMENTS |S| List of file names sent as attachments. There is a

maximum of 1000 attachments.

CC |S| E-mail address(es) for copied recipient(s).

FROM |S| E-mail address to be sent as the return

MESSAGE |S| List of individual lines to send in the message

area of the e-mail. Each string is a separate line.
There is a maximum of 1000 messages.

PASSWORD |S| Password for the account specified in

USERNAME, if the SMTP server requires secure
logon.
If coding your script in Cube text editor, you can
insert the password value with the Insert
ribbon command then selecting Password for
email . Cube opens a Password Entry dialog
box, which t allows you to mask the password
for security.
PORT |I| <25> is the TCP PORT number. The typical
SMTP server uses PORT number 25.

SMTPSERVER |S| Name of the send-mail server. An example might

be: smtp.sbcglobal.yahoo.com

SUBJECT |S| Subject of e-mail.

TO |S| E-mail address(es) of the recipient(s). Separate

multiple recipient addresses with a comma. You
can also send mail as a text message to a phone
and account that supports text messaging.
Examples of cell phone provider messaging e-
mail addresses are:
• T-Mobile: {phone#}@tmomail.net

• Sprint:
{phone#}@messaging.sprintpcs.com

• Verizon: {phone#}@vtext.com
Check with his/her cell phone service provider to
verify the appropriate address.

USERNAME |S| User name for mail account, if the mail SMTP
server requires logon.
Pilot Program > Control statements > SENDMAIL > Example

Exam ple

Using SENDMAIL with ONRUNERRORGOTO, RETURNCODE, and CLEARERROR to generate e-

mail with attachments for various conditions
;========================================================================
ONRUNERRORGOTO='ONERROR' ; set LABEL to jump to if an error occurs

StepName='Step 1 - Network'
RUN PGM=NETWORK
NODEI=DTWNNOD.DBF, LINKI=DTWNLNK.DBF
NETO=DTWNTPP1.NET
ZONES=24
ENDRUN

StepName='Step 2 - Network'
RUN PGM=NETWORK
NODEI=xDTWNNOD.DBF, LINKI=DTWNLNK.DBF
NETO=DTWNTPP1.NET
ENDRUN

SENDMAIL SMTPSERVER='smtp.yourname.com',
FROM='ken@yourname.com',
TO='ken@yourname.com,jill@yourname.com',
CC='The Boss<boss@yourname.com>',
Subject='Email from Voyager, Run Completed, No Error',
Message='Voyager Run Completed',
'There is no run error',
ATTACHMENTS='DTWNTPP1.NET'

Exit ; if no errors then this step gets executed and terminates the run

:ONERROR ; if an error occurs the processing jumps to this location

rcode=str(returncode,2,0) ; returncode will have value=0,1,2,3

SENDMAIL SMTPSERVER='smtp.yourname.com',
FROM='ken@yourname.com',
TO='ken@yourname.com',
Subject='Email from Voyager, Run Error',
Message='There is a run error, returncode:',rcode,
'On Step ',StepName

; Also text message a cell phone

SENDMAIL SMTPSERVER='smtp.yourname.com',
FROM='ken@yourname.com',
TO='5106635200@messaging.sprintpcs.com',
Subject='Email from Voyager, Run Error',
Message='There is a run error, returncode:',rcode,
'On Step ',StepName

; If the error happens on step 2, ignore the error, resume the run
if (StepName='Step 2 - Network')
CLEARERROR resume=t code=0
endif
Pilot Program > Control statements > SLEEP

SLEEP
Pauses program execution for a specified amount of time. Keywords include:
• T IME =duration

S LE E P k e y wo rd

Ke y wo rd D e s c rip tio n

TIME |RS| Duration, in seconds, of the pause. Users

can specify TIME as a constant numeric
value or a variable. TIME does not
accept an arbitrary expression.
Pilot Program > Control statements > SLEEP > Example

Exam ple
SLEEP TIME = 5

; Pauses execution for five seconds

Pilot Program > Examples and FAQ

Examples and FAQ

This section contains examples using the Pilot program, along with a link to Frequently
Asked Questions.
• Example 1: Typical application, with no logic

• Example 2: Loop

• Example 3: Additional logic

• Frequently asked questions

Pilot Program > Examples and FAQ > Example 1: Typical application, with no logic

Example 1: Typical application, with no logic

/* Example 1: Typical application, with no logic. */

RUN PGM=NETWORK
. data for NETWORK to build a network
ENDRUN
RUN PGM=HIGHWAY
. data for HIGHWAY to build LOS files
ENDRUN
RUN PGM=DISTRIBUTION
. data for DISTRIBUTION to distribute trip ends
ENDRUN
RUN PGM=MATRIX
. data for MATRIX to combine and factor matrices
ENDRUN
RUN PGM=HIGHWAY
. data for HIGHWAY to load trips to highway network
ENDRUN
RUN PGM=NETWORK
. data for NETWORK to analyze assignment
ENDRUN
Pilot Program > Examples and FAQ > Example 2: Loop

Example 2: Loop
This example is a little more complicated. All the RUN statements would have statements
following them (including an ENDRUN statement). They are excluded, so that process
can be presented more briefly.
LOOP iter=1,5
COMP ID='This is iteration' + str(iter,2,0)
RUN PGM=NETWORK
RUN PGM=HIGHWAY
RUN PGM=DISTTRIBUTION
RUN PGM=MATRIX
RUN PGM=HIGHWAY
RUN PGM=NETWORK
ENDRUN
IF ( NETWORK.RESULT <= 0.02) BREAK ; criteria already satisfied
ENDLOOP
Pilot Program > Examples and FAQ > Example 3: Additional logic

Example 3: Additional logic

This example introduces more capabilities, including branching with GOTO statements,
page breaks with NEWPAGE, and output via REPORT .
LOOP iter=1,5
COMP ID='This is iteration' + str(iter,2,0)
RUN PGM=NETWORK
RUN PGM=HIGHWAY
RUN PGM=DISTTRIBUTION
RUN PGM=MATRIX
RUN PGM=HIGHWAY
RUN PGM=NETWORK
ENDRUN
IF ( NETWORK.RESULT <= 0.02)
GOTO Early_Converge
ELSEIF (NETWORK.RESULT <= 0.04)
LIST=' exit early ' + str(iter,2,0) + ' iterations’
GOTO TRANSIT
ENDIF
ENDLOOP
LIST='Speeds did not converge'
EXIT
:Early_converge
LIST='Convergence after ' + str(iter,2,0) + ' iterations'
:TRANSIT
ID=BEGIN TRANSIT PROCESSING
REPORT vars=y ; list current variables
Newpage BEFORESYS=y, AFTERSYS=y
; copy transit files to ramdisk
*COPY d:\transit\neta\altx*.* r:
RUN PGM=PUBLIC TRANSPORT
read r:altx01.set
ENDRUN
IF (RETURNCODE > 0) EXIT
*COPY r:trnnet d:\transit\neta
Pilot Program > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see Pilot and general syntax in Chapter 17, “Frequently Asked Questions.”
Fratar > Using Fratar

Using Fratar
Fratar distribution is the process of modifying a matrix of values based upon a set of
production and attraction factors for each of the zones in the matrix. The process is a
relatively simple iterative one:
In the first iteration, each row in the matrix is factored according to its production factor.
At the end of the iteration, the row totals will match the target row values, but the column
totals will most likely not match their targets.
In the second iteration each column in the modified matrix is factored according its
attraction factor. At then end of the iteration, the column totals will match the target
column values, but the row totals may not match their targets.
This process continues for some number of iterations; the row and column totals should
converge towards the target totals. When the criteria for convergence is met, the
process is complete.
A complete convergence (target row and column totals obtained for all zones) can be
obtained only if the target grand control totals for rows and columns are the same. The
program makes adjustments to guarantee that the target grand totals do match. It is
possible that the user input values and specifications can preclude obtaining matching
totals. In such cases, the program will fatally terminate.
This section discusses:
• Specifying target values

• Controlling target totals

• Convergence — Iteration control

• Multiple purposes
Fratar > Using Fratar > Specifying target values

Specifying target values

There are several typical ways in which the control totals can be specified: direct values,
growth factors (explicit and implicit), or some combination of both. All specifications are
via the SETPA control statements. An array of production values (Ps) and an array of
attraction values (As) are maintained for each purpose. To simplify this description, the
term “value” will be used to mean either direct values or growth factors. There must be a
set of production values and attraction values for each matrix to be factored. They are
input to the program via P, A, PGF, and AGF expressions. If direct values are to be
input, the P and A expressions are used. If growth factors are to be input, the PGF and
AGF expressions are used. Direct values and growth factors can be mixed for a
purpose, but a complete understanding of the SETPA statement is necessary.
Each of the keyword expressions is computed for an array of values for all zones. P[1] =
ZI.1.HBWP2000 would cause the program to simulate the expression:
JLOOP J=1,ZONES
P[1][J] = ZI.1.HBWP2000[J] .
ENDJLOOP

Similarly, A[]=, PGF[]=, and AGF[]= expressions are computed for corresponding
arrays. To provide the capability of mixing P and PGF for a purpose, the SETPA
statement may include the basic INCLUDE and EXCLUDE filter specifications. If either,
or both, of these filters are specified on a SETPA statement, they apply to all
expressions on that statement. To specify P and PGF for the same purpose, separate
SETPA statements are used; each would have its own zonal filter set. If the sets
overlap, the latest SETPA values replace any prior values. If the final value for a P or A
is 0, the program revises it to a growth factor of 1.0.
Fratar > Using Fratar > Specifying target values > Example 1

Exam ple 1
SETPA P[1]=ZI.1.HBWP2000, A[1]=ZI.1.HBWA2000 INCLUDE=1-500
SETPA PGF[1]=ZI.2.EXTW/2 AGF[1]=PGF[1] INCLUDE=501-550

In this example, the values for zones 1-500 would be the direct values obtained directly
from the ZI.1.HBWP2000 array, and the values for zones 501-550 would be the growth
factors obtained from the ZI.2.EXTW array (divided by 2).
In most cases the values will be obtained from ZDATI (zonal data) files, or LOOKUP
functions, but that is not an absolute requirement. Standard numerical expressions (J
being the only viable variable that could be included) are used to compute the values.
Sometimes, it is desirable to input specific values.
Fratar > Using Fratar > Specifying target values > Example 2

Exam ple 2
SETPA P[1]=5000 INCLUDE=255 ;input a specific value
SETPA A[1]=sqrt(J/2+25**3.5) ;would be possible, but weird.

A special feature of these expressions is that if the result is less than zero, it is not
stored. After all SETPA P,A,PGF, and AGF expressions are processed, the program
performs a zonal (I) loop, obtaining the matrix values for each purpose. The matrices are
obtained by solving the SETPA MW[]= expressions. Again, the INCLUDE and
EXCLUDE filters are employed, but care must be exercised, if they are specified. The
MW expressions are array notation, but applied for each I zone. Therefore the filters will
apply to both the I and J zones.
Fratar > Using Fratar > Specifying target values > Example 3

Exam ple 3
SETPA MW[1]=... INCLUDE=1-500
; will compute only the I=1-500 to J=1-500 portion of the matrix.
Fratar > Using Fratar > Controlling target totals

Controlling target totals

After processing the input matrix, the target totals for any growth factor values can be
fully determined (value = gf * input). Next, the program adjusts the values to insure that
the P and A totals match for each purpose. There are several options for adjustment;
they are specified by the use of the CONTROL keywords on the SETPA statement.
There may be a CONTROL specification for each purpose, and if the CONTROL for
any purpose is specified more than one time, the latest value prevails. If no CONTROL
is specified it defaults to PA. The valid values for CONTROL are: P, A, PA, PL, AL, and
PAL. The meanings are:

V a lue D e s c rip tio n

P The P totals control; all values in the A array will be

factored so that the A totals will match the P totals.

A The A totals control; all values in the P array will be

factored so that the P totals will match the A totals.

PA All values in both the P and A arrays will be

factored so that their totals will match the average
of the initial totals.

Sometimes only certain zones are to be modified, and the remainder of the zones are to
be kept constant. The program keeps track of the zones that are eligible for modification
by noting which zones have target values that differ from the input value by more than
one. If the letter “L” is appended to any of the CONTROL values, it indicates that the
modifications are Limited to only the zones that have change. Use of the this feature
can, in some cases, lead to a situation where a matrix grand total can not be properly
computed. If that is the case, the program will fatally terminate.

V a lue D e s c rip tio n

PL The P totals control. The changed zones in the A

array will be factored so that the final A total will
match the P total.

AL The A totals control. The changed zones in the P

array will be factored so that the final P total will
match the A total.

PAL The values in P array for zones that have P

changes, and the values in the A array for zones
that have A changes will be factored in such a
manner that the final P and A totals match the
average of the initial P and A totals.

It is impossible to modify any cell, column, or row of the input matrix that has zero to
begin with. If a target value is specified for a zone that initially had no total, a warning
message is issued. Traditionally, some modelers would scale a matrix by a value
(usually 10, or 100), and then fill in all empty cells with one. This is not necessarily a
good, or bad, solution. But, because of the potential problems associated with this
approach, zero accountability is not included in this program directly. If the scaling
scheme is to be applied, a prior application of the Matrix program can be used to scale
and fill in a matrix in any desired manner. It could also be achieved by setting the
SETPA MW expression to: max(1,mi.n.n*10).
Fratar > Using Fratar > Convergence — Iteration control

Convergence — Iteration control

A concern is when to stop the iterating process; there are several ways to control it. The
user can specify a maximum number of iterations, so that no matter how the
convergence is progressing, the process will not exceed that number. After each
iteration, the program computes an RMS error value based upon the integer differences
between the computed and target row or column totals. After odd iterations, column total
differences are checked, and after even iterations, row differences are checked. If the
RMSE value is less than the MAXRMSE parameter value, the solution is achieved.
It is believed that this process will eventually reach convergence. But if, due to some
unforeseen conditions, the RMSE value begins to oscillate, the program detects the
oscillation, and terminates the process at the minimum RMSE. If there are multiple
matrices being factored, they may reach optimum solutions at different times. If this
happens, the “solved” matrices are held steady, and the others continue to be
processed.
A small example of this process:
A fte r Ite ra tio n 1: R MS E = 22.87

Zo ne 1 2 3 T o ta l

1 57 24 19 100

2 64 106 30 200

3 102 61 137 300

Total 223 191 186 600

Target 240 200 160 600

As dictated by row factoring, the row totals are correct. But, the column totals do not
quite match the target. Another iteration is performed, and the results appear as:
A fte r Ite ra tio n 2: R MS E = 7.94

Zo ne 1 2 3 T o ta l

1 61 25 16 102

2 69 111 26 206

3 110 64 118 292

Total 240 200 160 600

The column totals are now on target, but the row totals are not quite on target.
This process goes on, back and forth, until either the RMSE drops to the MAXRMSE
level, or the number of iterations reaches the MAXITERS value. In this example, the final
solution is reached after 5 iterations (MAXRMSE=0.01 and MAXITERS=10).
A fte r Ite ra tio n 5: R MS E = 0

Zo ne 1 2 3 T o ta l

1 60 25 16 102

2 70 110 26 206

3 113 64 118 292

Total 240 200 160 600

All values are shown to the nearest integer and thus may not total exactly. Internally, the
values are carried with more precision.
Fratar > Using Fratar > Multiple purposes

Multiple purposes
The number of purposes is determined by the highest P, A, PGF, AGF, or MW index
found on any SETPA control statement. The program assumes that there will be
purposes from one, monotonically, through that highest index. (FRATAR allows up to 20
trip purposes.) The distribution is performed prior to entering the main Matrix program I-
loop. When the main I-loop is processed, MW[1] through MW[highest purpose] are
initialized with the final matrices from the Fratar distribution. After the factoring process is
complete, a standard Matrix program I-loop is performed.
Fratar > Control statements

Control statements
All the standard Matrix statements are valid in Fratar, and a few additional ones are
available. Fratar is a subset of the Matrix program. This section only describes the
differences between the Matrix and Fratar control statements. For descriptions of other
control statements see Chapter 9, “Matrix Program.”
Fratar statements not in Matrix:
• SETPA

Fratar keywords not in Matrix:

• PARAMETERS MAXITERS = MAXRMSE=

• REPORT ACOMP= PCOMP=

This section describes:

• PARAMETERS

• REPORT

• SETPA
Fratar > Control statements > PARAMETERS

PARAMETERS
Sets general parameters. Keywords include:
• MA T OE V E R Y

• MA XIT E R S

• MA XP U R P S

• MA XR MS E

• ZON E S

In addition to the standard Matrix parameters (see “PARAMETERS” on page 638), you
may specify the parameters described here.
P A R A ME T E R S k e y wo rd s

P a ra me te r D e s c rip tio n

MATOEVERY |K?| Switch that can force the program

to write output matrices for every
iteration, instead of waiting until
the last iteration.
For large systems, not writing
output matrices for each iteration
saves considerable computer
time, but forces another
processing iteration to write the
matrices after reaching
convergence.
Writing output matrices for each
iteration increases run times for
each iteration, but prevents the
program from having to run
another iteration to write the
output matrices after reaching
convergence.
If you anticipate that there will be
many iterations before reaching
convergence, set this switch to
false. If you anticipate that the
process will involve only a few
iterations, set this switch true.

MAXITERS |KI| Maximum number of iterations. If

the MAXRMSE criterion is met, the
number of iterations actually
performed could be less than this
value.
The default is 9, and the max is
99.

MAXPURPS |KI| Number of purposes to process

in this application. FRATAR allows
up to 20 trip purposes.
MAXPURPS is not required,
because the program will
 determine the value from the
detection of the values on the
SETPA statements. But, if this
value is provided, and it conflicts
with the SETPA statements, a fatal
message will be issued.

MAXRMSE |KR| Cutoff criteria. If the RMSE for a

purpose does not exceed this
value, a solution is assumed for
the purpose.
The default is 10, and the
minimum is 0.

ZONES |KI| Highest zone number to process.

If the number of zones cannot be
ascertained from the project file
or from any binary input matrices,
ZONES must be provided, or the
value will default to 100. If present,
this value controls the
application. Normally, there will
be an input matrix file, so this
keyword should not be required.
Fratar > Control statements > REPORT

REPORT
• A COMP

• P COMP

In addition to the REPORT keywords available for Matrix, the following are also available
for Fratar:
R E P OR T k e y wo rd s

Ke y wo rd D e s c rip tio n

ACOMP |KIP| Requests report comparing computed

to target attractions for specified
purposes. The report is in a format that
is similar to the MARGINS report. The
values are reported as nearest integers
(without decimal places). Only the
purposes specified by the keyword are
reported, but they are reported for all
odd iterations.

PCOMP |KIP| Same as ACOMP, but refers to

productions, and refers to only even
iterations.
Fratar > Control statements > REPORT > Example

Exam ple
ACOMP=1-3,5 ;request reports for the specified purposes
Fratar > Control statements > SETPA

SETPA
Establishes base productions and attractions. Keywords include:
• A

• A GF

• CON T R OL

• E XCLU D E

• IN CLU D E

• MW

• P

• P GF

The SETPA statement is required; if it is not included, the program will fatally terminate.
These statements define how the production and attraction factors are to be obtained,
and how many purposes are to be processed. There should be a P[]= and A[]= and
MW[]= expression for every purpose beginning with 1 and continuing, monotonically,
until all purposes are defined. (FRATAR allows up to 20 trip purposes.) The highest
index encountered establishes the number of purposes.
If there are any holes in the purpose scheme, the program will issue a warning
statement.
The Ps and As are computed from the expressions that are supplied. In most cases, the
expression will simply point to a ZDATI file variable. Complex expressions are allowed,
but the use of any variables in the expression could cause unpredictable results. In a
purpose where the Ps and As are the same for each zone, it is acceptable to set the Ps,
and then set the As equal to the Ps. The SETPA expressions are computed in the order
in which they appear in the control stream, and they are computed only one time -- prior
to the first iteration. For each array, the expression is solved in a loop of J=1-Zones, and
the results are stored in the A,P,MW [n][J] cells. The keywords may not have a zone
index in the SETPA statement.
If the same purpose is referenced more than one time, the subsequent values will
replace the prior values. Duplication of purposes might be helpful if values for different
zones for a purpose are to be obtained from different sources, or if different
INCLUDE/EXCLUDE filters are to be used (different SETPA statements must be used for
different filters).
S E T P A k e y wo rd s

Ke y wo rd D e s c rip tio n

A |NV| Expression solved to set the target

 attraction totals for the indexed
purpose.

AGF |NV| Expression solved to set the target

attraction growth factors for the
indexed purpose. The final totals
are obtained by multiplying the
growth factors by the initial input
matrix totals.

CONTROL |SV*| String indicating how to adjust final

target totals to enable
convergence. The possible values
are:
P
Production totals control; As will
be adjusted
A
Attraction totals control; Ps will
be adjusted
PA
Both Ps and As will be adjusted
to the average of the P and A
totals.
PL
Same as P, but only As in
adjustable zones will be
adjusted
AL
Same as A, but only Ps in
adjustable zones will be
adjusted
PAL
Same as PA, but only
adjustable zones will be
adjusted

EXCLUDE |IP| Processed the same as EXCLUDE

on COMP statements (see “COMP”
on page 49). If it is used, the loop
will not be processed for any zones
in the list. EXCLUDE filtering follows
any INCLUDE filtering.

INCLUDE |IP| Processed the same as INCLUDE

on COMP statements (see “COMP”
on page 49). If it is used, the loop
will not be processed for any zones
not in the list. INCLUDE filtering
precedes any EXCLUDE zones.

MW |NV| Expression solved for each zone

during the first iteration. The result is
the matrix row for that zone. Usually,
this expression will be a single
variable name such as MI.n.n, but
that is not required.

P |NV| Expression solved to set the target

production totals for the indexed
purpose.
PGF |NV| Expression solved to set the target
production growth factors for the
indexed purpose.
Fratar > Control statements > SETPA > Example

Exam ple

Using single CONTROL keyword:

SETPA PGF[1]=zi.1.xifac, AGF[1]=PGF[1], MW[1]=mi.1.1 CONTROL=PAL

Using multiple CONTROL keywords:

SETPA P[1]=(ZI.1.P1) A[1]=(ZI.1.A1) MW[1]=1 CONTROL[1]=A
SETPA P[2]=(ZI.1.P1) A[2]=(ZI.1.A1) MW[2]=1 CONTROL[2]=P
SETPA P[3]=(ZI.1.P1) A[3]=(ZI.1.A1) MW[3]=1 CONTROL[3]=PA
Fratar > Examples and FAQ

Examples and FAQ

Items in this section include:
• Example 1: Matrix and Fratar

• Frequently asked questions

Fratar > Examples and FAQ > Example 1: Matrix and Fratar

Example 1: Matrix and Fratar

The following two steps (MATRIX and FRATAR) set up and run the small example used
in the Introduction (see Using Fratar) to illustrate convergence. It is a good example of
different ways to “play” with MATRIX. The MATRIX step generates a 3 zone matrix, and
the FRATAR step modifies it.
RUN PGM=MATRIX
ZONES=3
MATO=3ZONE.MAT,MO=1
IF (I==1) MW[1][1]= 57 MW[1][2]= 24 MW[1][3]= 19
IF (I==2) MW[1][1]= 64 MW[1][2]=106 MW[1][3]= 30
IF (I==3) MW[1][1]=102 MW[1][2]= 61 MW[1][3]=137
ENDRUN

RUN PGM=FRATAR
MATI=3ZONE.MAT
MATO=3ZONEF.MAT,MO=1
LOOKUP NAME=TOT,LOOKUP[1]=1,RESULT=2,LOOKUP[2]=1,RESULT=3,
R='1 100 240',
'2 200 200',
'3 300 160'
MAXRMSE=0.01 MAXITERS=10
SETPA P[1]=TOT(1,J) A[1]=TOT(2,J) MW[1]=MI.1.1
ACOMP=1,PCOMP=1
MARGINS=1
ENDRUN
Fratar > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see Fratar in Chapter 17, “Frequently Asked Questions.”
Highway Program > Using the Highway program

Using the Highway program

This section provides helpful information about using Cube Voyager’s Highway
program. Topics include:
• Highway introduction

• Highway program control statement overview

• Functions and built-ins

• Getting started with assignment

• Path-based tolls

• Multiple user class assignment using generalized cost functions

Highway Program > Using the Highway program > Highway introduction

Highway introduction
The Highway program now supports junction or intersection constrained assignment as
well as the typically link based capacity constrained assignment. Junction-constrained
assignment requires the coding of the junction or intersection movements and controls.
The descriptions below refer to link based traffic assignment. Refer to Chapter 7,
“Intersection Modeling” for a detailed description of intersection modeling and the data
requirements.
The Highway program now can write the full path file from an assignment run including
full results from every iteration. This makes many forms of path based analysis directly
accessible in Cube without having to rerun the assignments with specific commands in
the scripts. See the description of PATHO in “FILEO” on page 221 and “PATHLOAD” on
page 270; also refer to “Highway path display” on page 265 of the Cube Base
Reference Guide for information about path-based analysis in Cube.
The Highway program’s primary function is to assign trips to highway network links. A
highway network, zonal matrices, zonal data, junction data and turn penalties can be
input, and a loaded network, new matrices, turning volumes, final junction delay and
reports can be output. There are basic default operations, but the user can control much
of the process
A typical assignment program builds paths based upon link costs (impedances) and
assigns trips to those paths for each origin zone. After all origin zones have been
processed, link costs are updated based upon the level of congestion on each link.
Then the entire path and assignment process is repeated. This process continues until
some criteria for termination is reached. The volumes from each iteration are combined
to form a weighted assignment. Different criteria are used to determine when enough
iterations have been performed. Almost all of the operations follow a fixed pattern, and
are driven by basic parameters. Various options are usually available to provide the user
with additional outputs. Select link analysis is a major tool for most users. This process
“traps” the trips that meet the select link criteria, and usually writes them to output
matrices.
The Highway program provides the same capabilities as a traditional assignment
program, but functions somewhat differently. There are only a few automatic operations,
and global parameters are used sparingly. The program operates by processing in
various phases. In each phase the program performs certain specific operations, and
optionally processes a stack of operations provided by the user for that phase.
In addition to phase operations, the user can enter FUNCTION statements (in the form of
numerical expressions) that are to be performed in place of default functions at certain
times by the program.
• Using the FU N CT ION control statement, the user may calculate the cost, congested time, or
volume (at the current iteration) of a link. See “FUNCTION” on page 245.

• is also ideal for modeling multiple user class assignments (such as regular vs.
FU N CT ION
HOV traffic). For more information and an example, see “Multiple user class assignment
using generalized cost functions” on page 166.

For normal processing, there must be a way of computing certain required values for
each link. If there is no automatic way for the program to determine these values, the
user must supply the process to obtain them. Normally, the values are computed directly
from the variables in the input network, but since there is no fixed format of the network,
the required variables may not be present. In that case, the LINKREAD phase can be
used and formulated to provide these values. The underlying assumption is that path
building and capacity restraint are based upon a generalized cost on each link. In most
cases, the cost is time. There are several ways to obtain the free flow time (T0), and the
initial path time (T1). The hierarchy of the processes to obtain T0 and T1 is outlined
below, in the description of the LINKREAD phase.
The best advice is that the network should contain a variable that can be used directly
for T0, or that it contains variables so that DISTANCE and SPEED information can be
easily obtained. If the variables DISTANCE, LANES, and SPDCLASS are in the
network, T0 can be computed from the DISTANCE and the values from the SPDTAB
speed table.
If the network is the result of conversion from a TRANPLAN network, it will usually
contain variables named DISTANCE, TIME1, and CAPACITY. DISTANCE and TIME1
are usually in hundredths of miles and hundredths of minutes, respectively. CAPACITY
is normally the total capacity for the link. TIME1 is the starting time for assignment, and is
not necessarily a true T0 (free flow time). If such a network is used directly, the
LINKREAD stack should contain the following statements:
DISTANCE=LI.DISTANCE/100 ; not absolutely necessary
T0 = LI.TIME1/100
C = LI.CAPACITY * CAPFAC ; factor to get on same scale with trips

In reality, it would be better to rename and scale the variables appropriately during the
network conversion process, so that it is not necessary to remember to deal with them in
the Highway program.
TRANPLAN converted networks will be in nearly the correct format, but the user should
also be aware to scale the variables to the correct values. If the network distance is
properly scaled, T0 will be computed from the DISTANCE, SPDCLASS, LANES, and
the SPEED portion of the SPDCAP tables.
The major phases in the process are:
• SET UP — Optionally, initialize basic user arrays and processes

• LIN KR E A D — Obtain required values for each link

• ILOOP — Build paths and assign trips from each origin zone

• ADJUST — Examine iteration results, test for convergence and adjust link values for next
iteration

• — Optional phase where user can specify their own convergence rules and
CON V E R GE
stopping criteria

These phases are processed even if the user does not explicitly specify any controls for
them. However, if there is no explicit ILOOP phase, the program will terminate with an
appropriate message. The phases are specified by using PROCESS
PHASE=PhaseName statements; for simplistic purposes, most users simply use the
short form: PHASE=PhaseName without the PROCESS control word. A PHASE is
closed with either an ENDPROCESS or an ENDPHASE statement. These two
statements are interchangeable. A PHASE will also be closed if an new PROCESS
PHASE=PhaseName or PHASE=PhaseName statement is encountered prior to an
ENDPROCESS or ENDPHASE.
For more information about phases, see “Phases” on page 170.
Highway Program > Using the Highway program > Highway program control statement overview

Highway program control statement overview

There are several types of control statements in the Highway program:
• Definition statements — Define static processes. Examples include:
m
FILEI and FILEO which define the input and output data
m
FUNCTION
m
LOOKUP
m
PARAMETERS

• Computational statements — Update variable values. Examples include:

m
COMP
m
PATHLOAD
m
SET

• Reporting statements — Accumulate or dynamically display values. Examples include:

m
PRINT
m
PRINTROW
m
REPORT

• Flow control statements — Set statement order. Examples include:

m
GOTO
m
:label LOOP BREAK CONTINUE ENDLOOP JLOOP ENDJLOOP
m
IF ELSEIF ELSE ENDIF
m
EXIT

For details about control statements, see “Control statements” on page 199.
Highway Program > Using the Highway program > Functions and built-ins

Functions and built-ins

This section lists built-in variables, arrays, and functions that can assist in performing
most desired operations:
• Built-in variables

• Built-in arrays

• Built-in functions

• Built-in variables available in the CONVERGE phase

• Built-in functions available in the CONVERGE phase

NOTE: Thenames are not case sensitive, but capitalization may make them a bit more
meaningful.

You can also use FUNCTION statements to enter single expressions for computing certain
values. See “FUNCTION” on page 245.
Highway Program > Using the Highway program > Functions and built-ins > Built-in variables

Built-in variables
Only the variables with a * may be stored into by the user; the others are reserved.

V a ria b le D e s c rip tio n

_SKIPTOI In the ILOOP phase, jump to the specified

zone immediately. Its value is checked at the
end of the current I. If specified, Cube Voyager
sets I to that value. The specified value must
be greater than the current I. See “Example of
_SKIPTOI” on page 157.

C* Capacity used in congestion expressions;

DISTANCE* Link distance expressed in miles or

kilometers.

I Current row’s zone (ILOOP).

ITERATION Current iteration number.

J Column index, usually 1, and varies (1-Zones)

for MW[] and JLOOPs.

LAMBDA Lambda value computed for this iteration; do

not be reset.

LASTITERATION Last iteration indicator, usually set to the

MAXITERS parameter

LINKCLASS* Class of the current link; you can modify in

LINKREAD.

LINKNO Link number (available during any implied link

loops)

LOWCNT Result of LOWEST().

NODES Number of nodes.

NUMLINKS Number of links.

PROJECTLINK Zero value means do not include in

equilibrium; you can modify in LINKREAD.

SPEED* Link speed.

T0* Link free flow time.

T1* Initial iteration time.

V* Total link volume used in ADJUST phase; by

default, it is the sum of all VOL[] sets.

ZONES Number of zones.

Highway Program > Using the Highway program > Functions and built-ins > Built-in arrays

Built-in arrays
There are arrays that can be referenced with […] to indicate a specific value from the
array. Most times, the link-oriented arrays need not be referenced with an index; the
default [linkno] is supplied by the program. The names with a * can be stored into, the
others are reserved.

A rra y D e s c rip tio n

A A-nodes for each link.

B B-nodes for each link.

COST Link cost values.

DIST* Link distances.

LI.name Link values from the network.

LW.name* User generated values for links

(currently accepts numeric values
only).

MW[]* A work matrix; see “COMP” on

page 202 for more details.

TIME* Link times.

VOL[]* Link volumes.

Highway Program > Using the Highway program > Functions and built-ins > Built-in functions

Built-in functions
These built-in functions are described in “COMP” on page 202.

Func tio n D e s c rip tio n

ROWSUM(mw) Row total.

ROWCNT(mw) Number of cells whose values != 0.

ROWMIN(mw) Minimum value in the row.

ROWMAX(mw) Maximum value in the row.

ROWAVE(mw) Average cell value where value!=0.

ROWFIX(mw) Convert mw to integer values (start at column

intrazonal + 1).

ROWFAC(mw,fac) Factors the row by fac.

ROWADD(d,s1,…,sn) Add matrices MW[s1], MW[s2], . . . MW[sn] to

matrix MW[d].

ROWMPY(d,s) Multiply mw[d] by mw[s].

ROWDIV(d,s) Divide mw[d] by mw[s].

LOWEST(mw,#) Sum of lowest valued cells in a matrix row.

LOWCNT Actual number of cells found by LOWEST

function.

SPEEDFOR(lanes,class) Speed from spdtab.

CAPACITYFOR(lanes,class) Capacity from captab.

PATHTRACE(value) Sum of link values (Time, Cost, LI. or LW.) on

path for I to J.

LINKNUM(a,b) Link number for link a-b.

CHECKNAME(Name) Check if a matrix table/ zonal file field/ link

attribute exists. If it does not exist, the function
returns a zero. If it exists, the return code is a 2
digit number in the format of {t}{s}, defined as
follows:
{t} is type
0=single variable
1=vector
2=user function
3=work matrices
4=user function
5=user function
6=vector with constant index and no
default index
7=multidimension array, no default
 index
{s} is storage size
1=numeric size
2=string
e.g. 1=numeric variable, 2=string variable,
11=numeric array, 12=string array

GETVALUE(Name {, Get a numeric value from a matrix table/ zonal

DefaultValue}) file field/ link attribute. This function is used
along with the CheckName function.
CheckName checks the existence of a matrix
table/ zonal file field/ link attribute and
GetValue extracts the value from it. They are
used to avoid model run crash due to non-
existence or invalid value of a matrix table/
zonal file field/ link attribute in the input files.
• MI.x.x must be used with an explicit
JLOOP block where the default index of I
and J will be set to the correct origin and
destination.
• ZI.x.x must be used inside the ILOOP
Phase so that the default index I will be
set to the correct origin zone.
• LI.x and LW.x must be used inside
the LINKREAD Phase, ADJUST Phase
or within a LinkLoop block where the
default index LinkNo will be set to the
correct link.
PROCESS PHASE=ILOOP
JLOOP
IF CheckName(‘MI.1.HBW’) hbw
= GetValue(‘MI.1.HBW’)
ENDJLOOP
IF
(CheckName(‘ZI.1.SFDUS’)>0)
SF = GetValue(‘ZI.1.SFDUS’)
ENDPROCESS

PROCESS PHASE=LINKREAD
IF(CheckName(‘LI.Capacity’)>0)
C = GetValue(‘LI.Capacity’)
ENDPROCESS

GETMATRIXROW(Name,MW# Load a MI matrix row into a MW. This function

{, must be used inside the ILOOP Phase and
DefaultValue})DefaultValue}) name must be a MI.x.x name. The return
code can be the following:
0=matrix row loaded successfully
1=invalid name or other errors, the default
value is used
2=invalid name or other errors and no
default value is supplied, program
terminating
PROCESS PHASE=ILOOP
nn=GetMatrixRow(‘MI.1.NHB’,2,1)
ENDPROCESS
Highway Program > Using the Highway program > Functions and built-ins > Built-in variables available in the CONVERGE
phase

Built-in variables available in the CON VERGE phase

There are various variables available for testing in the CONVERGE phase. See
“CONVERGE phase” on page 192 for examples of usage.
Co nv e rg e p ha s e v a ria b le s

V a ria b le D e s c rip tio n

GAP The GAP for the current iteration. Must be

indexed GAP[] for previous iterations.

RGAP The RELATIVEGAP for the current iteration.

Must be indexed for previous iterations.

AAD The AAD for the current iteration. Must be

indexed for previous iterations.

RAAD The RAAD for the current iteration. Must be

indexed for previous iterations.

PDIFF The PDIFF for the current iteration. Must be

indexed for previous iterations.

RMSE The RMSE for the current iteration. Must be

indexed for previous iterations.

BALANCE Initialized to 0 and set to 1 when convergence

criteria have been met.

GAPCUTOFF* Initialized to the value PARAMETERS GAP; may

be reset anytime.

RGAPCUTOFF* Initialized to the value PARAMETERS

RELATIVEGAP; may be reset anytime.

AADCUTOFF* Initialized to the value PARAMETERS AAD;

may be reset anytime

RAADCUTOFF* Initialized to the value PARAMETERS RAAD;

may be reset anytime

PDIFFCUTOFF* Initialized to the value PARAMETERS PDIFF;

may be reset anytime

RMSECUTOFF* Initialized to the value PARAMETERS RMSE;

may be reset anytime.
Highway Program > Using the Highway program > Functions and built-ins > Built-in functions available in the CONVERGE
phase

Built-in functions available in the CON VERGE phase

There are various functions available that return a value for testing in the CONVERGE
Phase. See “CONVERGE phase” on page 192 for examples of usage.
Co nv e rg e p ha s e func tio ns

Func tio n D e s c rip tio n

GAPCHANGE Change in GAP between the specified

iteration (the required argument) and the
previous iteration.

RGAPCHANGE Change in RELATIVEGAP between the

specified iteration (the required argument)
and the previous iteration.

AADCHANGE Change in AAD between the specified

iteration (the required argument) and the
previous iteration.

RAADCHANGE Change in RAAD between the specified

iteration (the required argument) and the
previous iteration.

PDIFFCHANGE Change in PDIFF between the specified

iteration (the required argument) and the
previous iteration.

RMSECHANGE Change in RMSE between the specified

iteration (the required argument) and the
previous iteration.

GAPMIN Minimum GAP between the last n iterations,

where n = the number of iterations to
process.

GAPMAX Maximum GAP between the last n iterations,

where n = the number of iterations to
process.

GAPAVE Function that results in the average GAP

between the last n iterations, where n = the
number of iterations to process.

GAPCHANGEMIN Minimum change in GAP between the last n

iterations, where n = the number of iterations
to process.

GAPCHANGEMAX Maximum change in GAP between the last

n iterations, where n = the number of
iterations to process.

GAPCHANGEAVE Average change in GAP between the last n

iterations, where n = the number of iterations
to process.

RGAPMIN Minimum RELATIVEGAP between the last

n iterations, where n = the number of
 iterations to process.

RGAPMAX Maximum RELATIVEGAP between the last

n iterations, where n = the number of
iterations to process.

RGAPAVE Average RELATIVEGAP between the last n

iterations, where n = the number of iterations
to process.

RGAPCHANGEMIN Minimum change in RELATIVEGAP

between the last n iterations, where n = the
number of iterations to process.

RGAPCHANGEMAX Maximum change in RELATIVEGAP

between the last n iterations, where n = the
number of iterations to process.

RGAPCHANGEAVE Average change in RELATIVEGAP

between the last n iterations, where n = the
number of iterations to process.

AADMIN Minimum AAD between the last n iterations,

where n = the number of iterations to
process.

AADMAX Maximum AAD between the last n iterations,

where n = the number of iterations to
process.

AADAVE Average AAD between the last n iterations,

where n = the number of iterations to
process.

AADCHANGEMIN Minimum change in AAD between the last n

iterations, where n = the number of iterations
to process.

AADCHANGEMAX Maximum change in AAD between the last

n iterations, where n = the number of
iterations to process.

AADCHANGEAVE Average change in AAD between the last n

iterations, where n = the number of iterations
to process.

RAADMIN Minimum RAAD between the last n

iterations, where n = the number of iterations
to process.

RAADMAX Maximum RAAD between the last n

iterations, where n = the number of iterations
to process.

RAADAVE Average RAAD between the last n

iterations, where n = the number of iterations
to process.

RAADCHANGEMIN Minimum change in RAAD between the last

n iterations, where n = the number of
iterations to process.

RAADCHANGEMAX Maximum change in RAAD between the

last n iterations, where n = the number of
iterations to process.
RAADCHANGEAVE Average change in RAAD between the last
n iterations, where n = the number of
iterations to process.

PDIFFMIN Minimum PDIFF between the last n

iterations, where n = the number of iterations
to process.

PDIFFMAX Maximum PDIFF between the last n

iterations, where n = the number of iterations
to process.

PDIFFAVE Average PDIFF between the last n

iterations, where n = the number of iterations
to process.

PDIFFCHANGEMIN Minimum change in PDIFF between the last

n iterations, where n = the number of
iterations to process.

PDIFFCHANGEMAX Maximum change in PDIFF between the

last n iterations, where n = the number of
iterations to process.

PDIFFCHANGEAVE Average change in PDIFF between the last

n iterations, where n = the number of
iterations to process.

RMSEMIN Minimum RMSE between the last n

iterations, where n = the number of iterations
to process.

RMSEMAX Maximum RMSE between the last n

iterations, where n = the number of iterations
to process.

RMSEAVE Average RMSE between the last n

iterations, where n = the number of iterations
to process.

RMSECHANGEMIN Minimum change in RMSE between the last

n iterations, where n = the number of
iterations to process.

RMSECHANGEMAX Maximum change in RMSE between the

last n iterations, where n = the number of
iterations to process.

RMSECHANGEAVE Average change in RMSE between the last

n iterations, where n = the number of
iterations to process.

In many applications, only a few ILOOP statements will be required. For example, an
assignment would require only the following statements:
Highway Program > Using the Highway program > Functions and built-ins > Built-in functions available in the CONVERGE
phase > Example of most simple assignment

Exam ple o f m o st sim ple assignm ent

Assume NETI contains values to obtain T0.

RUN PGM=HIGHWAY
FILEI NETI=..., MATI=...
FILEO NETO=...
PHASE=ILOOP
PATHLOAD VOL=MI.1.1, PATH=TIME
ENDRUN
Highway Program > Using the Highway program > Functions and built-ins > Built-in functions available in the CONVERGE
phase > Example of _SKIPTOI

Exam ple o f _SKIPTOI

/* In this example, the first zone will be processed and then jump to I=100. */
; Therefore, zones 2-99 will be skipped.
RUN PGM=HIGHWAY
FILEI NETI=..., MATI=...
FILEO NETO=...
PHASE=ILOOP
PATHLOAD VOL=MI.1.1, PATH=TIME
_skiptoi=100
ENDRUN
Highway Program > Using the Highway program > Getting started with assignment

Getting started with assignment

Using the Highway program is simple if all the input data is in the proper format and the
normal procedure is adhered to, but it can be somewhat more difficult if deviations from
the normal procedure is desired. In this section we would like to walk the novice users
through the steps of setting up the scripts for typical situations.
To perform a typical traffic assignment, all that is needed is an input network and a trip
matrix. If the network is in the proper format (contains the required variables) only a few
statements are required. While the program bases its computations upon generalized
costs, most users tend to think of assignments in terms of time.
To accommodate this, the program assum es that co st is equal to tim e , unless the user
specifies otherwise. In the examples below we will assume that time is the basis for the
process.
We wish to do a peak-hour assignment, and the network has the following variables.

V a ria b le D e s c rip tio n

T0 Link free flow time

DISTANCE Optional, but useful for certain statistics

C Link capacity in veh/hr

Base case is therefore:

RUN PGM=HIGHWAY ; simple case
NETI = mybase.net
MATI = mytrips.mat ; peak O-D trips
NETO = loaded.net
PHASE = ILOOP
PATH=TIME, VOL[1]=mi.1.1
ENDRUN

This script will assign the trips from MATI[1] to the paths based upon TIME. It will adjust
link times between iterations based upon the congestion levels. By default, up to 10
iterations of assignment and capacity restraint will be run; it will stop sooner if equilibrium
convergence is reached before 10 iterations.
In the following examples we will work from this same template and to keep reading to a
minimum, we will not include the RUN, NETI, MATI, NETO, and ENDRUN statements.
Thus, our illustration script would look like this:
PHASE = ILOOP
PATH=TIME, VOL[1]=mi.1.1

Examples show:
• Daily assignment

• Add select link loading

• Add truck assignment on same paths

• Add truck assignment on separate paths

• Use preloaded truck volumes

• Separate trips on separate paths

• Assignment of trips to HOV facilities

Highway Program > Using the Highway program > Getting started with assignment > Daily assignment

Daily assignment
Now let’s add a few complications: The trip matrix contains daily trips, and we wish to do
a daily assignment. The only thing that we need to do is to get the capacity into the
correct units (we’ll assume that daily capacity is 10 times the hourly capacity). We can
do this in one of several ways, but let’s just do the simplest, by adding a capacity factor.
PARAMETERS CAPFAC=10; factor NETI capacity by 10 to get daily capacity
PHASE = ILOOP
PATH=TIME, VOL[1]=mi.1.1
Highway Program > Using the Highway program > Getting started with assignment > Add select link loading

Add select link loading

Returning to the base case, let’s now assume that you wish to do an assignment and get
the volume on each link that is associated with only the trips that use a certain link. We
do this by the typical process, but add an additional select link assignment to the typical
assignment. Because this adds another volume set to the process the program will
automatically want to sum the two volume sets together to perform capacity restraint. We
have to tell the program to not add the selected link volumes. The volume used in each
link’s capacity restraint is determined by the program by performing the V function which
by default is: V=VOL [1]+… VOL[n], where n is the highest volume set in the setup.

NOTE: VOL[1], VOL[2], etc must be used with FUNCTION V. V1, V2, etc will generate
incorrect results.

So, we replace the function in the following manner:

FUNCTION V=VOL[1]
PHASE = ILOOP
PATH=TIME, VOL[1]=mi.1.1,
MW[1]=mi.1.1, SELECTLINK=(L=2001-2002), VOL[2]=mw[1]

In this case, work matrix 1 (MW[1]) is computed to be only the trips from MATI whose
paths use the selected link. That matrix is then assigned to volume set 2 (VOL[2]).
Because we supplied the V function, capacity restraint will only involve VOL[1].
As a side note, when using SELECTLINK and the TURNS control statement in the same
HIGHWAY program, care must be taken. Please see “TURNS” on page 301 for more
information.
Highway Program > Using the Highway program > Getting started with assignment > Add truck assignment on same paths

Add truck assignment on same paths

Base case plus assigning the trucks from the second matrix on M ATI. Trucks use same
paths as cars and the combined volumes are used in the capacity restraint.
PHASE = ILOOP
PATH=TIME, VOL[1]=mi.1.1, VOL[2]=mi.1.2
Highway Program > Using the Highway program > Getting started with assignment > Add truck assignment on separate
paths

Add truck assignment on separate paths

Base case plus assign the trucks from the second matrix on M ATI. Trucks use a variable
from NETI as their base path times, those times will remain constant throughout the
assignment.
PHASE = LINKREAD
LW.TRKTIME = LI.TRUCKTIME
PHASE = ILOOP
PATH=TIME, VOL[1]=mi.1.1
PATH=LW.TRKTIME, VOL[2]=mi.1.2
Highway Program > Using the Highway program > Getting started with assignment > Use preloaded truck volumes

Use preloaded truck volumes

Base case but include the volumes from a prior assignment on the network as additional
volumes. Assume that truck trips were assigned, and you wish to use the volumes (plus
30 percent to get passenger car equivalency) in determining total congestion.
PHASE = LINKREAD
LW.TRKVOL = LI.V_1 ; save the prior assignment volumes
ENDPHASE
FUNCTION V=VOL[1]+LW.TRKVOL*1.3
PHASE = ILOOP
PATH=TIME, VOL[1]=mi.1.1
ENDPHASE
Highway Program > Using the Highway program > Getting started with assignment > Separate trips on separate paths

Separate trips on separate paths

This involves more planning and a bit more script to set up the process. In this scenario,
we will assume that one matrix will be assigned to the minimum time paths, but when the
paths for the other matrix are developed, the link times are different then the times used
for the first matrix. A typical situation occurs when trucks basically operate at a lower
speed than cars. In this example, we will establish a time factor to adjust the time on all
links. The LINKREAD phase will establish an array (LW.TRKTIME) of times to be used
in assignment of the truck trips. After the first iteration, the program would automatically
adjust the car times, but there is no automatic way to adjust the truck times. So, we have
to introduce an ADJUST phase, in which we do the truck time adjustment for the next
iteration.
PHASE = LINKREAD
T0 = LI.DISTANCE * 60 / LI.SPEED
TRKFAC = 1.0
IF (LI.FUNCTYPE == 15, 25,35,45,55,65,75) TRKFAC = 1.2
LW.TRKTIME = T0 * TRKFAC
ENDPHASE
FUNCTION V = VOL[1] + VOL[2]*1.3
PHASE = ILOOP
PATH = TIME, VOL[1] = mi.1.1
PATH = LW.TRKTIME, VOL[2] = mi.1.2
ENDPHASE
PHASE = ADJUST
LW.TRKTIME = TIME * TRKFAC
ENDPHASE
Highway Program > Using the Highway program > Getting started with assignment > Assignment of trips to HOV facilities

Assignment of trips to HOV facilities

Base case plus LINKREAD to flag HOV links. We will use 2+ and 3+ facilities, which are
flagged in the network variable named HOV. The trip matrices have been previously
split into matrices that could not use any HOV links, those that could use 2+ facilities,
and those that could use 3+ facilities, stored in mi.1.1, mi.1.2, and mi.1.3, respectively.
PHASE = LINKREAD
IF (LI.HOV==2) ADDTOGRP=2
IF (LI.HOV==3) ADDTOGRP=3
PHASE = ILOOP
PATH=TIME, EXCLUDEGROUP=2-3, VOL[1]=mi.1.1
PATH=TIME, EXCLUDEGROUP=3, VOL[2]=mi.1.2
PATH=TIME, VOL[3]=mi.1.3
Highway Program > Using the Highway program > Path-based tolls

Path-based tolls
This section describes how to incorporate path-based tolls. This section discusses:
• Network development

• Path development
Highway Program > Using the Highway program > Path-based tolls > Network development

N etw ork development

To use the path-based tolling TOLLMATI function, you must follow several rules when
coding closed toll systems. Violating any of these rules causes Cube Voyager to
terminate.
• Each toll facility must operate as a completely closed system where users can access and
egress the facility only by crossing specified toll gates.
m
Every on-gate must have a unique number (1-999).
m
Every off-gate must have a unique number (1-999).
m
Every toll-road link must be identified as such (that is, value is not 0).

• Each network link must have three attributes, which designate the link’s role in the toll
system. You specify the attribute names in a FILEI TOLLMATI statement. A link can have a
non-zero value for at most one of these attributes. The attributes store:
m
On-gate number
m
Off-gate number
m
Toll-road indication

• A toll record must specify the toll for every possible on-off combination of toll gates. You
specify toll records in a FILEI TOLLMATI file.

• Toll access rules:

m
Toll on-ramps:
• Inbound link must be a non-toll-road link or a toll off-link.
• Outbound link must be a toll-road link or a toll off-link.
m
Toll off-ramps:
• Inbound link must be a toll-road link or a toll on-link.
• Outbound link must be a non-toll- road link or a toll on-link.
m
Toll-road links:
• Inbound link must be a toll-road link or a toll on-ramp.
• Outbound link must be a toll-road link or a toll off-link.

Inb o und Outb o und Inb o und Outb o und

link mus t link mus t link ma y link ma y
T o ll ty p e be be no t b e no t b e

On-ramp Non-toll- Toll-road Toll-road Non-toll-

 road off- off-ramp on-ramp road on-
ramp ramp

Off-ramp Toll-road Non-toll- Non-toll Toll-road

on-ramp road on- road off-ramp
ramp

Toll road Toll-road Toll-road Non-toll- Non-toll-

on-ramp off-ramp road off- road on-
ramp ramp
Highway Program > Using the Highway program > Path-based tolls > Path development

Path development
To include tolls in path development, specify the keyword TOLLMATI= on a
PATHLOAD statement. The first value for TOLLMATI refers to the FILEI TOLLMATI[#].
An optional second value can specify which toll set from the TOLLMATI records to use.
The specification for the TOLLMATI records is as follows:
FILEI TOLLMATI[#]=filename, ENTRYGATE= EXITGATE= TOLLS= NETIENTRY= NETIEXIT=
NETITOLLROAD=

The file may be a DBF, an MDB-element, or a delimited text file. For DBF or MDB files,
you must name ENTRYGATE and EXITGATE to indicate which fields on the record
contain the on- and off-gate numbers, and TOLLS must name the fields containing the
toll values. The first value for TOLLS is toll set 1, the second value is set 2, and so forth.
For delimited text files, the values are field numbers instead of names. There may be up
to ten TOLLMATI record numbers, and up to ten toll sets. If any of these values is not
specified, the default is the relative field on the record (ENTRYGATE is 1, EXITGATE is
2, and TOLL is 3).

NOTE: If arecord exists for a gate-to-gate combination (for the TOLLMATI#), but does
not contain a specific toll (value missing or blank), Cube Voyager assumes a toll value
of zero.

The NETI... keywords indicate the NETI link attributes that contain the values for the
ramp and road links. You can use these keywords on any FILEI TOLLMATI statement.
If you use the keywords on more than one such statement, they must have the same
values. If any are unnamed, the defaults names are: TOLLENTRY, TOLLEXIT,
TOLLROAD.
The program will fatally terminate if:
• A link has a nonzero value on more than one of the required toll attributes.

• More than one link has the same on-ramp value.

• More than one link has the same off-ramp value.

• A possible on-to-off route does not have a toll specified. Zero is an acceptable value.

• There is a violation of the above access rules.

At the beginning of each iteration, the program determines the on-off combinations that
are possible for each PATHLOAD statement. It checks if there is a toll for each of those
combinations, and if not, it fatally terminates. It saves those on-off combinations and
uses them during the PATHLOAD statement; therefore, do not revise the PATH=array
within the iteration. With most toll systems, altering the array would probably not cause a
different routing between on-off ramps, but, the on-off travel costs could become
incompatible with the array costs. In some systems, changes in the path array might
cause a different on-off routing, but since the toll routings and costs are fixed for the
iteration, the application does not consider such changes. The PATHLOAD path-
building process does not directly use the toll facility links; instead, the process uses the
predetermined combinations. During path building, the new PATHTOLL keyword value
can be used to skim the toll values for the paths (MW[1]=PATHTOLL). Any I-J path that
traversed one or more combinations of entry and exit gates will have the accumulated
toll along the path placed in the matrix.
For an example of a script using TOLLMATI, see “Example 7: Using TOLLMATI to
incorporate closed system Tolls in the Pathbuilding process” on page 315.
Highway Program > Using the Highway program > Multiple user class assignment using generalized cost functions

Multiple user class assignment using generalized cost

functions
You may skip ahead to:
• Example A: COMBINE = AVE

• Example B: COMBINE = EQUI

HIGHWAY supports assigning volumes between multiple user classes, such as High
Occupancy (HOV) and Low Occupancy (LOV) vehicles.
For example, to run a two-class assignment process with a different cost function for
each user class, the user should use LW variables to define each cost function. These
will be used to build paths in the ILOOP phase. This requires two PATHLOAD
commands: the first one assigns VOL[1] based on PATH = LW.COST_LOV, and the
second one assigns VOL[2] based on PATH = LW.COST_HOV.
In the ADJUST phase the user should calculate the variable COST as the weighted
average of the two costs. This allows HIGHWAY to compute the total cost and
convergence measures based on the variable COST.
If COMBINE=AVE is used, the FUNCTION COST equation can contain LW variables
(see below, Example A: COMBINE = AVE). If COMBINE=EQUI is used, the
FUNCTION COST equation cannot contain LW variables that are function of volume
changes (such as TIME). In this case, LW variables must be replaced with their formula
inside the FUNCTION COST equation (see COST, and Example B: COMBINE =
EQUI).
In the following examples, observe that:
• When total volume after an iteration is computed using FUNCTION V, VOL[1] and VOL[2]
represent the volume sets, and not V1 and V2.

• When COMBINE=EQUI is used, the LW.COST_HOV (and LOV) work variables should not
be used in FUNCTION COST. If FUNCTION COST contains the work variables, the
equilibrium process uses the incorrect TIME values referred in the previous ("not current")
iteration because the work variables are updated following the equilibrium process in the
ADJUST phase.
Highway Program > Using the Highway program > Multiple user class assignment using generalized cost functions >
Example A: COMBINE = AVE

Example A: COMBIN E = AVE

; Do not change filenames or add or remove FILEI/FILEO statements using an editor.
Use Cube/Application Manager.

RUN PGM=HIGHWAY PRNFILE="C:\EX_MC_EQUI\MCHWY00J.PRN" MSG='LW.COSTs & FUNC COST'

FILEI MATI[1] = "C:\EX_MC_EQUI\MCMAT00A.MAT"
FILEO NETO = "C:\EX_MC_EQUI\MCHWY00J.NET"
FILEI NETI = "C:\EX_MC_EQUI\data\BASE.NET"

DIST_COST_LOV = 0.3 ; User Class 1

DIST_COST_HOV = 0.5 ; User Class 2

PAR COMBINE=AVE MAXITERS={MAXITERS} GAP=0.0001

PROCESS PHASE=LINKREAD
T0 = (LI.DISTANCE/LI.SPEED)*60
C = LI.CAP
LINKCLASS = LI.FUNC_CLASS
IF (LI.FUNC_CLASS == 1,1.5) LINKCLASS=1 ; Freeways, tollways & HOV
IF (LI.FUNC_CLASS == 2-3) LINKCLASS=2 ; Ramps & expressways
IF (LI.FUNC_CLASS == 4-5) LINKCLASS=3 ; Arterial streets
IF (LI.FUNC_CLASS == 6) LINKCLASS=4 ; Local / collector
IF (LI.FUNC_CLASS == 9-10) LINKCLASS=10 ; Connectors /dummy
IF (LI.NAME='HOV') ADDTOGROUP=1
IF (LI.NAME='RAILACCESS') ADDTOGROUP=9
IF (ITERATION=0)
LW.COST_LOV = T0 + DIST_COST_LOV * LI.DISTANCE
LW.COST_HOV = T0 + DIST_COST_HOV * LI.DISTANCE
ENDIF
ENDPROCESS

PROCESS PHASE=ILOOP
PATHLOAD PATH = LW.COST_LOV VOL[1]=MI.1.1 EXCLUDEGROUP=1,9
PATHLOAD PATH = LW.COST_HOV VOL[2]=MI.1.2 EXCLUDEGROUP=9
ENDPROCESS

PROCESS PHASE=ADJUST
FUNCTION {
V=VOL[1]+VOL[2]
TC[1] = T0 *(1+0.18*(V/C)^8.5) ; Freeways, tollways & HOV
TC[2] = T0 *(1+1.00*(V/C)^5.0) ; Ramps & expressways
TC[3] = T0 *(1+0.70*(V/C)^5.0) ; Arterial streets
TC[4] = T0 *(1+1.40*(V/C)^5.0) ; Local / collector
TC[10]= T0 ; No congestion degradation on centroid connectors
}
LW.COST_LOV = TIME + DIST_COST_LOV * LI.DISTANCE
LW.COST_HOV = TIME + DIST_COST_HOV * LI.DISTANCE

FUNCTION COST = (LW.COST_LOV * V1 + LW.COST_HOV * V2) / CmpNumRetNum(V,'=',0,1,V) ;

cost function

ENDPROCESS
;PROCESS PHASE=CONVERGE
;ENDPROCESS

ENDRUN
Highway Program > Using the Highway program > Multiple user class assignment using generalized cost functions >
Example B: COMBINE = EQUI

Example B: COMBIN E = EQUI

; Do not change filenames or add or remove FILEI/FILEO statements using an editor.
Use Cube/Application Manager.

RUN PGM=HIGHWAY PRNFILE="C:\EX_MC_EQUI\MCHWY00J.PRN" MSG='LW.COSTs & FUNC COST'

FILEI MATI[1] = "C:\EX_MC_EQUI\MCMAT00A.MAT"
FILEO NETO = "C:\EX_MC_EQUI\MCHWY00J.NET"
FILEI NETI = "C:\EX_MC_EQUI\data\BASE.NET"

DIST_COST_LOV = 0.3 ; User Class 1

DIST_COST_HOV = 0.5 ; User Class 2

PAR COMBINE=EQUI MAXITERS={MAXITERS} GAP=0.0001

PROCESS PHASE=LINKREAD
T0 = (LI.DISTANCE/LI.SPEED)*60
C = LI.CAP
LINKCLASS = LI.FUNC_CLASS
IF (LI.FUNC_CLASS == 1,1.5) LINKCLASS=1 ; Freeways, tollways & HOV
IF (LI.FUNC_CLASS == 2-3) LINKCLASS=2 ; Ramps & expressways
IF (LI.FUNC_CLASS == 4-5) LINKCLASS=3 ; Arterial streets
IF (LI.FUNC_CLASS == 6) LINKCLASS=4 ; Local / collector
IF (LI.FUNC_CLASS == 9-10) LINKCLASS=10 ; Connectors /dummy
IF (LI.NAME='HOV') ADDTOGROUP=1
IF (LI.NAME='RAILACCESS') ADDTOGROUP=9
IF (ITERATION=0)
LW.COST_LOV = T0 + DIST_COST_LOV * LI.DISTANCE
LW.COST_HOV = T0 + DIST_COST_HOV * LI.DISTANCE
ENDIF
ENDPROCESS

PROCESS PHASE=ILOOP
PATHLOAD PATH = LW.COST_LOV VOL[1]=MI.1.1 EXCLUDEGROUP=1,9
PATHLOAD PATH = LW.COST_HOV VOL[2]=MI.1.2 EXCLUDEGROUP=9
ENDPROCESS

PROCESS PHASE=ADJUST
FUNCTION {
V=VOL[1]+VOL[2]
TC[1] = T0 *(1+0.18*(V/C)^8.5) ; Freeways, tollways & HOV
TC[2] = T0 *(1+1.00*(V/C)^5.0) ; Ramps & expressways
TC[3] = T0 *(1+0.70*(V/C)^5.0) ; Arterial streets
TC[4] = T0 *(1+1.40*(V/C)^5.0) ; Local / collector
TC[10]= T0 ; No congestion degradation on centroid connectors
}
LW.COST_LOV = TIME + DIST_COST_LOV * LI.DISTANCE
LW.COST_HOV = TIME + DIST_COST_HOV * LI.DISTANCE

FUNCTION COST= ((TIME + DIST_COST_LOV * LI.DISTANCE) * V1 + (TIME + DIST_COST_HOV *

LI.DISTANCE) * V2) / CmpNumRetNum(V,'=',0,1,V) ; cost function
ENDPROCESS
;PROCESS PHASE=CONVERGE
;ENDPROCESS

ENDRUN
Highway Program > Phases

Phases
You code Highway-program control statements within different phases. The Highway
program processes the phases in a specific order.
This section provides more details about the different phases in the
Highway program:
• SETUP phase

• LINKREAD phase

• ILOOP phase

• ADJUST phase

• CONVERGE phase
Highway Program > Phases > SETUP phase

SETUP phase
After reading all control statements, the Highway program processes the SETUP
phase’s control statements—that is, its stack. The SETUP phase can only contain COMP
and SET statements. The SETUP phase does not have a header: it precedes the first
actual PHASE= statement. Use the SETUP phase to initialize certain variables and/or
arrays.
Highway Program > Phases > LINKREAD phase

LINKREAD phase
An initial LINKREAD phase follows the SETUP phase. This phase obtains the required
initial values from the input network and computes link values that you can reference in
other phases. The program executes the LINKREAD phase implicitly during the
equilibrium/volume-combination process and during the ADJUST phase to obtain
required link values from the input network.
You reference values obtained directly from the network with the network variable name
prefixed by “LI.” Link variables not obtained directly from the network are called link-work
variables. To reference link-work variables, you must give link-work variables names
that begin with “LW.” For example, the statement: LW.TOLLTIME = LI.TOLLTIME / 100
generates a value available for every link at any phase in the program. On the other
hand, the statement: TOLLTIME = LI.TOLLTIME / 100 generates a temporary variable that
has no meaning beyond the current link. The program stores link-work variables as link-
work arrays (see “Built-in arrays” on page 149).

NOTE: Please see “Using Cluster with HIGHWAY” on page 1164 for guidelines on using
link-work arrays in a distributed system.

During the LINKREAD phase, the program processes an internal loop from the first link
through the last link, using the LINKNO variable (that is, LINKNO=1, NUMLINKS). For
each value of LINKNO, the program obtains a link data record from the input network
(NETI), and processes any control statements (the LINKREAD stack).
In the LINKREAD stack, you might use:
• COMP statements to alter, or set, link values.

• statements to list information about individual links. Remember that DISTANCE,

PRINT
LINKCLASS, C, T0, T1, TIME, COST, and DIST contain meaningless values during
LINKREAD processing.

NOTE: The program processes the entire LINKREAD stack for each link whenever
reading a network link’s data record. To ensure consistency, the program also
processes the LINKREAD stack for each link when reading and processing the link in
the ADJUST (capacity restraint) phase. Therefore, you must not reference DISTANCE,
LINKCLASS, C, T0, T1, TIME, COST, and DIST in the LINKREAD stack; doing so
could alter the internal arrays used and dynamically altered by the capacity-restraint
process.

If you do not need any special LINKREAD operations, you need not specify any stack
statements in this phase.
After processing the LINKREAD stack, the program ensures that certain link variables
(T0, T1, and C) have values and sets the link’s TIME, COST, and DIST values. There
are several methods for setting these variables (see “Setting TIME, COST, and DIST
values” on page 173).

NOTE: The
program does not set the TIME, COST and DIST values after processing the
LINKREAD stack for each link during the capacity-restraint process (that is, during the
ADJUST phase).

You can use the LINKREAD phase to specify GROUP codes for links. You might use
GROUP codes for various reasons. For example, you can disable links with certain
GROUP code values during path building to preclude using those links in the path. (See
“PATHLOAD” on page 270 for more details.) For example, you might build low-
occupancy vehicle paths by precluding the use of HOV links. Other applications can
also take advantage of this capability.
GROUP codes can be very useful in select-link processing. You can easily identify
paths that use links with certain GROUP codes, and use these paths for extracting
matrices. You can even identify the paths that have a certain level, or combination of
levels, of GROUP-coded links. See “SETGROUP” on page 298 for details.
Highway Program > Phases > LINKREAD phase > Setting TIME, COST, and DIST values

Setting T IME, COST , and DIST values

After processing the LINKREAD stack, the program sets TIME, COST, and DIST
values using the following logic:
• DISTANCE (possibly used to compute T0):
m
If set by LINKREAD stack, use that value.
m
Else if there is a LI.DISTANCE, set DISTANCE = LI.DISTANCE.
m
Else set DISTANCE = 0.
m
If DISTANCE < 0, set DISTANCE = 0.

• LINKCLASS (essential for selecting appropriate Functions):

m
If set by LINKREAD stack, use that value.
m
Else if there is a LI.LINKCLASS, set LINKCLASS = LI.LINKCLASS.
m
Else set LINKCLASS = 1.
m
If LINKCLASS < 1, set LINKCLASS = 1.

• SPEED (possibly used to compute T0):

m
If set by LINKREAD stack, use that value.
m
Else if there is a LI.SPEED, set SPEED = LI.SPEED.
m
Else If there are LI.LANES and LI.SPDCLASS and their values are valid (1-9, and 1-99),
set SPEED = SPEEDFOR(LI.LANES,LI.SPDCLASS).
m
Else set SPEED = 0.

• C (capacity, used later in restraining process in the ADJUST phase):

m
If set by LINKREAD stack, use that value.
m
Else if there is a LI.CAPACITY, set C = LI.CAPACITY* CAPFAC.
m
Else If there are valid LI.LANES and LI.CAPCLASS values (1-9 and 1-99), set
C = CAPACITYFOR(LI.LANES,LI.CAPCLASS) * CAPFAC.
m
Else set C = 0.
m
If C < 0, set C = 0.
NOTE: The program treats a link capacity of 0 (zero) as infinite capacity.
• T0 (free flow time):
m
If set by LINKREAD stack, use that value.
 m
Else if there is a LI.T0, set T0=LI.T0.
m
Else if there is a LI.TIME, set T0 = LI.TIME.
m
Else if there is a LI.TIME1, set T0 = LI.TIME1.
m
Else if SPEED > 0, set T0 = DISTANCE*60/SPEED.
m
If T0 < 0, set T0 = 0.

• T1 (initial iteration time):

m
If set by LINKREAD stack, use that value.
m
Else set T1 = T0.

• TIME (a link-work variable, without the required “LW.” prefix, of T1 values):

m
Set equal to T1. Do not reference TIME in LINKREAD stack because its value is
unpredictable during stack processing.

• COST (a link-work variable, without the required “LW.” Prefix, of cost values):
m
Compute from the COST function for the LINKCLASS. Do not reference COST in
LINKREAD stack.

• DIST (a link-work variable, without the required “LW.” prefix, of DISTANCE values):
m
Set equal to DISTANCE. Do not reference DIST in LINKREAD stack.

NOTE: Though the program examines DISTANCE and SPEED, you need not specify
them. Usually, the program computes T0 by dividing DISTANCE by SPEED. Therefore,
the program will try to obtain DISTANCE and SPEED values. If you do not set these
values in control statements, the program will try to set them, and then compute T0. On
the other hand, if you set T0 directly, the program does not use the values of
DISTANCE and SPEED.
Highway Program > Phases > ILOOP phase

ILOOP phase
The ILOOP phase performs a zonal loop (I = 1, Zones). This phase is the first phase of
the iteration loop (ITERATION=1, LASTITERATION). Almost all control statements are
valid during the ILOOP phase (that is, in the ILOOP stack). The Highway program
requires a PHASE=ILOOP statement, and the ILOOP stack must have at least one
PATHLOAD statement. The program executes the ILOOP stack one time for each value of
I.
The ILOOP stack can contain nearly any of the functions of the Matrix program. The
ILOOP phase performs MW[#] statements for all Js (J=1, Zones), unless the statement
occurs within a JLOOP block, or the statement specifies both indices (MW[m][j]).
Please see “Using Cluster with HIGHWAY” on page 1164 for guidelines on using link-
work arrays in the ILOOP phase.
For assignment, you must include a PATHLOAD statement. This statement specifies a set
of values that the program assigns to the links in a specified path set. The following
examples illustrate the PATHLOAD statement:
• Volume sets

• Stratifying vehicle distance traveled by average trip speed

• Select-link processing

• Selected zone loading

• Subarea trip extraction

Highway Program > Phases > ILOOP phase > Volume sets

Volume sets
A volume set is an array that accumulates assignments for each link. There may be up
to 1000 volume sets. Though the highest set number is 1000, set numbering need not
be monotonic. The program refers to volume sets as VOL[#], and clears each at the
beginning of each iteration. You can enter values into volume sets with PATHLOAD VOL[#]
= expressions. A VOL[#] expression implies an internal loop of J=1, ZONES. In example
1, VOL[1]=MI.1.6 instructs the program to assign the values from the expression “MI.1.6”
to each link in the paths from the origin zone (I) to each of the destination zones (J). As
J loops, the value (normally trips) for I to J from MI.1.6 will be assigned to links along the
path from I to J.
Highway Program > Phases > ILOOP phase > Volume sets > Example 1

Exam ple 1
PATHLOAD VOL[1]=MI.1.6, PATH=TIME

Builds paths based on TIME value. For each link in those paths, adds values to the first
volume set (VOL[1]) from matrix 6 in the MATI[1] file.
Highway Program > Phases > ILOOP phase > Volume sets > Example 2

Exam ple 2
PATHLOAD PATH=LI.DISTANCE, VOL[3]=I*10+J

Builds paths based on the value of DISTANCE read from the network. For each link in
those paths, adds values to the third volume set (VOL[3]) computed from the “I*10+J”
expression. (The program assigns a value for each J in: J=1, ZONES.)
Highway Program > Phases > ILOOP phase > Volume sets > Example 3

Exam ple 3
PATHLOAD VOL[4]=MW[5]+MW[6]+MI.2.8, PATH=LW.TOLLTIME

Builds paths based on the link-work variable, TOLLTIME. For each link in those paths,
adds values to the fourth volume set (VOL[4]) computed from the “MW[5] + MW[6] +
MI.2.8” expression.
Highway Program > Phases > ILOOP phase > Stratifying vehicle distance traveled by average trip speed

Stratifying vehicle distance traveled by average trip speed

During a multiple-iteration assignment, the trips from any I to J may use various paths.
The paths are based upon the link times in effect during that iteration. After all iterations,
the program determines vehicle time from the final link volumes and the travel times
associated with those volumes. You might want to estimate emissions based on the
average trip speed rather than on the individual link volumes, distances, and times. In
this case, you must request REPORT VDTSPD to base vehicle distance on average trip
speed.
This option requires considerably more processing and might require considerably more
disk space. The program saves the paths for each I-J movement during normal
assignment. Following the assignment, the program retrieves the paths and retraces all
the assigned trips along their paths. The program uses the final link times to compute
the individual trip time and distance. Finally, the program calculates the average speed
for the trip. The program uses speed to stratify the vehicle distance of travel.
You can specify multiple stratification schemes; additional schemes do not require
additional resources.
Highway Program > Phases > ILOOP phase > Select-link processing

Select-link processing
Use the PATHLOAD statement to initiate select-link processing. The PATH keyword
specifies the link values that the program uses to develop the paths. Specify an M W []
expression followed by SELECTLINK , SELECTGROUP , or SELECTLINKGROUP to solve the
MW expression only for those destination zones (J) where the specified SELECT…
expressions result in a true condition. Subsequent VOL[] statements can assign any of
the select-link matrices to a link’s volume set. Select link functionality is currently not
implemented with path based assignment (COM BINE=PATH ) and will not work.
Highway Program > Phases > ILOOP phase > Select-link processing > Example (simple code – inefficient)

Exam ple (sim ple co de – inefficient)

MW[1]=0
JLOOP ; this illustrates selective gathering
IF ((I=... & J=...) || (I=... & J=...) ) MW[1] = MI.1.1
ENDJLOOP
VOL[1]=MW[1],path=...

Solving complicated selections is time consuming. The IF process will run faster if the
zonal ranges are not too complicated.
Highway Program > Phases > ILOOP phase > Select-link processing > Example (most efficient)

Exam ple (m o st efficient)

IF (I=...) PATH=..., VOL[1]=MI.1.1, INCLUDEJ=...
Highway Program > Phases > ILOOP phase > Select-link processing > Example (using SELECTLINK)

Exam ple (using SELECTLINK)

PATH=..., MW[1]=MI.1.ODTRIPS, SelectLink=(a=... && b=...),
SelectLink=(a=... && b=...),
VOL[1]=MI.1.1,
Highway Program > Phases > ILOOP phase > Selected zone loading

Selected zone loading

You can use several techniques to load only trips between selected zone pairs:
• Establish a work matrix with the trips you want loaded. Clear the “unwanted” I-J pairs, and
then reference that matrix with the PATHLOAD V OL[ ] statement.

• Use IF statements to find the desired I, and use IN CLU D E J and E XCLU D E J keywords to select
the desired J values.

• Use S E LE CT LIN K, specifying A=range of desired I values and B=range of desired J values.
Highway Program > Phases > ILOOP phase > Subarea trip extraction

Subarea trip extraction

To obtain matrices of trips that travel through some portion of a selected region in the
network (such as a subarea network polygon), use the following keywords:
• FILEI S U B A R E A N E T I — Define the region.

• FILEO S U B A R E A MA T O — Define where to save the selected trips.

• PATHLOAD S U B A R E A MA T — Specify values to write to the SUBAREAMATO file.

After building paths for the current I-zone, the program computes the SUBAREAMAT
expression for each J-zone on the path from I to J. If the I-to-J path uses any links in the
subarea network, the program records the computed value for the path’s J in the
subarea matrix. This process can extract several types of records:
P o te ntia l e xtra c te d re c o rd s

R e c o rd ty p e D e s c rip tio n

X-X Path begins and ends outside subarea,

crossing the cordon line exactly two times.

X-I Path begins outside the subarea and ends

inside the subarea.

I-X Path begins inside the subarea and end

outside the subarea.

I-I Path begins and ends inside the subarea.

When a path enters the subarea by crossing a cordon link, the A-node of the cordon link
becomes the origin zone of the extracted record. Similarly, the B-node of the cordon link
used to exit the subarea becomes the destination zone. If the path terminates at an
internal zone, the internal zone becomes the destination zone.
When a path exits the subarea, the internal zone where the path began, or the A node
of the cordon link that was used to enter the subarea, becomes the origin zone of the
extracted record, and the B node of the exit cordon link becomes the destination zone.
If a path begins and ends inside the subarea, but never crosses the cordon line, a single
I-I record is extracted. The A node of the origin zone becomes the origin, and the
destination zone becomes the destination. The intrazonal value for an internal zone will
be extracted even though there is no path.
Multiple records can be extracted for a path. (For example, a path begins outside,
enters, exits, enters, and either exits again, or terminates an internal zone.) The final
matrices are combined values from all iterations of assignment, but if requested during a
non-assignment application, only 1 iteration is processed.
The subarea network is obtained from Cube Base, using the polygon subarea network
extraction process.
Highway Program > Phases > ILOOP phase > Subarea trip extraction > Example (subarea trip extraction)

Exam ple (subarea trip extractio n)

PATHLOAD PATH=TIME, SUBAREAMAT[1]=MI.1.1, SUBAREAMAT[2]=1
Highway Program > Phases > ADJUST phase

ADJUST phase
You may skip ahead to:
• Example illustrating Lambda and Factor

• Combination processes

• Convergence tests

Part of the iteration loop, the ADJUST phase automatically follows the ILOOP phase.
This phase computes the congested time (Tc) on each link and revises the link’s TIME
values, which the next iteration uses.
If you want to complete special processing on each link following the normal adjustment
process, include the Phase=ADJUST control statement followed by the stack of control
statements you want to complete. Most commonly, you might include ADJUST
statements to list how the normal adjustment process affects each link and to adjust LW
values. LW values based on values revised by the ADJUST process (such as TIME
and COST) should be recalculated. For example, if you have a set of LW.TOLLTIME
values, those values must be updated to reflect changes made in TIME. You must make
the changes to LW.TOLLTIME because the program does not know your intention and
cannot adjust the values automatically. Though allowed, Citilabs recommends that you
do not alter TIME values with ADJUST statements.
After processing user-specified ADJUST statements, the program recalculates the
COST values using the Cost Function. See FUNCTION COST for more on using cost
functions.
The ADJUST phase runs an automatic link loop across all links on the input network.
The link loop executes the ADJUST phase stack once per link. To accumulate
summary values during the link loop, you must properly initialize the values at the
beginning of the link loop. In initializing statements, you might test the value of LINKNO : IF
(LINKNO=1)... (You can also test for ITERATION and LASTITERATION .)

Congestion is based on the variable V, computed for each link. By default, V is the sum
of all VOL[] values that appear on any PATHLOAD statement. Use a FUNCTION V statement
to override the default computation of V.
When using SELECTLINK analysis:
• Do not use the default computation for V if you configure a standard assignment along with
a select-link assignment; this configuration duplicates some volumes. Use a FUNCTION V
statement to override the default computation of V.

• With SELECTLINK analysis, only the turn volume sets corresponding to the original volume
 indices should be summed. This avoids double counting in the TURNS request.

For example, when

FUNCTION V = VOL[1] + VOL[2]

Then the corresponding TURNS request should be:

TURNS T = TURN[1] + TURN[2]

For more information, please see “TURNS” on page 301.

NOTE: See “Functions and built-ins” on page 147 for a description of the built-in
functions, variables, and arrays the program uses.)

Most often, you configure multiple iterations, and the program computes the final
volumes by combining the volumes from each iteration. Though you can specify the
maximum number of iterations, Citilabs recommends that you let the program determine
when more iterations will not result in any assignment improvements.
The program can use various methods to combine iteration volumes. Use PARAMETERS
COM BINE to specify the method used. For a list of these methods, see “Combination
processes” on page 185.
Equilibrium assignment is performed within the ADJUST phase. If the term assignment
is used to indicate the actual accumulation of trips on link volumes, the term “equilibrium
assignment” is somewhat of a misnomer. Most users tend to think of equilibrium
assignment as the process of determining a weight factor for an iteration, and then
applying that factor to the current iteration volumes and a complementary factor to the
previously weighted volumes to obtain new weighted volumes. If the network is “well
behaved,” and the appropriate processes are included, eventually a state of equilibrium
is reached. That state is reached when further adjustments in the link costs used for
routing, will not produce significant differences in the system as a whole. In theory,
equilibrium is reached when there is no ability for individual I-J path costs to improve,
without causing degradation in other parts of the network. If a system has a significant
degree of congestion, it may be difficult (practically impossible) to reach a true state of
equilibrium.
The basic measure of equilibrium is total system user cost, and in most situations, cost
involves some measure of time. Time is generally the measurable quantity that can be
directly related to congestion. Thus, most equilibrium formulations are based upon time.
To determine the weight to apply to each iteration’s volume in the volume combining
process, a factor λ (generally referred to as Lambda) is estimated for the iteration.
Lambda is a factor >=0 and < 1. Starting from Cube 6.4 version, LAMBDA has been
allowed to take zero values. This is controlled by the PARAMETER ALLOWLAMBDA0.
By default ALLOWLAMBDA0 is set to true. Once LAMBDA reaches zero, the
assignment process stops since there will be no more convergence of the results. It is
impossible to solve directly for Lambda, so it is estimated using a linear approximation
method.
The user can select one of two Lambda search processes using the PARAMETERS
COM BINE LAM BDASEARCH = AREA, or EQUATION. Note that both processes estimate
Lambda so the results might be slightly different. In most cases, the results will be quite
similar, but the EQUATION method can save considerable computation and I/O time.
• If the AREA search process is used, the program minimizes the area under all the V vs.
Cost curves computed for incremental estimates of lambda for every link. This process
provides a Lambda calculation that is up to 6 digits in precision.
If a standard function for computing TC is used, the estimation process could be
considerably more efficient.
• If the EQUATION search process is used, the program solves the expression for only a
limited number of Lambdas, using the following expression if the default BPR form is used
for the TC functions or no TC functions are coded (default TC function is BPR form with
default BPR constant and exponent):

Y(λ) = Σ (VOLk – V k-1) * T0(1 + TCCOEFF * ((V k-1 + λ * (VOLk - V k-1))/C) ^ TCEXP)
where:

Σ = the summation over the links in the input network

VOLk = the AON volume assigned in iteration k to COST k-1

paths based on Vk-1

Vk-1 = the equilibrium weighted volume from the prior iteration

T0 = the free flow time

TCCOEFF = value of the TC functions coefficient term defined on

the PARAMETERS statement

C = the link capacity

TCEXP = value of the TC functions exponent term defined on the

PARMETERS statement

If the user has specified his own alternate form for the TC functions using the
PARAMETERS TCCOEFF and TCEXP and requests the EQUATION search process,
then the program uses the following expression to solve for Lambda:
Y(λ) = Σ (VOLk – V k-1) * TC(V’,TCCOEFF,TCEXP)
Where TC(V’,TCCOEFF,TCEXP) is the TC functions evaluated for link volumes V’,
and the appropriate values of TCCOEFF and TCEXP, where V’= V k-1 + λ * (VOLk -
V k-1).
The resulting curve is examined, and the Lambda which provides Y=0 is obtained by
interpolation. This value is then used to weight the current volumes: V k = λ * VOLk +
(1- λ)*V k-1.

NOTE: EQUATION is available only with the single user class assignment, and when
using the default FUNCTION COST=TIME. On the other hand, with a generalized cost
function, o nly the AREA process should be used. This is depicted in Example 8:
Multiple User Class Assignment with Cost based on User Class. EQUATION and
AREA will generate substantially different results when used with a generalized cost
function.
Highway Program > Phases > ADJUST phase > Example illustrating Lambda and Factor

Example illustrating Lambda and Factor

To illustrate the relationship between Lambda and Factor, below is a sample assignment
with three iterations:

Iter Vcost VDist VTime AAD RAAD PDiff RMSE Gap RelGap Lambda Factor
E+03 E+03 E+03
---- ----- ----- ---- --- ---- ----- ---- --- ----- ------ -----

1 8,277 335,070 8,277 -- -- -- -- 0 0 1.00000 0.43207

2 1,809 351,444 1,809 1,635 0.208 -- 2,700 0.78150 0.88754 0.32084 0.20411
3 1,084 353,968 1,084 1,088 0.139 -- 1,719 0.40077 0.47792 0.36381 0.36381
Highway Program > Phases > ADJUST phase > Example illustrating Lambda and Factor >
Highway Program > Phases > ADJUST phase > Example illustrating Lambda and Factor > From the previous section,

From the previous section,

V 1 = λ1 * VOL1 + (1- λ1) * V 0

V 2 = λ2 * VOL2 + (1- λ2) * V 1

Highway Program > Phases > ADJUST phase > Example illustrating Lambda and Factor > Combining these,

Combining these,
V 2 = λ2 * VOL2 + (1- λ2) * (λ1 * VOL1 + (1- λ1) * V 0)

V 2 = (1- λ1) * (1- λ2) * V 0 + λ1 * (1- λ2) * VOL1 + λ2 * VOL2

Or,
V 2 = factor0 * V 0 + factor1 * VOL1 + factor2 * VOL2

Where
factor0 = (1- λ1) * (1- λ2)

factor1 = λ1 * (1- λ2)

factor2 = λ2

These relationships thus yield:

Ite ra tio n La mb d a (λ ) Fa c to r

0 1 0.43207

1 0.32084 0.20411

2 0.36381 0.36381
Highway Program > Phases > ADJUST phase > Combination processes

Combination processes
There are several iteration volume combination processes available; the PARAMETERS
COM BINE = specifies the one to use. EQUI is the default. The available processes are:

• EQUI

• AVE

• WTD

• ITE

• SUM

• PATH

• PROBIT and BURRELL

n EQUI

Standard equilibrium processing: compute a Lambda (λ) for each iteration to be applied
to obtain the factor to combine the current volume (V) with the previous combined
volume (CVOL):
V = V * λ + CVOL * (1-λ)
This method is an implementation of the Frank-W o lfe algo rithm ("An algorithm for quadratic
programming", Naval Research Logistics Quarterly, 3 (1956), pp. 95-110).

NOTE: Highway
will use TIME as the cost for the computation of Lambda, unless
FUNCTION COST is calculated in the Highway model.

With this method, there are several options that can be specified by the subkeyword
LAM BDASEARCH (see“LAMBDASEARCH” on page 259). When intersection modeling is
being undertaken (triggered by the presence of a FILEI JUNCTIONI statement),
standard Lambda estimation processes are used for the link volume evaluations, but
there is no equivalent process for including turning volumes. Intersection delays are not
directly dependent upon the volumes on them; they are influenced by the total
intersection traffic. But, the delays might have an important impact upon the assignment
convergence. The vehicle delay costs for the turn movement can be included with the
link costs by providing a value for the EQUITURNCOSTFAC keyword. If specified,
Lambda estimation includes the turning delays multiplied by this value.
HIGHWAY supports additional assignment algorithms for COM BINE=EQUI mode. To
access these, include the ENHANCE keyword immediately after the COM BINE=EQUI
statement. Please see “ENHANCE” on page 259.
When using COM BINE=EQUI, please note that:
• For distributed cluster node systems, please see “Using Cluster with HIGHWAY” on
page 1164.

• Any LW.xxxx equation containing variables which are a function of Volume changes (such
as TIME) c a nno t be used with FU N CT ION COS T and FU N CT ION T C when COMB IN E =EQUI. Such
arrays are updated following the equilibrium processes in the ADJUST phase, and will
generate incorrect results if directly referenced.
For an implementation example, Citilabs stro ngly recommends reviewing “Multiple
user class assignment using generalized cost functions” on page 166.

n AVE

Averages all the iteration loadings — the program simply keeps a running average of the
volumes on each link.

n WT D

Weighted average. MAXITERS will be set according to the number of weights specified
in W EIGHTS. This is similar to AVE (above), but the required weights are used to favor
specific iterations.

n IT E

Iterative assignment keeps only last iteration volumes as output; prior iteration volumes
are not considered. Only the last iteration volumes are used for output to NETO.

n SUM

All the Iteration volumes are summed to form the final volume. This process can be used
to perform traditional incremental loading. When SUM is specified, it must be followed by
the FRACTIONS subkeyword. The V at the end of each iteration is the accumulated V for
all the iterations to that point. Thus, the V/C ratio used in adjustment is based upon a
partial assignment; it is true only on the last iteration. If it is desired to use a “projected
full” V/C, then C must be computed differently depending upon which iteration it is. This
can be accomplished in the LINKREAD phase, by use of IF (ITERATION=...) processes
or by using an array of C scales.

n PAT H

HIGHWAY includes support for path-based assignm ent using a gradient projection
algorithm. In contrast to the Frank-Wolfe method (which finds solutions that are vertices
of the feasible region), gradient projection makes successive moves in the direction of
negative gradient.
The keywords VARIABLEDEMAND and ALLJ can be included immediately after the
COM BINE=PATH statement, which gives additional flexibilities to handle complex
scenarios. For more information, see “VARIABLEDEMAND” on page 260.
With path based assignment, select link functionality is not implemented and will not
work.

n PROBIT and BURRELL

• See also: “Stochastic traffic assignment theory” on page 305.

These COM BINE modes support sto chastic assignm ent.

Associated COM BINE sub-keywords supporting stochastic assignment (when using

PROBIT and BURRELL) are:
STOCHASTICSEED=n, LINKRANDSERIES=s

The associated PATHLOAD statement stochastic assignment support keywords are:

PATH=x,
SPREADPERC=n,
SPREADPERCVAR=var,
SPREADMAX=n
Highway Program > Phases > ADJUST phase > Convergence tests

Convergence tests
If the optional CONVERGE phase has not been specified then default convergence
testing is performed at the end of the ADJUST phase to determine if more iterations are
necessary.
Convergence testing is not performed for Combine=Sum assignment. There are several
tests that can be made to determine if more iterations are necessary. The items that are
used in the tests are Keywords set with the PARAMETERS statement and include:

Ke y wo rd s D e s c rip tio n

GAPk ABS(SUML(VEk *COSTEk ) – SUML(Vk-

1*COSTEk-1))/ SUML(Vk‑1*COSTEk-1)
Where k is the current iteration and SUML
denotes summation over the links and, if
appropriate, the turning movements in the
network, VEk is the equilibrium weighted
volumes for iteration k and COSTEk is the cost
based on the equilibrium volumes VEk .

RGAPk (SUML(VEk-1*COSTEk-1) -
SUML(VAk *COSTEk-1))/
SUML(VEk‑1*COSTEk-1)
Where VAk is the link volume from an all or
nothing assignment to the minimum cost paths
based on COSTEk-1.

AAD Average absolute volume difference: based

upon successive iterations

RAAD Relative AAD: DiffV/V

Pdiff Percent of links whose change in V between

iterations is less than a set value.

RMSE Root mean squared error of the differences in V

between iterations.

MAXITERS Sets a fixed maximum number of iterations for

convergence

The ADJUST phase process is as follows:

• Major Link loop: Linkno = 1, NumLinks (multiple passes if equilibrium is specified):
m
Obtain link values (as in LINKREAD and LINKREAD stack, except TIME is not altered).
m
If Iteration > 1, obtain prior combined iteration volumes (CVOL is prior V).
m
Apply the appropriate TC and Cost Functions (based on LinkClass) to compute revised
 Time and Cost.

NOTE: Unless FUNCTION COST is calculated in the Highway model, Highway will
use TIME as the cost for the calculation of convergence, and for the computation
of Lambda for the Frank-Wolfe algorithm (COMBINE EQUI).
m
If this is an Equilibrium pass, compute link contribution (Y) to Lambda estimations.
m
Else if Iteration > 1, combine V with prior combined Vs
m
Process LinkAdjust stack (if present), and recompute Cost.
m
End Major Link Loop.

• Determine if this is to be the last iteration:

m
If Iteration = MaxIters: LastIteration = 1, go to write NETO

• Test for Convergence if CONVERGE phase not specified (true if any of following
conditions met – minimum values are those set with the PARAMETERS statement):

GAP < MinGap

RGAP < MinRGAP

AAD < MinAAD

RAAD < MinRAAD

PDIFF > MaxPdiff

RMSE < MinRMSE

NOTE: Under the default convergence criteria, convergence is considered to be

achieved if ANY of the above PARAMETERS minimum values are obtained. Note
that all of these PARAMETERS have default values so they do have minimum
targets even though the user has not explicitly coded them. For example if you have
specified PARAMETERS GAP=0.001 in order to stop further iterations beyond this
value of GAP but have set no other controls, the assignment may stop after 20
iterations because the default value of MAXITERS=20 (when COMBINE = EQUI) is
reached before reaching a GAP<0.001. Or, the assignment may stop in less then 20
iterations and before GAP<0.001 because one of the other PARAMETERS has
reached its default minimum. In order to insure that a specific GAP value is achieved
(if that is your goal) you must set all of the other convergence PARAMETERS to zero.
For example:
PARAMETERS MAXITERS=99, GAP=0.001, RELATIVEGAP=0, AAD=0, RAAD=0, RMSE=0
 Would continue performing iterations until GAP<=0.001 or 99 iterations were
preformed. If you would like to specify alternate rules for when the program
determines convergence is reached, this can now be achieved by using the
CONVERGE phase. See “CONVERGE phase” for examples of specifying alternate
convergence rules.
• If PHASE=CONVERGE is present, process the stack statements in the CONVERGE
Phase until BALANCE=1 or MAXITERS is reached.

• If Convergence satisfied by BALANCE=1 (LastIteration set to Iteration, if true), or

LastIteration: Write Neto.
Highway Program > Phases > CONVERGE phase

CONVERGE phase
This phase, if specified, follows the ADJUST phase in each iteration. At the end of the
ADJUST phase, the program checks if additional iterations are necessary.
Convergence testing is not performed for Combine=Sum assignment or for Iteration=1.
There are several tests that can be made to determine if more iterations are necessary.
The default items that are used in the convergence tests are:

GAPk ABS(SUML(VEk*COSTEk) –
SUML(Vk-1*COSTEk-1))/ SUML(Vk-
1*COSTEk-1)
Where k is the current iteration and
SUML denotes summation over the
links and, if appropriate, the turning
movements in the network, VEk is the
equilibrium weighted volumes for
iteration k and COSTEk is the cost
based on the equilibrium volumes
VEk.

RGAPk (SUML(VEk-1*COSTEk-1) -
SUML(VAk*COSTEk-1))/ SUML(VEk-
1*COSTEk-1)
Where VAk is the link volume from an
all or nothing assignment to the
minimum cost paths based on
COSTEk-1.

AAD Average absolute volume difference:

based upon successive iterations

RAAD Relative AAD: DiffVE/VE

Pdiff Fractional portion of links whose

change in VE between iterations is
less than a set value.
# of links: [ABS(V1-V2) / (V1) <
PDIFFVALUE] / # of links: [V1 ->
 0V2]

Where V1 and V2 are the link flows

of consecutive iterations.

RMSE Root mean squared error of the

differences in VE between iterations.

MAXITERS Sets a fixed maximum number of

iterations for convergence

There are different philosophies as to what measures are best to determine if

convergence has been reached, or if further assignment iterations will improve the
assignment depending on the assignment method used. Some networks may never be
able to reach a true balance because there is too much congestion, or there is
insufficient capacity in certain parts of the network. Things can not be completely smooth
because a slight adjustment in a few links may cause a large shift in a slug of traffic.
Sometimes, the test statistics will begin to oscillate near the desired test limit, and may
never reach a desired result.
The CONVERGE phase process is provided to allow the user to program his/her own
method of setting convergence. The user can write script to determine if the desired
measure has been met. When the results are satisfactory, the script should set the
variable BALANCE to 1. That will indicate to the program that further iterations are not to
be undertaken.
Note that if PHASE=CONVERGE is detected within the script, the standard tests are not
performed; termination will be determined by the value of BALANCE after the phase is
completed. If BALANCE is never set to 1, the program will continue until MAXITERS is
satisfied. BALANCE is automatically set to 0 when the phase begins.
To help the user set BALANCE, various variables and functions are available.
V a ria b le s a v a ila b le fo r B A LA N CE

V a ria b le D e s c rip tio n

GAP The GAP for the current iteration, Must be

indexed GAP[] for previous iterations

RGAP The RELATIVEGAP for the current iteration,

Must be indexed for previous iterations

AAD The AAD for the current iteration, Must be

indexed for previous iterations

RAAD The RAAD for the current iteration, Must be

indexed for previous iterations

PDIFF The PDIFF for the current iteration, Must be

indexed for previous iterations
RMSE The RMSE for the current iteration, Must be
indexed for previous iterations

GAPCUTOFF A variable initialized to the value Parameters

GAP, may be reset anytime

RGAPCUTOFF A variable initialized to the value Parameters

RELATIVEGAP, may be reset anytime

AADCUTOFF A variable initialized to the value Parameters

AAD, may be reset anytime

RAADCUTOFF A variable initialized to the value Parameters

RAAD, may be reset anytime

PDIFFCUTOFF A variable initialized to the value Parameters

PDIFF, may be reset anytime

RMSECUTOFF A variable initialized to the value Parameters

RMSE, may be reset anytime

Func tio ns a v a ila b le fo r B A LA N CE

Func tio n D e s c rip tio n

GAPCHANGE Function that results in change in GAP

between the specified iteration (the
required argument) and the previous
iteration.

RGAPCHANGE Function that results in change in

RELATIVEGAP between the specified
iteration (the required argument) and the
previous iteration.

AADCHANGE Function that results in change in AAD

between the specified iteration (the
required argument) and the previous
iteration.

RAADCHANGE Function that results in change in RAAD

between the specified iteration (the
required argument) and the previous
iteration.

PDIFFCHANGE Function that results in change in PDIFF

between the specified iteration (the
required argument) and the previous
iteration.

RMSECHANGE Function that results in change in RMSE

between the specified iteration (the
required argument) and the previous
iteration.

GAPMIN Function that results in the minimum GAP

between the last n iterations, where n = the
number of iterations to process.

GAPMAX Function that results in the maximum GAP

between the last n iterations, where n = the
 number of iterations to process.

GAPAVE Function that results in the average GAP

between the last n iterations, where n = the
number of iterations to process.

GAPCHANGEMIN Function that results in the minimum

change in GAP between the last n
iterations, where n = the number of
iterations to process.

GAPCHANGEMAX Function that results in the maximum

change in GAP between the last n
iterations, where n = the number of
iterations to process.

GAPCHANGEAVE Function that results in the average

change in GAP between the last n
iterations, where n = the number of
iterations to process.

RGAPMIN Function that results in the minimum

RELATIVEGAP between the last n
iterations, where n = the number of
iterations to process.

RGAPMAX Function that results in the maximum

RELATIVEGAP between the last n
iterations, where n = the number of
iterations to process.

RGAPAVE Function that results in the average

RELATIVEGAP between the last n
iterations, where n = the number of
iterations to process.

RGAPCHANGEMIN Function that results in the minimum

change in RELATIVEGAP between the
last n iterations, where n = the number of
iterations to process.

RGAPCHANGEMAX Function that results in the maximum

change in RELATIVEGAP between the
last n iterations, where n = the number of
iterations to process.

RGAPCHANGEAVE Function that results in the average

change in RELATIVEGAP between the
last n iterations, where n = the number of
iterations to process.

AADMIN Function that results in the minimum AAD

between the last n iterations, where n = the
number of iterations to process.

AADMAX Function that results in the maximum AAD

between the last n iterations, where n = the
number of iterations to process.

AADAVE Function that results in the average AAD

between the last n iterations, where n = the
number of iterations to process.
AADCHANGEMIN Function that results in the minimum
change in AAD between the last n
iterations, where n = the number of
iterations to process.

AADCHANGEMAX Function that results in the maximum

change in AAD between the last n
iterations, where n = the number of
iterations to process.

AADCHANGEAVE Function that results in the average

change in AAD between the last n
iterations, where n = the number of
iterations to process.

RAADMIN Function that results in the minimum RAAD

between the last n iterations, where n = the
number of iterations to process.

RAADMAX Function that results in the maximum RAAD

between the last n iterations, where n = the
number of iterations to process.

RAADAVE Function that results in the average RAAD

between the last n iterations, where n = the
number of iterations to process.

RAADCHANGEMIN Function that results in the minimum

change in RAAD between the last n
iterations, where n = the number of
iterations to process.

RAADCHANGEMAX Function that results in the maximum

change in RAAD between the last n
iterations, where n = the number of
iterations to process.

RAADCHANGEAVE Function that results in the average

change in RAAD between the last n
iterations, where n = the number of
iterations to process.

PDIFFMIN Function that results in the minimum PDIFF

between the last n iterations, where n = the
number of iterations to process.

PDIFFMAX Function that results in the maximum PDIFF

between the last n iterations, where n = the
number of iterations to process.

PDIFFAVE Function that results in the average PDIFF

between the last n iterations, where n = the
number of iterations to process.

PDIFFCHANGEMIN Function that results in the minimum

change in PDIFF between the last n
iterations, where n = the number of
iterations to process.

PDIFFCHANGEMAX Function that results in the maximum

change in PDIFF between the last n
 iterations, where n = the number of
iterations to process.

PDIFFCHANGEAVE Function that results in the average

change in PDIFF between the last n
iterations, where n = the number of
iterations to process.

RMSEMIN Function that results in the minimum RMSE

between the last n iterations, where n = the
number of iterations to process.

RMSEMAX Function that results in the maximum

RMSE between the last n iterations, where
n = the number of iterations to process.

RMSEAVE Function that results in the average RMSE

between the last n iterations, where n = the
number of iterations to process.

RMSECHANGEMIN Function that results in the minimum

change in RMSE between the last n
iterations, where n = the number of
iterations to process.

RMSECHANGEMAX Function that results in the maximum

change in RMSE between the last n
iterations, where n = the number of
iterations to process.

RMSECHANGEAVE Function that results in the average

change in RMSE between the last n
iterations, where n = the number of
iterations to process.
Highway Program > Phases > CONVERGE phase > Example

Exam ple
PHASE=CONVERGE
IF (ITERATION < 6) BREAK; Do not even test for Iterations 2-5
IF (GAP < GAPCUTOFF)
BALANCE = 1
BREAK
ENDIF
IF (GAPCHANGEAVE(3) < 0.006 && GAPCHANGEMAX(3) < 0.009 &&
ABS(GAPCHANGEMIN) < 0.009) BALANCE = 1
ENDPHASE
Highway Program > Phases > CONVERGE phase > Example

Exam ple
; This example implements the opposite of the default stopping criteria which is to
stop if ANY of the convergence measures go below the values specified on the
PARAMETERS statement. In this example the assignment would stop only when ALL
criteria fall below their specified values.
PHASE=CONVERGE
IF (GAP<GAPCUTOFF & RGAP<RGAPCUTOFF & AAD<AADCUTOFF &
RAAD<RAADCUTOFF & RMSE<RMSECUTOFF & PDIFF<PDIFFCUTOFF)
BALANCE = 1
ENDIF
ENDPHASE
Highway Program > Control statements

Control statements
The following control statements are available in the Highway program.

Co ntro l
s ta te me nt D e s c rip tio n

ABORT Quit current program

ARRAY Set user arrays

BREAK Break out of current process

COMP Compute variables from expressions

CONTINUE Go to end of current loop

EXIT Terminate current phase

FILEI Input files

FILEO Output files

FILET Set path for temporary files

FILLMW Fill work matrices

FUNCTION Define Volume, TimeAdjustment, and Cost

functions

GOTO Jump immediately to :label statement

IF ... ELSEIF ... ELSE Define IF ENDIF block

... ENDIF

JLOOP ... Define a loop for destination zones (J)

ENDJLOOP

LINKLOOP ... Control a link loop for processing link

ENDLINKLOOP records in the ILOOP phase

LOOKUP Define lookup tables (see Chapter 3,

“General Syntax”)

LOOP ... ENDLOOP Define a user controlled loop

PARAMETERS Set static parameters

PATHLOAD Build path, load path, compute selected link

matrices

PRINT Print variable values

PRINTROW Print a row of a matrix

PROCESS ... Set process (phase) blocks

ENDPROCESS

REPORT Set standard reports

SET Set multiple variables/arrays to same value

SETGROUP Set link group codes

SORT Sort user arrays

SPDCAP Set Speed and Capacity table values

TURNS Designate intersections where turn volumes

are to be accumulated
Highway Program > Control statements > ABORT

ABORT
Aborts the entire run.
Keywords include:
• MS G

Use ABORT to terminate the program and return a fatal code to Cube Voyager. It normally
is not used, but allows for termination due to some conditions that can be detected in the
process. For example: if it is discovered that an LOS matrix is empty when it should
have data, the run should be aborted.
A B OR T k e y wo rd

Ke y wo rd D e s c rip tio n

MSG |S| Optional message that can be printed

when the program terminates. For
readability, Citilabs recommends 100
characters or less.
Highway Program > Control statements > ABORT > Example

Exam ple
IF (MW[1][I] != 0) ABORT ;Intrazonal present in MW[1]
Highway Program > Control statements > ARRAY

ARRAY
Declares user single-dimension arrays. Keywords include:
• V A R =size

Use ARRAY to allocate user arrays that are to be used in the process. An array is
different than a variable in that it represents vectored data. Values stored to arrays must
be numeric. String values cannot currently be stored in an array. When an array is
referenced, it should include an index [], and if the index exceeds the size, the program
may fatally terminate. Arrays can be useful for different processes. ARRAY statements
are not dynamic (stack oriented); they are allocated prior to any stack operations. When
an array variable appears in a SET statement, all the cells in the array are set to the
same value.
A R R A Y k e y wo rd

Ke y wo rd D e s c rip tio n

VAR |I| Name of the variable that is to be

allocated according to the specified
size. VAR must be a unique name. The
size following the keyword is the
highest index possible for VAR. Size
may be either a numeric constant, or a
special name. Special names are:
ZONES, NODES, LINKS (or
NUMLINKS).
Highway Program > Control statements > ARRAY > Example

Exam ple
ARRAY sum_toll=20
sum_toll[NI.CLASS] = sum_toll[NI.CLASS] + VOLTOT

ARRAY VMT=LINKS
Highway Program > Control statements > BREAK

BREAK
Breaks out of a loop.
Upon encountering BREAK, the script immediately passes control to the statement after
the associated loop.
If BREAK is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the
statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP
(J is reset to 1).
If BREAK is not within a LOOP or JLOOP block, the script terminates processing for the I
zone but does not bypass output and zonal reporting statistics.
Highway Program > Control statements > BREAK > Example

Exam ple
LOOP L1=1,3
IF (condition)
statements
ELSE
BREAK ; jump to IF statement
ENDIF
ENDLOOP
IF (condition) BREAK ; no more processing for this origin zone
Highway Program > Control statements > COMP

COMP
Computes a variable, matrix, or matrix element from an expression.
Keywords and sub-keywords include:
• MW
m EXCLUDE
m INCLUDE

• VAR

Usage:
VAR=expression
MW[n]=expression, INCLUDE=list of J zones, EXCLUDE=list of J zones

Use the COMP statement to compute variable and work matrix values.
COMP k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

MW |KN| Value for a working matrix. You

can specify this keyword in two
formats:
• MW[n] — Defines the
index n of a working
matrix. Matrices can
contain up to MAXMW
sub-matrices, as indexed
by n. The index n may be
either a constant or a
variable name.
The program solves the
expression for all values of
J (1 through Zones), filtering
values indicated by any
INCLUDE or EXCLUDE lists
on this statement.
Within a JLOOP statement,
the program only solves the
expression one time only,
with J being the value of the
loop’s current J.
• MW[n][c] — Defines the
value for column c in
working matrix n. The
second index, c, must be
between one and Zones.
The program solves the
expression one time only,
with J being the loop’s J if
 within a JLOOP, or 1, if not.

MW E XCLU D E |IP| Optional. Values of J excluded

when computing the MW[n]
expression. As the program
internally loops on J, the
program compares J to the
values in the EXCLUDE list. If the
current J is on the list, the
program does not evaluate or
store the expression for that J.
Specified values can range
from 1 to the highest zone
number.
Filter applies to all MW[n]
values on the COMP statement.
Not permitted if COMP
statement within JLOOP ...
ENDJLOOP block.
Always processed after
INCLUDE subkeyword.
By default no zones are
excluded.

MW IN CLU D E |IP| Optional. Values of J included

when computing the MW[n]
expression. As the program
internally loops on J, the
program compares J to the
values in the INCLUDE list. If the
current J is not on the list, the
program does not evaluate or
store the expression for that J.
Specified values can range
from 1 to the highest zone
number.
Filter applies to all MW[n]
values on the COMP statement.
Not permitted if COMP
statement within JLOOP ...
ENDJLOOP block.
By default all zones are
included.

VAR |KN| Name of a variable where the

result of expression is to be
stored. The name may be as
long as desired (within reason).
The expression is solved one
time for each encounter, with J
being either one (not in JLOOP),
or the value of the JLOOP J. If
expression results in a
character string, the variable
must be a character string
variable. All variables are
assumed to be numeric
variables, unless their first
appearance as a result in a
COMP statement is with an
 expression that results in a
character string. Examples:
abc = '123'
def = 123
abc = def ; invalid: abc has
been declared a string
abc = abc + '456' ; valid
abc = abc + def ; messy -- don’t
mix
jkl = 1 ; jkl is declared
numeric
jkl = xyz ; invalid: xyz is
declared a string (later)
xyz = 'xyz' ; xyz is declared a
string

If a COMP statement includes any INCLUDE or EXCLUDE filters, the filters apply to all MW[]=
values, and special matrix functions on the statement, no matter where they appear on
the statement. EXCLUDE is processed after INCLUDE. INCLUDE and EXCLUDE may not be
specified within a JLOOP.
Highway Program > Control statements > COMP > Special matrix variables

Special m atrix variables

MW[] MI.n.name MI.n.matnum

The expression is a standard Cube Voyager numeric expression, but there are some
special variables that may be used within it:
Ma trix v a ria b le s

V a ria b le D e s c rip tio n

MW[Rexpression] Value from any work matrix; the column

index (not explicitly expressed) will be
supplied as J. Rexpression may contain
nested MW[]; be careful! MW[Rexpression]
[Cexpression] is the value from any work
matrix for zone Cexpression.

MI.n.name Value from the MATI[n].name matrix; the

column index (not explicitly expressed) will
be supplied as J. The row index [n], must be
a constant. MI.n.name[Cexpression] is a
variation; the column index is computed.
Valid matrix names contain only
alphanumeric characters, spaces, and
underscores (_). If matrix names have
spaces, then you must include the entire MI
matrix reference in double quotes to
recognize the name. For example:
MW[1]="MI.1HBW TRIPS"

MI.n.matnum Value from the MI[n].matnum matrix; the

column index (not explicitly expressed) will
be supplied as J. The row index [n] and the
matnum must be constants.
MI.n.matnum[Cexpression] is a variation; the
column index is computed.

ZI.n.name Value from the ZDATI[n].name matrix; the

zone index (not explicitly expressed) will be
supplied as I.
ZI.n.name[Cexpression] is a variation; the
zone index is computed.
Highway Program > Control statements > COMP > Special matrix functions

Special m atrix functio ns

ROWSUM ROWCNT ROWMIN ROWMAX ROWAVE ROWFIX ROWFAC LOWEST

LOWCNT ROWADD ROWMPY ROWDIV
In addition to the standard numeric expression functions (abs, exp, int, ln, log, max, min,
round, sqrt — see Chapter 3, “General Syntax” for more details), some special purpose
functions are available. The matrix-oriented functions process all cells in a matrix
(subject to the restrictions of any INCLUDE and EXCLUDE lists), and should not be
used within JLOOP blocks and MW[]= expressions. Normally, they should be used only
as VAR = ROWFUNC(#).
Most of these functions could be duplicated with a combination of MW[]= statements.
The function format has two advantages: coding is much easier, and processing is more
efficient. Combining functions on a single statement is permissible; they will be
processed in appropriate order. Example: DUMMY = ROWFAC(3,1.5) + ROWFIX(3)
will factor matrix 3 and then convert it to integer.
In the following matrix function descriptions, the first argument (mw) indicates the work
matrix to process, and must be specified. If “lo,hi” is allowed, and lo is supplied, and hi is
not, hi will be set to lo. Lo and hi are inclusive values. If an invalid argument is detected
by a function, the function will return a zero, without any diagnostics.
Ma trix func tio ns

Func tio n D e s c rip tio n

LOWCNT The actual number of cells that was

used in the summary is stored in the
variable LOWCNT. Warning: Dividing
by LOWCNT if it is 0, will cause a
program error message (too many
will be fatal).

LOWEST(mw,n) Sum of lowest n cells.

LOWEST(mw,n,lo,hi) Sum of lowest n cells, including only

cells with values greater than or equal
to lo, and less than or equal to hi.

LOWEST(mw,n,lo,hi,z,z,...) Sum of lowest n cells, including only

cells with values greater than or equal
to lo, and less than or equal to hi, and
exclude the values for J=z,z,...

LOWEST is quite useful for computing

an intrazonal value based upon the
proximity to the nearest zones. The
range of arguments is to provide for
most types of situations. With lo and
hi, it is possible to exclude possible
dummy zones that may appear as
zero in the row. With z, specific zones
can be excluded; normally, the
 intrazonal cell (I) would be excluded.
This exclusion is in addition to any
that may be on an EXCLUDE list.
NOTE: Zeros are treated as regular
numbers in LOWEST function. Since
all MWs are initialized to zeros,
caution should be exercised when
applying LOWEST function with no
range specified.

ROWADD(d,s1...sn) Add matrices MW[s1], MW[s2], . . .

MW[sn] to matrix MW[d].
Same as:
MW[d] = MW[s1] + MW[s2] +
MW[sn]

ROWAVE(mw) Average cell value, including only

cells with values not equal to 0.

ROWAVE(mw,lo,hi) Average cell value, but include only

cells with values greater than or equal
to lo, and less than or equal to hi.

ROWCNT(mw) Number of cells with values not equal

to 0

ROWCNT(mw,lo,hi) Number of cells with values greater

than or equal to lo, and less than or
equal to hi; can include 0.

ROWDIV(d,s) Divide MW[d] by MW[s] making all

divided-by-zero cells equal to 0.
Same as:
JLOOP
IF (MW[s] == 0)
MW[d] = 0
ELSE
MW[d] = MW[d] / MW[s]
ENDIF
ENDJLOOP

ROWFAC(mw,fac) Factors the row by fac.

Same as MW[mw] = MW[mw] * fac

ROWFIX(mw) Convert mw to integer values (start at

column intrazonal + 1, with rounding
factor = 0).

ROWFIX(mw,n) Convert mw to integer values (start at

column n, with rounding factor = 0).

ROWFIX(mw,n,rnd) Convert mw to integer values (start at

column n, using specified rounding
factor).

ROWFIX converts the values in each

cell of the matrix to integers (that is,
drops all fractional portions of the
number) in such a manner to ensure
the integer total is consistent with the
original total. It converts each cell to
an integer value after adding the
rounding factor and the accumulated
fractional portions from the previously
 treated cells. With a rounding factor of
0 each cell is truncated and its
fractional remainder is carried to the
next cell. With a rounding factor of 0.5,
each cell is rounded to the nearest
integer and the difference (original –
rounded) is carried to the next cell.

If the process always began at zone

1, the lowest numbered zones would
never get their fair share of the
fractions. To eliminate this bias, the
default condition is to start at the cell
after the intrazonal cell and wrap
around until the intrazonal cell is the
last cell processed. The optional
second argument specifies which cell
the process is to end with.

ROWMAX(mw) Maximum value in the row.

ROWMIN(mw) Minimum value in the row.

ROWMPY(d,s) Multiply MW[d] by MW[s]

Same as:
MW[d] = MW[d] * MW[s]

ROWSUM(mw) Row total.

ROWSUM(mw,lo,hi) Row total, but include only cells with

values greater than or equal to lo, and
less than or equal to hi.
Highway Program > Control statements > COMP > Example 1

Exam ple 1
MW[mw][I] = LOWEST(mw,4,0.01,5,I)/max(1,LOWCNT)/2
Highway Program > Control statements > COMP > Example 2

Exam ple 2
MW[2]=J
MW[K]=MW[2] * MW[5]) / SQRT(A*MW[3][MW[22]])
A=1, B=2, MW[A]=A+B INCLUDE=1-5,8,47-93
MW[3]=5*A, MW[4]=MW[3]*2, MW[K][I%10+1]=ODD,
INCLUDE=1-100,401-500, EXCLUDE=90,93,452
; applies to the MW[]s=
ABC=LOOKUP(DEF)*3
/* move input matrices to work areas */
MW[11]=MI.1.1, MW[12]=MI.1.2, MW[13]=MI.1.3
MW[21]=MI.2.1, MW[22]=MI.2.2, MW[23]=MI.1.3
Highway Program > Control statements > CONTINUE

CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements.
If CONTINUE is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the
appropriate ENDLOOP or ENDJLOOP statement. Otherwise, processing for the I zone is
terminated, but output statistics will not be bypassed.
Highway Program > Control statements > CONTINUE > Example

Exam ple
LOOP L1=1,3
IF (!(condition)) CONTINUE
ENDLOOP
IF (condition) CONTINUE
; no more processing for this origin zone
LOOP L2=K1,K2,KINC
LOOP L3=L2,L2+5
IF (condition) CONTINUE ; jump to ENDLOOP for L3
ENDLOOP
ENDLOOP
Highway Program > Control statements > EXIT

EXIT
Terminates stack processing. When the program encounters an EXIT statement, the
program goes to the end of I-loop processing.
Highway Program > Control statements > EXIT > Example

Exam ple
IF (expression) EXIT
Highway Program > Control statements > FILEI

FILEI
NOTE: See “FILEI” on page 50 for general information about FILEI and for important
limitations when using Application Manager.

FILEI, its keywords and subkeywords define the input HIGHWAY’s input data files.
Keywords and sub-keywords include:

• J U N CT ION I • T URNPENI
m N m LIST
m PERIOD m MISSINGLINK
m SET • ZD A T I

• LOOKU P I m AVE

• MA T I m AVEX0
• NET I m CNT
• SUBAREANET I m DEFAULT
• T OLLMA T I m FIRST
m ENTRYGATE m LAST
m EXITGATE m MAX
m NETIENTRY m MIN
m NETIEXIT m NAME
m NETITOLLROAD m SELECT
m TOLLFACTOR m SUM
m TOLLROUND m Z
m TOLLS

Matrix data is read dynamically (at the start of each I-loop), and must be in origin zone
(I) order, whereas zonal data is read prior to the initiation of the I-loop, and need not be
in any specified order. Data from MATI and ZDATI files are accessed via stack
statements, and are identified as MI.n.name and ZI.n.name. The n designates subscript
of the file, name designates the matrix name or number. Cube Voyager matrices can
have names and/or numbers, other matrices have only numbers, and zonal data files
have names only. Example: MI.1.3 indicates matrix number 3 on the MATI[1] file.
ZI.6.POP indicates the POP variable from ZDATI[6] file. Valid matrix names contain only
alphanumeric characters, spaces, and underscores (_). If matrix names have spaces,
then you must include the entire MI matrix reference in double quotes to recognize the
name. For example:
MW[1]="MI.1HBW TRIPS"

On the FILEI statement the subscript is either explicitly, or implicitly, specified. MATI=...
defaults to MATI[1], and MATI[3]=name3,name4,name5 sets up MATI[3], MATI[4], and
MATI[5]. Since it is required that ZDATI files have variables explicitly defined for them,
the vector form of ZDATI (ZDATI=file1, file2...) will be treated as an error.
When an input file is used in an expression, it may have an additional subscript
appended to it to specify a zone number. For matrices, the subscript references the
column within a row, and for zonal data, it references the nth item in the vector. Zonal
data can be viewed as having zones rows with one column per zone, or as one row
having zones columns (user’s choice, it doesn’t matter). If there is no subscript specified,
the current value of J is used. J will always be in the range 1-zones. Example: MI.6.3[I]
accesses the intrazonal cell. ZI.1.TRMTIME[I] and ZI.1.TRMTIME[J] reference the
origin and destination terminal times, respectively.
TURNPENI designates a file that contains intersection movement functions and penalties.
This file may be read and kept in memory for use during any path development
processes (specified with PATH on PATHLOAD statements). Even if the file is designated
on a FILEI statement, the penalties will not automatically be applied during path
development; the user must specify which penalties are to be applied on each PATH
selection. The file has two sections: functions and movements.
The function section is optional, but allows the user to specify that a penalty is to be
computed from an expression. If a function contains a C variable (movement capacity),
the penalty will be revised between iterations in the ADJUST phase.
Each record in the movement section designates a specific movement (a-b-c), a set
identifier for the movement, and the penalty to be assessed. For example,
a b c set # turnpen
-------- ------ ---------
11 23 15 1 -1 (Prohibitor)
1 12 13 3 2 (Constant)
15 58 36 8 FUNC1(500) (Function)

The penalty may be a prohibition, a fixed unit penalty, or a reference to a function in the
function section. A prohibition is designated as the constant -1. It is the user’s
responsibility to make sure that the penalty values are in the proper scale and units as
the paths to which they are being applied.
Turn functions are designated as numeric expressions that may contain constants and
the variables: T, C, PrevPen. T is the turn volume at the intersection (it may alternatively
be named TURN); C is the capacity of the movement, and PrevPen is the penalty that
was used in the previous iteration.
T is vectored (that is, it may contain an index []). T is the total volume for the movement;
it is 0 at the first iteration, but is the result of the T=expression on the TURNS statement
after the first iteration. If there is no TURNS statement, T will automatically be the sum of all
loadings. T[1] would indicate the turning volume associated with any PATHLOAD
VOL[1] statements. T[0] and T are the same variable. If a T is specified with an index for
which there is no PATHLOAD VOL[index], the value of T[] in the expressions will be 0.
Care must be taken if a fixed penalty is to be established for the first iteration, and then
dynamic values are to be used after the first iteration. This is usually done by using the
MAX function in the expression. For example: Func1=MAX(2.00,T/C*5.00). In this
example, since T would be 0 on the first iteration, the initial penalty would be 2, and it
would vary after the first iteration. If the 2 unit penalty was to remain in effect for all
iterations, and be increased according to the T/C ratio, the expression would be:
Func1=2+ T/C *5.
C is obtained from the record in the movement section as an argument of the function.
To apply the above Func1 (2+T/C*5), with C=500, the movement record would be
coded as: 100 200 201 0 Func1(500). This designates that the movement 100-200-201
is to be penalized 2 units on the first iteration and then the penalty will be increased
according to a T/C ratio (with C being 500) after the first iteration. If there were no C
affixed to the Func1 on the movement record, the C would be considered as 0 in the
computations. (Warning: Be careful not to create divided-by-zero errors when applying
functions with C=0.)
TURNPENI function records are structured as: FuncName=expression. The name is
what the user desires, and the expression is any valid numeric expression that may
contain numbers, standard functions, T, C, PrevPen.
TURNPENI movement records are structured as: A B C Set Penalty (one set per
record). The records are white space delimited (space, comma). A is the entry node to
the intersection, B is the intersection node, and C is the exit node. Set is a number in the
range of 0-8. If the set number is 0, it is applied any time that penalties are in effect, no
matter what the designated sets are. There may be up to 9 records (sets 0-8) for the
same movement. During path building, when the movement is detected and PENI= is
specified in the PATHLOAD statement, the penalty process will automatically apply set
0, if there is a set 0 for the movement. If there is no set 0, the penalty is assumed to be 0.
Then it will check all the other possible sets for the movements; it there are additional
sets, the penalty for the highest set number that matches the highest PENI designation
for the PATH process will be used. NOTE that any movements that have functions
specified will cause the B node to be included as a node for which TURNS are to be
kept, and will be reported on the TURNVOLO file.
JUNCTIONI designates a file or Cube Geodatabase network containing descriptions of
junction models. The format of the file is discussed in Chapter 7, “Intersection
Modeling.” N specifies a list of nodes where the intersection modeling is to be invoked
during the ADJUST phase. However, invoking intersection modeling for a node where
there is no model description has no effect. PERIOD is the model period in minutes. It is
used to convert the assigned volumes into units of per hour, and it is one of parameters
of the queuing delay equation.
Executing a junction model produces turning delays that may be applied during the next
iteration of capacity restraint. This form of output is similar to a set of turn penalties, and
the turn penalty set numbering system applies. The SET keyword designate the turn
penalty set to contain the model results. Turn penalty records may be applied with
higher or lower priority (that is, set number) than the calculated delays.
FILE I k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

JUNCTIONI |KF| Specifies the input junction file or

Cube Geodatabase network. Note if
intersection data is loaded from a
Cube Geodatabase network, the
JUNCTIONI keyword designates the
filename followed by a backslash
and the name of the Cube
Geodatabase network.

JUNCTIONI N |IP| Optional. Specifies the nodes where

intersection modeling is to be
invoked. A junction that is not
invoked has no effect. Invoking
intersection modeling where there is
no junction described has no effect.
Only those nodes that both have a
model description and are listed in
this list are actually modeled.
By default, Cube invokes
intersection modeling for all the
nodes specified in the junction file.

JUNCTIONI PERIOD |R| Duration of the model period in

minutes. The input demand matrix
should be in units of vehicles (or
PCU) per model period.
NOTE: If PARAMETERS
MODELPERIOD is used, this
subkeyword will be ignored.

JUNCTIONI SET |I| Specifies which turn penalty set will

contain the delays calculated by the
junction models

LOOKUPI |FKV999| Name of file containing records for a

lookup function implemented with the
LOOKUP control statement.
Equivalent to the FILE keyword of the
LOOKUP control statement. You
must index LOOKUPI.

MATI |KFV20| Specifies the input matrix files. The

files must be Cube Voyager, TP+,
MINUTP, or Tranplan binary
matrices.

NETI |KF| Specifies the input highway network

file. It MUST be a Cube Voyager or
TP+ binary network, or a Cube
geodatabase network stored in an
MDB or GDB geodatabase. If
 specifying a Cube geodatabase
network, the NETI keyword
designates the filename followed by
a backslash and the name of the
Cube geodatabase network. The
link variables from the network are
referred to as LI.name.

SUBAREANETI |KF| Specifies a file that contains subarea

network information. In most cases
the network will be one created by
the polygon subarea network
extraction process in Cube. If Cube is
used to create the subarea network,
the subarea will be set up properly,
with the proper node renumbering
and cordon link specification. This
keyword is used in conjunction with
the FILEO SUBAREAMATO = and
PATHLOAD SUBAREAMAT[] =
expressions. See “ILOOP phase” on
page 175 for details about subarea
processing.
The node records of the network
contain both the subarea node
number (N) and the number
(OLD_NODE) that N was in the
network from it was extracted, The
records also contain the variable
SUB_TYPE that indicates the type of
node with relationship to the original
network.
The SUB_TYPE values are:
• 0=insignificant
• 1=internal (subarea) zone
• 2=external gateway to the
subarea network
• 3=internal exit from subarea
If these values are altered from
those that Viper or Cube Base wrote,
the results will be unpredictable.

TOLLMATI |KF10| Specifies the input toll matrix files.

The specified files are toll-point to
toll-point records and may be input
as DBF, MDB table or delimited text
records.
See “Path-based tolls” on page 162.

TOLLMATI ENTRYGATE |S| Field name or field number on the

input TOLLMATI file that holds the
entry toll gate numbers. If the input
file is a DBF or MDB table, the
ENTRYGATE value must be a field
name from the input table. If the input
file is a delimited ASCII file then the
ENTRYGATE value is a field
number on the input file. If
ENTRYGATE is not specified, the
first field on the input file will be used.
Valid value range for entry toll gate
 numbers is 1-999.

TOLLMATI EXITGATE |S| Field name or field number on the

input TOLLMATI file that holds the
exit toll gate numbers. If the input file
is a DBF or MDB table, the
EXITGATE value must be a field
name from the input table. If the input
file is a delimited ASCII file then the
EXITGATE value is a field number
on the input file. If EXITGATE is not
specified, the second field on the
input file will be used. Valid value
range for exit toll gate numbers is 1-
999.

TOLLMATI NETIENTRY |S| NETI link attribute that contains the

entry gate numbers. The numbers in
this link attribute correspond to the
numbers in the ENTRYGATE field of
the TOLLMATI file. If NETIENTRY is
not specified the name will default to
TOLLENTRY and it is assumed this
link attribute name is available on
the input NETI network.

TOLLMATI NETIEXIT |S| NETI link attribute that contains the

exit gate numbers. The numbers in
this link attribute correspond to the
numbers in the EXITGATE field of
the TOLLMATI file. If NETIEXIT is not
specified the name will default to
TOLLEXIT and it is assumed this link
attribute name is available on the
input NETI network.

TOLLMATI NETITOLLROAD |S| NETI link attribute that contains the

toll road indicator. All links with a
non-zero value for this attribute are
considered part of one or more
closed toll systems in the network.
The numbers in this link attribute can
be used to correspond to one or
more unique toll systems in the
network. If NETITOLLROAD is not
specified the name will default to
TOLLROAD and it is assumed this
link attribute name is available on
the input NETI network.

TOLLMATI TOLLFACTOR |R10| Up to 10 toll factors may be

specified, one for each toll set. If
specified the factor is applied to all
toll values in the TOLLMATI file for
the set. The TOLLFACTOR provides
a method for quickly factoring tolls
for sensitivity analysis.

TOLLMATI TOLLROUND |R| Allows for rounding of tolls or

factored tolls to the nearest units
specified. For example if a toll,
coded in the TOLLMATI file for a
particular entry to exit movement is
US$1.50, and a TOLLFACTOR of 1.2
has been specified to test a 20% toll
 increase, the factored toll value
would be US$1.80. By specifying
TOLLROUND=0.25, the applied toll
value for this movement would then
be US$1.75 (that is,. rounded to the
nearest US quarter dollar).

TOLLMATI TOLLS |S10| Field name(s) or field number(s) on

the input TOLLMATI file that holds
the toll values. Up to 10 toll value
sets may be coded. If the input file is
a DBF or MDB table, the TOLLS
value(s) must be a field name from
the input table. If the input file is a
delimited ASCII file then the TOLLS
value(s) is a field number on the
input file. If TOLLS is not specified,
the third and subsequent fields on
the input file will be used for up to 10
toll sets. Tolls can be coded as true
toll values or in any units the user
desires.

TURNPENI |KF| Specifies the input file that contains

the turn penalty functions and
movement records.

TURNPENI LIST |?| Switch to designate if the penalty

values are to be listed to the print file.

TURNPENI MISSINGLINK |I| Designates the level of severity for

any turning movements where links
appear in the TURNPENI file, but the
A-B and the B-C links are not both in
the NETI network.
Possible values:
• 0 — Ignore completely (default
value)
• 1 — Write warning
• 2 — Generate fatal error

ZDATI |KFV10| Specifies the input files containing

zonal data. There can be up to 10
zonal data files. Zonal data is data
which is specific for each zone.
Every zonal record must include a
field that identifies the zone to which
the record data applies. Aside from
the zone number, any fields from the
record can be extracted and used
by the program.
The file format can be any of: ASCII,
DBF, MDB, or a Cube Voyager or
TP+ binary network. The program
will try to detect what type of file it is. If
it can not identify the file as a DBF,
MDB, or a Cube Voyager or TP+
network, it will assume ASCII. When
the program detects a Cube
Voyager or TP+ network file, it opens
the node database portion of the file
as zonal data.
 If the file is of ASCII format, the fields
to be extracted must be named and
identified on the ZDATI statement by
either relative field number, or by
exact column positions on the
records. The field that contains zone
number must be specified using 'Z='
keyword.
If the file is a database or a Cube
Voyager or TP+ network, it is not
necessary to name the fields to be
extracted. All fields will be extracted
and can be referenced, in the script,
by existing field names from the input
file. The specification of zone
number field is optional for those two
file formats. If 'Z=' is present, the
specified field will be used to extract
zone number. Otherwise, the
program will try to determine the
zone number field based on file type.
For DBF and MDB files, the program
will go through all field names to find
a match with one of the following
possible zone field names, in the
given order: {Z, I, J, ZONE, ZONA,
TAZ}. The first matched name will be
used to extract zone number. (Note:
For files with more than one possible
zone field from the list above, it is
recommended to specify zone
number field explicitly to ensure the
correct field is used.) For Cube
Voyager or TP+ network files, node
numbers (N) will be used as zone
numbers by default.

ZDATI AVE |SV| Average of all records. 1

ZDATI AVEX0 |SV| Average of all records, where the

value from the file records is not 0. 1

ZDATI CNT |SV| Count of the records that contain the

variable. 1

ZDATI DEFAULT |R| Value with which to initialize the array

for the named variable. Then, if there
are no records for a zone, or the field
is blank on a record, this value will
be used.

ZDATI FIRST |SV| Directly from the record from the

FILEI with the lowest index[]. 1

ZDATI LAST |SV| Directly from the record from the

FILEI with the highest index []. 1

ZDATI MAX |SV| Maximum value of all the records. 1

ZDATI MIN |SV| Minimum value from all the records.

1

ZDATI NAME |S| Identifies a data variable that is to be

 extracted from each record. Only the
variables named will be extracted. If
the file is a dbf, the value for each
name is the name from the dbf
dictionary. In most dbf cases,
name=name would be the standard,
but it is not necessary to keep the
same names. For text files, the value
assigned to name is either a field
number (delimited format), or the
columns (fixed format) where the
variable is located on the record. All
names must be specified with the
same format; the first name value
(including Z) establishes the format. If
the first value is a number, fixed
format is assumed; otherwise,
delimited format is assumed. If
delimited format is specified, each
name value MUST end in a number.
It doesn’t matter what string
precedes the number (the value
need not be prefixed with a string).
Example: Z=#1,POP=#2, AREA=3,
SALES=xxx4. These are all be valid,
because Z specified triggered
delimited format. Z=1-5,POP=#2
would be invalid because Z
specifies fixed format.

ZDATI SELECT |S3| Used to cause selective reading of

zonal data records from ASCII files.
The program will compare a field
from each record with the string
specified in SELECT[1], and if the
comparison fails, the record is
bypassed. This selection is not used
if SELECT is not specified. The
second SELECT value specifies the
field to be compared with. If the value
is a number, it designates the
beginning column of the comparison
field on the input record, and an
optional third value can be specified
to designate the ending column. The
second and third values must both
be numeric and should be
separated by a dash. If the second
field is not numeric, but ends with a
number (Example: #1), it is assumed
that the value indicates a relative
field number on the data record; that
field is the comparison string. The
third value is ignored if the second
value is a free field definition.

ZDATI SUM |SV| Sum of all the records. 1

ZDATI Z |S| Identifies where the zone number

identifier is found on each data
record; Z MUST be specified, even if
the file is a dbf. Z is a special case
for name= (below).
 to use in obtaining the value for the variables that are listed following the keyword. The values for the
1
variables will be obtained only from file records that contain the variable. A variable may appear in only one
keyword list; any variables that are not in any list will be set to LAST.

Caveat: The program establishes a buffer to read file records into. It has to know how
long a buffer is required. With DBFs and fixed format records, the required length is
known, but with delimited format, the required length can not be estimated exactly. For
delimited files, the record length is estimated by multiplying the highest field number by
10. If the estimated length is inadequate, a dummy variable with a high field number can
be specified to generate a larger record length.
Highway Program > Control statements > FILEI > Example

Exam ple
NETI=network.net ; TPP binary network file
MATI=test11.dat, test12.dat ; MINUTP binary matrix files
MATI[4]=tppltrips.mat ; TPP or MINUTP matrix file
TURNPENI=time.pen, MISSINGLINK=1
ZDATI[1]=housing.txt, Z=#1,DU1=#2,DUPLEX=3,MULTI_FAMILY=4,
CONDO=5,RETIREMENT=6
ZDAT[4]=pop.txt,Z=1-5,poptotal=6-15,popmale=16-25,popfemale=26-35,
popyouth=36-45,pop19-65=46-55,popsr=56-65,
poptotal=sum, popmale=cnt
Highway Program > Control statements > FILEO

FILEO
Specifies files that the Highway program outputs.
Keywords and sub-keywords include:

• E S T MD A T O • T OLLV OLO
m LINKTOICP m INCLUDE0
m NAME m MOMO

• E S T MICP O m MULTITOLL
m CONFVAR m NAMES
m COUNTVAR m OFFGATES
m DEFAULTCONF m ONGATES
m FORMAT m PATHSETS
m SCREENLINE m TOLLMATI
m VAR m TOLLSETS

• J U N CT ION O m VOLSETS
• MA T O • T REEO
m COMBINE m ALTNODEFIELD
m DEC m APPEND
m FORMAT m CELLTYPE
m MO m DELIMITER
m NAME m FORM
• NET O m FORMAT
m APPEND m LISTALTNODES
m DEC m LISTCOLNUMS
m EXCLUDE m LISTNETNODES
m INCLUDE m LISTLINKS
• PAT HO m MAXPERLINE
m COSTDEC m ORIGINTYPE
m ITERS m ROWTYPE
• P R IN T O • T URNPENO
m APPEND • T U R N V OLO
• S U B A R E A MA T O m DEC
m DEC m DELIMITER
 m FORMAT m FORMAT
m NAME m INCLUDE0

• T OLLV OLO m NAMES

m DEC m QUEUEDATA
m DELIMETER m VARS
m FORMAT

Use FILEO to specify the number and types of files that are to be written by the program.
Requested matrices are written for every origin zone for every iteration, but are
combined into a single “combined” matrix at the end of the application. A single network
with appended volumes and associated variables is written at the end of the application.
A turning volume file must be requested if a TURNS statement is used.
There MUST be a NETO specified if assignment is to be made; there would be no use in
running the program if there was no way to obtain the results. By default the NETO file will
contain all the input variables from NETI plus the variables V, VT, VC, TIME, CSPD
(congested speed), VDT (vehicle distance traveled), VHT (vehicle hours traveled) and
a Vn, and VnT for every VOL[n] specified on any PATHLOAD statements. VT and VnT
are the non-directional (two-way) counterparts of V and Vn. (Non-directional volumes
can be turned off using NETO EXCLUDE=T_.) These appended variables will have an
assignment number appended to their names. If there were no prior assignment result
variables appended to the link records, the assignment number will be 1. Thus, the first
assignment variables will be named V_1, VT_1, VC_1, TIME_1, V1_1, V1T_1 etc. If the
NETI file contains any variable whose name ends in _#, the NETO appended variables will
have an appended number that is one greater than the highest _# from NETI.
The following list summarizes the abovementioned additional output NETO attributes
from the assignment:
• T IME _ = Congested travel time

• CS P D _ = Congested speed

• V n_ = Volume for class n for every VOL[n] specified on any P A T H LOA D statement

• V_ = Total volume calculated applying the V function

• VT _ = Non-directional (two-way) total volume (counterpart of V)

• V nT _ = Non-directional (two-way) volume for class n (counterpart of Vn_)

• V C_ = V over C (capacity) ratio

• VDT _ = Vehicles x Distance travelled

• VHT _ = Vehicles x Time travelled

If the NETO file is being written to a Cube geodatabase network in an MDB file, the
source geometry for links in the output network will come from the geometry of the input
network. If the input network is a binary network, then the output NETO file will have no
associated geometry and will be displayed as straight-line links when opened in the
Cube GIS window.
The FILEO TOLLVOLO [#] file output keyword, along with its sub keywords, provides users
with the capability to output gate-to-gate toll trips captured with the TOLLPATHSET keyword
in PATHLOAD statement. Three different file formats (text, DBF and matrix) are supported
with this keyword. Below is a description of each of the keywords. The keyword
descriptions follow the same format as used in Cube help.
FILE O k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ESTMDATO |FV20| Specifies the file name(s) for the

output screenline data file(s)
(*.DAT) required by Cube
Analyst. Up to 17 files are
allowed.
It is not necessary to have a
ESTMDATO for every
ESTMICPO. Only one
ESTMDATO file needs to be
created if multiple ESTMICPO
files are created with the same
COUNTVAR setting.

ESTMDATO LINKTOICP |I| Number specifying which ICP file

the output is linked to. The
default is to link to the ICP file
with the same index (e.g.
ESTMDATO[12] links to
ESTMICPO[12]).

ESTMDATO NAME |SV| Specifies the names for the

screenlines in the ESTMDATO
file. There need not be a name
for each screenline, but it is
suggested that they be included
to help in documentation of the
file. A default name of “SL A-B”
will be supplied by Cube
Voyager if no NAME is provided
for a screenline.

ESTMICPO |FV20| Specifies the file name(s) for the

output intercept file (*.ICP) that is
required by Cube Analyst. Up to
17 files are allowed.

ESTMICPO CONFVAR |S20| Specifies the link array that

contains the count confidence
values. The value may be an
lw.array or li.array.

ESTMICPO COU N T V A R |S20| Alternate to using VAR. Specifies

the link array that contains the
counts. Links that have values in
this array will be trapped for
 inclusion in the matrix estimation.
The value may be an lw.array or
an li.array. If using COUNTVAR,
then do not specify VAR.

ESTMICPO D E FA U LT CON F |I| Default confidence value

applied if CONFVAR is not set or
contains an illegal value (<=0).
Valid range is 1 to 10,000.

ESTMICPO FOR MA T |I| Toggles the format of the output

ICP file(s).
• 0 — legacy format; will only
work with original Analyst.
• 1 — optimzed format (50-
80% smaller file size); will
only work with Analyst
Drive.
Default is 0.

ESTMICPO SCREENLINE |S20| Specifies the link array that

contains screenline numbers for
the links. If there is no value in
the array for a link that has a
count, the program will assign a
screenline number to it
automatically. If SCREENLINE is
not specified, the program will
assign a unique screenline
number to each link with a value
in the VAR array. If a link has a
value in the SCREENLINE array,
but does not have a value in the
VAR array, the link is ignored in
the matrix estimation. The value
may be an lw.array or an li.array.

ESTMICPO VAR |S20| Replaced by COUNTVAR.

Specifies the link array that
contains the counts. Links that
have values in this array will be
trapped for inclusion in the matrix
estimation. The value may be
an lw.array or an li.array.
If using VAR, do not use
COUNTVAR. However, Citilabs
recommends replacing all
instances of VAR with
COUNTVAR.

JUNCTIONO |F| Specifies the file name where

the results of junction modeling
may be stored for display.

MATO |FV20| Specifies the filename for the

MATO specified.

MATO COMBINE |?| This keyword, when set to True,

is used to combine the matrix
assignments estimated in each
iteration of the highway
assignment. The all-or-nothing
assignments are weighted
 (averaged) in a manner
consistent with the volume
combination method defined by
PARAMETERS COMBINE.
The averaging is performed
every n iterations, where n is
specified by PARAMETERS
MATOADJUST.
The most common application
of this feature would be with
SELECTLINK analysis, where it
is required. The MATRIX
program does not have an
equivalent function.
Default value is True.

MATO DEC |SV*| Specifies the format for the MOs.

There is a separate DEC for
each MO. The value can be a
number or the character D or S.
• A number value (0-9)
indicates the output matrix
cells are to be integerized
with that many decimal
places preserved. Only
the first digit of DEC is read;
ie DEC=14 is read as 1.
• The letter S indicates that
the cells are to be stored
with three decimal places,
while D indicates four
decimal places.
All internal work matrices are
maintained in double precision
floating point format (eight bytes
per cell), but can be written to
MATO files in different formats in
order to keep the storage
requirements to a minimum. The
reader is urged to read the
description of FILEO MATO DEC
in Chapter 9, “Matrix Program” for
a more detailed explanation of
the possible binary options. If no
DEC value is defined for a matrix,
the default value will be integer
with 2 implied decimal places.
DEC is not applicable when
FORMAT=MINUTP is specified.

MATO FORMAT |S| Specifies the format of the

MATO:
TPP
— Standard Cube Voyager
or TP+ matrices (default)
MINUTP
— Standard MINUTP
matrices

MATO MO |IVP| Specifies the MWs that are to be

included in the MATO. MW may
 be indexed, but care should be
taken to not leave holes in the
final list. The highest implicit or
explicit index establishes how
many matrices will be included
in the file. The same MW may
be included more than one time.
Example: MO=1-5,11-15,
MO[20]=1, MO[6]=31
establishes that 20 matrices will
be written. Nine of the matrices
(11-19) will be dummy because
no data was entered for them.
The output matrices are
numbered monotonically
beginning with 1.

MATO NAME |SV| Specifies the names for the TP+

and Cube Voyager matrices.
Each MO does not require a
name, but including names
helps document the file. Valid
matrix names only contain
alphanumeric characters,
spaces, and underscores (_).
Cube Voyager programs
reading the file can reference
the matrices by name and/or
number.

NETO |F| Specifies the file name for the

NETO; there must be NETO if
assignment is being performed.
The NETO can be a binary Cube
Voyager/TP+ network.
Alternatively, NETO can point to
a Cube geodatabase network
stored in an MDB file (personal
geodatabase) or GDB (file
geodatabase) by designating
the file name followed by a
backslash and the Cube
geodatabase network name.
NOTE: Networks stored in
personal (MDB) geodatabases
are limited to a maximum of 255
fields, including the default
geodatabase network fields
(OBJECTID, SHAPE,
SHAPE_LENGTH, A, B,
GEOMTERYSOURCE, etc).

NETO APPEND |I| Specifies that the variables that

are appended to NETO will have
their assignment number set to
this value. APPEND=5 would
cause V, VC,TIME,V1... to be
named V_5, VC_5, TIME_5,
V1_5, etc.

NETO DEC |I| Specifies the number of decimal

places to written to the NETO
Volume fields. Values in the
range 1-5 are valid.
NETO EXCLUDE |S20| Specifies that the NETI variables
that have names ending with the
specified strings are to be
excluded when copying NETI
records to NETO. Thus,
EXCLUDE=_1 will exclude all the
first assignment variables.
EXCLUDE=T_ is a special value
that can be used to specify that
the A-B and B-A values are NOT
to be summed and included in
the link records.

NETO INCLUDE |S20| Specifies that certain new

variables are to be included in
the NETO file. The intent of this
keyword is to allow the user to
compute LW.vars and
selectively include them in the
NETO. All LW.vars named by
this keyword will appear in the
NETO as LW_NAME_# (# is the
assignment number value). You
can specify a single variable
with INCLUDE, but this only adds
a variable that has the same
value in each record. The
variable will appear as name_#
in NETO.

PATHO |F10| Specifies the name of a file upon

which paths from a PATHLOAD
statement are to be written.

PATHO COSTDEC |I| Specifies how many decimal

places are to be maintained in
the cost values when they are
written to the PATHO file. The link
cost values will be rounded to
this many decimal places; this
allows for more efficient
compressing of the data. The
value must range from 1-5.
Default value is 2.

PATHO ITERS |I| Indicates which iterations to write

the PATHO file. Possible values
are:
• 0 — All iterations
• 1 — First iteration only
• 2 — Last iteration only
• 3 — First and last iteration
only
Default is 0.

PRINTO |KF| Specifies the name of the file

where the output from a PRINT
statement is to be directed using
PRINT PRINTO=#

PRINTO APPEND |?| See APPEND under “PRINT” on

 page 69.

SUBAREAMATO |KF| Specifies the file where binary

matrices of values from subarea
processing are to be written.
The matrices on the file will be
the final combination of values
from all iterations. The number of
matrices will be set by the
highest PATHLOAD
SUBAREAMAT[] index. The
zonal configuration for the O/P
matrices will be based upon the
renumbering scheme obtained
from the FILEI SUBAREANETI
file.

SUBAREAMATO DEC |SV20| Specifies the maximum number

of decimal places to retain in the
SUBAREAMATO matrices. The
values may be 0-9, S for a
single-precision number, or D for
a double-precision number. If
not specified, or any other value
is coded, the values will default
to 2. This keyword is ignored if
the format is not TPP.

SUBAREAMATO FORMAT |C| Specifies the desired output

format for SUBAREAMATO
matrices. Possible values are
TPP, MINUTP, and TRANPLAN; if
anything else is specified, or it is
not specified at all (normal), the
default is TPP.

SUBAREAMATO NAME |SV20| Specifies the individual names

for the SUBAREAMATO matrices.
This keyword is ignored if the
format is not TPP.

TOLLVOLO |FV20| Specifies the filenames for the

TOLLVOLO files to store the toll
gate to toll gate trips. If the name
is a geodatabase table, then the
output will be a database table
in the geodatabase and the
FORMAT keyword value will be
ignored. See Example 11: Using
TOLLMATI and TOLLVOLO.

TOLLVOLO DEC |SV*255| Specifies the decimal settings

for the matrix tables for MAT
format or the setting for the
TRIPS field for the other formats.
The default is 2. For matrix
format, there is a separate DEC
for each MO. The value can be
a number between 0 and 9 (the
number of preserved decimals),
or the character D or S for
double and single precision
floating point values. Care must
 be taken to match up the list of
MO and the list of DEC,
especially when wildcard
characters are used in the MO
specifications, which can
generate multiple tables from a
single MO specification and will
require multiple matching DEC.
For database and text format,
only the first DEC value (DEC
[1]) is used. It is the number of
decimal places that the TRIPS
values are printed with.

TOLLVOLO D E LIME T E R |S| Delimiter character that is written

in a delimited TXT file. If this
keyword is specified, the file will
be delimited with this character.
If it is not specified, the file will be
fixed-field format

TOLLVOLO FOR MA T |S| Specifies the format of the

TOLLVOLO file:
• "TXT (default) - ASCII text
format either in fixed format
or delimited (if DELIMITER
is specified). There is no
header for this file; each
record contains the fields:
m o ONGATE - the on
gate number as
coded in the network
link
m o OFFGATE - the off
gate number as
coded in the network
link
m o ONLINKA - The on
gate link A node
m o ONLINKB - The on
gate link B node
m o OFFLINKA - The off
gate link A node
m o OFFLINKB - The off
gate link B node
m o MATINUM - The
TOLLMATI number
specified in the
PATHLOAD statement
m o TOLLSET - The toll
set number specified
in the PATHLOAD
statement
m o PATHSET - The
TOLLPATHSET
number specified in
the PATHLOAD
 statement
m
o VOLSET - The VOL
set number specified
in the PATHLOAD
statement
m o TRIPS - The number
of toll trips in this group
All fields except the ONGATE,
OFFGATE and TRIPS field can
be omitted by specifying a '-' in
the NAMES keyword for that
position.
If MULTITOLL is set to true,
• "Then there could be
multiple on-gate and off-
gate columns
corresponding to the
maximum number of toll
gate pairs, the toll trips
use.
• "The On-Off gate pair
columns will appear at the
end and not at the start
• "ONLINKA, ONLINKB,
OFFLINKA and OFFLINKB
will not be included
• "DBF - a standard DBF file
will be written with each
record containing the
same fields as listed in the
TXT format. The names of
the fields can be changed
from the default name with
the NAMES keyword by
position (e.g. NAMES[3] is
the name for the ONLINKA
field). All fields except the
ONGATE, OFFGATE and
TRIPS field can be
omitted by specifying a "-"
in the NAMES keyword for
that position.
• "MAT - Standard Cube
Voyager or TP+ matrices.

TOLLVOLO IN CLU D E 0 |?| A flag that when set true

indicates that records with 0 trip
value will also be written to the
file. The default value is false.

TOLLVOLO MO |SV255| Specifies the toll trip matrices

that are to be included in the
TOLLVOLO file. This keyword is
applicable only if the output
format is MAT. The MO keyword
should not be indexed because
by using wildcard characters,
multiple output tables can be
generated. The toll trip groups
are identified by 4 key values:
 TOLLMATI, TOLLSET,
PATHSET and VOLSET. The
format for the MO specification is
M#T#P#V#. The # character can
be a number for a specific set or
can be a '?' for a wildcard
character. For example,
M1T2P3V4 specifies the output
of the group TOLLMATI 1, toll set
2, path set 3 and VOL set 4. If the
specification includes one or
more wildcard characters, all
groups matching the
specification will be output in
separate tables. For example,
M2T?P3V? specifies all groups
from TOLLMATI 2 and path set 3
will be output to the matrix file. If
the run has the groups
M1T2P3V4, M2T2P3V4,
M2T3P3V5, M3T2P3V4, then the
M2T?P3V? specification will
include the M2T2P3V4 and
M2T3P3V5 tables in the output
file. However, wildcard table
inclusions are constrained by
the TOLLMATI, TOLLSETS,
PATHSETS and VOLSETS
specifications. The same MO
specification may be included
more than one time.
The default for MO is M?T?P?
V?, which will include all groups
(up to a maximum of 255 tables)
in the output file subject to
TOLLMATI, TOLLSETS,
PATHSETS and VOLSETS
selections if they are specified

TOLLVOLO MU LT IT OLL |?| Outputs all on gate-off gate

pairs, if a toll trip set goes
through more than one set of
gate pairs. If set to true, the
output file will contains the fields:
MATINUM, TOLLSET,
PATHSET, VOLSET, TRIPS,
ONGATE1, OFFGATE1,
ONGATE2, OFFGATE2 ... etc.
up to highest on/off gate pairs
found in the data. The default is
false. The MULTITOLL keyword
works in all text and database
output format but will be ignored
in matrix format output.

TOLLVOLO N A ME S |SV255| Specifies the names for the

matrix tables for MAT format or
the field names for the other
formats. For matrix format, the list
of NAMES will match the MO
specification by position. If not
specified, the default name for a
matrix table is M#T#P#V#. The
 '#' character represents the
specific set numbers for that
table. Care must be taken to
match up the list of MO and the
list of NAMES, especially when
wildcard characters are used in
the MO specifications, which can
generate multiple tables from a
single MO specification and will
require multiple matching
NAMES. If in doubt of how many
tables may be generated from a
wildcard specification, use the
default NAMES instead.
For database output format
(DBF and geodatabase), the list
of NAMES is the user specified
names of the 11 output fields.
The default names are:
ONGATE, OFFGATE, ONLINKA,
ONLINKB, OFFLINKA,
OFFLINKB, MATINUM,
TOLLSET, PATHSET, VOLSET,
TRIPS. All fields except the
ONGATE,OFFGATE and TRIPS
field can be omitted by
specifying a '-' in the NAMES
keyword for that position. For
example, NAMES=OnNum,
OffNum, -, -, -, - will name the first
two fields as OnNum and
OffNum instead of ONGATE and
OFFGATE and omit the next 4
fields (ONLINKA, ONLINKB,
OFFLINKA, OFFLINKB) in the
output table. The order of the
names should correspond to the
original order of the 11 fields
irrespective of whether
MULTITOLL is true or false.
For text output format, the list of
names are not used in the output
file but the '-' name specification
can still be used to omit certain
fields in the output record

TOLLVOLO OFFGA T E S |IVP1000| List of off gate numbers that will

be included in the output file. If
this keyword is not specified,
then by default, all OFFGATES
will be output

TOLLVOLO ON GA T E S |IVP1000| List of on gate numbers that will

be included in the output file. If
this keyword is not specified,
then by default, all ONGATES
will be output

TOLLVOLO PAT HSET S |IVP1000| List of path set numbers that will
be included in the output file for
all formats except MAT. For MAT
format, the list will control the
inclusion of output tables when
wildcard characters are used in
 the MO specification. If this
keyword is not specified, then by
default, all PATHSETS will be
output.

TOLLVOLO T OLLMA T I |IVP10| List of TOLLMATI numbers that

will be included in the output file
for all formats except MAT. For
MAT format, the list will control
the inclusion of output tables
when wildcard characters are
used in the MO specification. If
this keyword is not specified,
then by default, all TOLLMATIs
will be output.

TOLLVOLO T OLLS E T S |IVP10| List of toll set numbers that will

be included in the output file for
all formats except MAT. For MAT
format, the list will control the
inclusion of output tables when
wildcard characters are used in
the MO specification. If this
keyword is not specified, then by
default, all TOLLSETS will be
output.

TOLLVOLO V OLS E T S |IVP1000| List of VOL set numbers that will

be included in the output file for
all formats except MAT. For MAT
format, the list will control the
inclusion of output tables when
wildcard characters are used in
the MO specification. If this
keyword is not specified, then by
default, all VOLSETS will be
output.

T REEO |KS8| Specifies the output file name

where the results of shortest path
trees may be stored. Up to 8
files are allowed.
See more on TREEO from
Example 10: Shortest Path
Trees Using TREEO.

TREEO ALTNODEFIELD |S| Optional. Specifies if the

alternative node number is to be
written in the output file.

TREEO APPEND |?| Optional. Flag indicating whether

to overwrite or append to the
output file. Possible values:
• T - Append the data to the
specified file.
• F - Overwriting the existing
file when writing the data.

TREEO CELLTYPE |I| Specifies the cell values in the

output file. Possible values are:
• 0 - link number (default)
• 1 - node number
 • 2 - sequence node
number

• 3 - alternative node
number

TREEO DELIMITER |S| Delimiter character for CSV file

output. Default value is ','.

TREEO FORM |I| Specifies maximum field width

for columns. Up to 3 values are
allowed under FORM. These
three values specify the field
width for path set name, origin
nodes and cell values (columns)
respectively.
e.g., FORM=4,6,7

TREEO FORMAT |S| Specifies the format of the

TREEO file. Possible values are
TXT (default) and CSV.

TREEO LISTALTNODES |?| Flag that indicates if the program

writes the node alternative
number in sequential order in the
output file. Default value is F. To
print alternative node numbers,
ORIGINTYPE should be set to 1
and ALTNODEFIELD specified.

TREEO LISTCOLNUMS |?| Flag that indicates if the program

writes a row of column index in
the output file. Default value is F.

TREEO LISTNETNODES |?| Flag that indicates if the program

writes the node number in
sequential order in the output
file. Default value is F.

TREEO LISTLINKS |?| Flag that indicates if the program

writes the information on all links
in the network in the output file.
Default value is F.

TREEO MAXPERLINE |I| Specifies the number of column

per line in the output file. If the
number of columns defined by
ROWTYPE is more than the
MAXPERLINE, then the rows will
be split into two or more lines.
Also, the beginning cell index is
added after the origin number
and before the first cell value.

TREEO ORIGINTYPE |I| Specifies if alternative zone

number is to be listed in the
output file instead of the original
zone number. Possible values
are
• 0 - original zone number
(default)
• 1 - alternative zone
number
 NOTE: If set to 1, users must
specify ALTNODEFIELD.

TREEO ROWTYPE |I| Specifies the number of columns

for each origin (each record) in
the output file. Possible values
are:
• 0 - number of nodes
(default)

• 1 - highest node number

• 2 - number of links

TURNPENO |F| Specifies the file name where

the movement delays from the
junction model and/or the turn
penalties from the turn penalty
file will be written. In order to get
the final travel time and cost
skims from an assigned network
it is necessary to pass the
loaded network back through
the Highway program and build
and skim the paths from the
loaded network. The
TURNPENO file allows the
movement delays computed by
the Junction Model to be
included in the path skims by
using the TURNPENO file from
the assignment as the
TURNPENI file for the skims.
The data structure is the same
as that of the TURNPENI file but a
comment field is added to
indicate the movement is delay
is from the junction model in lieu
of a turn penalty or restriction. An
example of the output is show
below.
2606 2621 2773 1 0.08
;junct
2635 2621 2606 1 0.15
;junct
2635 2621 2615 1 0.15
;junct
2635 2621 2615 2 -1.00
2635 2621 2773 1 0.15
;junct

TURNVOLO |F| Specifies the filename where the

turning volumes are to be written.
There may be more than one
TURNVOLO specified; each
may have a different format.
Users must also specify
TURNS to instruct program to
accumulate turning volumes,
otherwise, the TURNVOLO will
be empty. The default format for
this file is binary so that Cube
can display it directly. Please
note that the presence of the
 VARS keyword may alter the
overall application of this
statement.
See “Example using
TURNVOLO” on page 241.

TURNVOLO DEC |I| Specifies the number of decimal

places to preserve when the file
is either DBF of TXT.

TURNVOLO DELIMITER |c| Character that is written in a TXT

file. If this keyword is specified,
the file will be delimited with this
character. If it is not specified,
the file will be fixed-field format. If
the value is a character, it should
be enclosed within quotes; but it
may also be specified as a
number that represents the
desired character (for example,
9=TAB).

TURNVOLO FORMAT |S| Specifies the format for the file

(must be BIN, DBF, or TXT).
NOTE: FORMAT=BIN will
automatically be reset to TXT if
VARS= is specified on the
statement.
• BIN — Binary format that is
usable only by Cube. The
structure is:
m One header record (at
least 64 bytes long):
0-1
total length of this
record (bytes)
2-3
length of each turn
record
3-6
bits whose position
represents the
presence of a turn
volume
0:
1 always on for T0
1:
1 if T[1] in the data
records, 0 if not in
data record
2:
1 if T[2] present, o if
not
3-31
same for T[3]...
7-64
”Cube Voyager
TURNVOL
pppp.nnnn
 HIGHWAY date...”
pppp
is the Cube
Voyager project
prefix
nnnn
is the Cube
Voyager sequence
number
m Individual records
(length set in header):
0-1
Anode
2-3
Bnode
3-4
Exit Node
5-12
T[total] All Ts are
double precision
13-20
1st T (T1)
21-28
2nd T
• DBF — A standard DBF file
will be written with each
record containing the
Anode, Bnode, ExitNode,
T[0], and any appropriate
T# values. The DBF
header will name the
variables that are in the
data records.
(continued)

TURNVOLO FORMAT • TXT — ASCII format either

(continued) in fixed format or delimited.
There is no header for this
file; the structure of each
record is:
m Anode, Bnode,
ExitNode, T,T# — (The
user has to know
which individual Ts
are written to the file).
The T values will be
determined either by
the DEC keyword, or
internally by the
program. Each
volume will be
formatted
appropriately. If
DELIMITER is
specified, the fields
will be written with only
the delimiter
separating them. If no
 DELIMITER, the fields
will be in fixed width
format; the program
will determine the size.
Note that VARS= will
cause this format to
change.

TURNVOLO INCLUDE0 |?| Flag that when set false

indicates that a turn movement
with T values all equal to 0, is to
not be written to the file. The
default value is true.

TURNVOLO NAMES |S25| May be used if both VARS= and

FORMAT=DBF are specified. The
names are aligned with the
VARS fields and then placed into
the created dbf file. Optionally,
the NAMES may be indexed [] to
set the alignment for renaming
only specific variables.

TURNVOLO QU E U E D A T A |?| Flag that indicate if the statistics

of the intersection modeling is to
be written out into the DBF file. If
it is set to true, it must be used
combined with FORMAT=DBF.
Eight extra columns (INITQ,
FINALQ, QFLOW, CAPACITY,
RANDOMNESS, DELAY,
FLOW0DELAY AND LOS) will
be written into the DBF file.
Default value is false.

TURNVOLO VARS |S25| Specifies which variables are to

be written to the file. Note that if
VARS is specified, FORMAT=BIN
will be reset to FORMAT=TXT, or
if there is no FORMAT specified,
that it will default to TXT. Any of
the following variables may be
specified (in any order, and may
even be repeated): A B C T T1
T2…Tn, where n is the highest
VOL in the application.
Optionally, the variable name
may have a standard PRINT
form appended to it (enclosed
within parenthesis). If decimals
are to be printed with the values,
it is suggested that an
appended format be specified
instead of DEC=. If a delimiter is
desired, FORMAT=TXT,
DELIMITER= must be specified.

PATHLOAD must include the keyword ESTMO=num, where num is between 1 and 20
corresponding the ICP file to write to, in order for the trips assigned from that statement
to be included in the matrix estimation. There may be more than one PATHLOAD
statement including ESTMO. It does not make sense to have ESTMO=num on a PATHLOAD
statement that does not have VOL[]= on it. PATHLOAD must have the keyword PATHO=#
in order to output the path file specified with FILEO PATHO=
Highway Program > Control statements > FILEO > Example using TURNVOLO

Exam ple using TURNVOLO

MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y
MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7
NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2
TURNVOLO=AlternateA.Trn.Bin, format=BIN
TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0
TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0
TURNVOLO=AlternateA.Trn.TXT, VARS=b(5) a(6) c(6) t(10.2) t1(10.2) t2(8.2)
TURNVOLO=AlternateA.Trn.TXT, format=dbf, vars=a(5),b(5),c(5),t(8.2),
t1(8.2),t2(8.2), names= Enter thru exit Total Cars Trucks
Highway Program > Control statements > FILEO > Example using multiple output screenline data files (DAT), and output
intercept files (ICP)

Exam ple using m ultiple o utput screenline data files (DAT), and o utput intercept files (ICP)
RUN PGM=HIGHWAY
FILEO ESTMDATO[05] = NewSL22NF.DAT,
LINKTOICP=7,
ESTMDATO[10] = NewSL24NF.DAT,
LINKTOICP=17,
ESTMDATO[12] = NewSL23NF.DAT,
; default to match ESTMICPO[12]
ESTMICPO[02] = NewSL21NF.ICP,
countvar=li.count, FORMAT=1, ; new
; format
ESTMICPO[07] = NewSL22NF.ICP, countvar=li.count, FORMAT=0, ; old
; format
ESTMICPO[12] = NewSL23NF.ICP, countvar=li.cost, FORMAT=1,
ESTMICPO[17] = NewSL24NF.ICP, countvar=li.cost, FORMAT=1
FILEO NETO = NEWLOAD.NET
FILEI NETI = dtown2.net

PAR MAXITERS=5

PROCESS PHASE=LINKREAD
IF (LI.SPDCLASS=33) ADDTOGROUP=1
IF (LI.SPDCLASS=45) ADDTOGROUP=2
IF (LI.SPDCLASS=55) ADDTOGROUP=3
ENDPROCESS

PROCESS PHASE=ILOOP
MW[1]=10
MW[2]=20
MW[3]=30
MW[4]=40
PATHLOAD PATH = COST, VOL[1]=MW[1], EXCLUDEGROUP=1, ESTMO=2
PATHLOAD PATH = COST, VOL[2]=MW[2], EXCLUDEGROUP=2, ESTMO=7
PATHLOAD PATH = COST, VOL[3]=MW[3], EXCLUDEGROUP=3, ESTMO=12
PATHLOAD PATH = COST, VOL[4]=MW[4], ESTMO=17
ENDPROCESS
ENDRUN
Highway Program > Control statements > FILEO > Example

Exam ple
MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y
MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7
NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2
TURNVOLO=AlternateA.Trn.Bin, format=BIN
TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0
TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0
ESTMICPO=ESTMO.ICP, VAR=LI.COUNT, SCREENLINE=LW.SCREENLINE
ESTMDATO=ESTMO.DAT, NAME='SL#1','SL#2','SL#3', NAME[5]='SL#5'

; The ESTMDATO and ESTMICPO keywords will not need an index because
; they default to index 1. However, the PATHLOAD ESTMO keyword value
; will have to be changed from "T" to "1" for the script to work.
Highway Program > Control statements > FILEO > Example

Exam ple
/*
Commands to generate a path file.
*/
FILEO PATHO[1]=myfile.pth, costdec=2, iters=0
.
.
.
PATHLOAD PATH=TIME, PATHO=1, INCLUDECOST=F, NAME=TIME_PATH, ALLJ=T
Highway Program > Control statements > FILEO > QUEUEDATA Example

QUEUEDATA Exam ple

RUN PGM=HIGHWAY
FILEI TURNPENI = "myTurnPen.pen"
FILEO JUNCTIONO = "myJunOut.INT"
FILEO TURNVOLO="myTurnOut.DBF",FORMAT=DBF, QUEUEDATA=T
FILEO NETO = "myLoaded.NET"
FILEI JUNCTIONI = "myJunctions.ind",
period=60,set=1
FILEI NETI = "myBase.net"

PARAMETERS COMBINE = AVE

PARAMETERS RELATIVEGAP=0.0001 GAP = 0.0, MAXITERS=10
PARAMETERS AllowAllUTurns=T ;model U-turns movements at all nodes unless it is
banned in the Junction file

ZONESMSG=1
TURNS N=1-99999

PROCESS PHASE=LINKREAD
C = LI.CAP
ENDPROCESS

PROCESS PHASE=ILOOP
MW[1]=500
PATHLOAD PATH = TIME, VOL[1]=MW[1], PENI=1,2
ENDPROCESS

PROCESS PHASE=ADJUST

FUNCTION {
V=VOL[1]
TC = T0 *(1+0.18*(V/C)^8.5)
}
ENDPROCESS

ENDRUN

Output of the DBF file:

Highway Program > Control statements > FILET

FILET
Specifies where the Highway program writes various temporary files.
Keywords include:
• PAT H

FILE T k e y wo rd

Ke y wo rd D e s c rip tio n

PATH |S| Specifies the path to the disk area

where any temporary files are to be
written.

D IS T R IB P A T H |S| Specifies the temp file folder for an

intra-distribution run. This is to speed
up run time when multi-steps are
distributed to different machines but
the distributed steps will do intra
distribution to slaves on the same
machine. This avoids using a network
drive to pass data between the slaves
and the main process. The option
defaults to the working directory. The
restriction on that is both the main and
the slaves must be referencing the
same location, either on a local drive
that both the main and the slaves can
access (basically the main and the
slaves must be on the same
machine), or a network drive that are
mapped to the same drive letter for
both the main and the slaves.

E S T MP A T H |S| Specifies the file path for saving the

temporary ESTM files when doing
intra distribution. Similar to the FILET
DISTRIBPATH keyword, the
ESTMPath keyword defaults to the
working directory. The restriction on
that is both the main and the slaves
must be referencing the same
location, either on a local drive that
both the main and the slaves can
access (basically the main and the
slaves must be on the same
machine), or a network drive that are
mapped to the same drive letter for
both the main and the slaves. The
specified folder must already exist or
else the specification will be ignored
and the temp file will be written to the
working directory.

The value for PATH is entered as a standard operating system path. If not specified, it will
default to the path in the environment variable named TMP, or TEMP. The logic for
determining the appropriate path, and opening the files is:
• If the PATH=' ', use current directory.

• If the PATH is specified, use it.

• If not specified, and TMP is, use TMP.

• If the operation fails, Fatal.

Highway Program > Control statements > FILET > Example

Exam ple
PATH=' ' ; use current directory
PATH=..\ ; up a directory
PATH=c:\ ; root of c:
Highway Program > Control statements > FILLMW

FILLMW
Fills work matrices.
See “FILLMW” on page 629 for a complete description.
Highway Program > Control statements > FUNCTION

FUNCTION
Defines special functions.
Keywords include:
• COS T

• TC

• V

Use FUNCTION statements to enter single expressions for computing certain values. The
statements are inoperable by themselves, and can be anywhere in the input stream, the
program dictates when they will be processed. It is recommended that they be placed
prior to the first PHASE statement or within the major phase in which they will be
processed. If there is no function for a type, a default function will be used. The V
function may be defined one time only. Each of the other functions is entered with an
index [] to indicate which LinkClass it is to be applied to. All the functions can be on one
FUNCTION statement, or they can be on individual statements, or some combination of
both. To reduce confusion, some users may wish to code the functions on a single
FUNCTION statement with a block control.

FU N CT ION k e y wo rd s

Ke y wo rd D e s c rip tio n

COST |NV999| Computes the cost for a link. COST is processed

in the LINKREAD and ADJUST phases to
compute the cost. In LINKREAD, it is applied
after the stack statements.
In the ADJUST phase, it is applied during
capacity restraint, usually following a TC
application, and after the user stack statements
are completed. This is the only way to alter the
cost values.
NOTE:
• LW.xxx equations containing variables which
are a function of Volume changes (such as
TIME) cannot be used with FUNCTION COST
when standard equilibrium processing is used
(COMBINE EQUI). Such arrays are updated
following the equilibrium processes in the
ADJUST phase, and will generate incorrect
results if directly referenced in FUNCTION
COST. Instead, the LW variables must be
replaced with their formula from the cost
function definition. For example:
Wrong Usage:
LW.Temp=TIME + dist_fac*li.distance
COST= LW.Temp *2
Correct Usage:
LW.Temp= dist_fac*li.distance
 COST= (TIME + LW.Temp) *2
For an implementation example, Citilabs
recommends reviewing Multiple user class
assignment using generalized cost functions.
• When referencing individual volume sets in
FUNCTION COST, V1, V2, etc, must be used
instead of VOL[1]. VOL[2], etc. For an example,
please see Multiple user class assignment
using generalized cost functions.

• If FUNCTION COST is not defined, Highway

will use TIME as the cost for the calculation
of convergence, and for the computation of
Lambda for the Frank-Wolfe algorithm
(COMBINE E QU I).

TC |NV999| Computes the congested time on a link by

LINKCLASS. TC functions are the labels in the
software given to volume delay functions
(commonly referred to as VDFs). TC stands for
congested time. The LINKREAD phase of this
program allows the user to associate every link
in the network with an internal LINKCLASS
variable. The TC functions can be indexed by
LINKCLASS to specify different volume delay
relationships for different classes of facility. If no
LINKCLASS is defined for a link it defaults to
LINKCLASS=1. If no TC functions are defined
then a default TC function is applied. The default
TC function is the standard BPR with the form:
TC[1] = T0 *(1 + TCCOEFF * (V/C) ^ TCEXP)
where TCCOEFF defaults to 0.15 and TCEXP
defaults to 4 if values are not specified with
PARAMETERS. Specifying TC[1] alters the
function. The user can also code their own
functional form if the BPR form is not what is
desired. In general,
TC[#]=f(T0, V/C, TCCOEFF, TCEXP) but the user
is free to experiment with any forms that make
sense to them for their application.
NOTE:
• If individual volume sets are required for
TC functions, then V1, V2, etc must be used
instead of VOL[1], VOL[2], etc. Otherwise,
the results will be incorrect.
• When computing Lambda for the Frank-
Wolfe algorithm (COMBINE E QU I), any
LW variables (such as TIME) which are a
function of volume change should not be
directly referenced in TC functions; the
results will be incorrect. Instead, the same
formulas used to generate the work
variables should be employed within
FUNCTION COST.

V |N| Computes the total volume on a link after an

iteration. It is applied in the ADJUST phase. If
there is no V function, V is assumed to be the
sum of all the VOL sets (V[1] + V[2] + ... + V[n]).
Some times the total volume should not be the
sum of all the VOLs. For example: if a separate
select link VOL set is being accumulated in
addition to the total VOL set, that VOL set should
be excluded from the total volume. Another
example would be if one of the VOL sets is for a
vehicle type for which it is desired to equate to a
passenger car equivalent.
NOTE: When using multiple volume sets,
FUNCTION V must reference VOL[1], VOL[2], etc,
and not V1, V2, etc, to obtain correct results. For
an implementation example, Citilabs recommends
reviewing Multiple user class assignment using
generalized cost functions.
Highway Program > Control statements > FUNCTION > Example

Exam ple
FUNCTION {
V = VOL[1] + VOL[3] + VOL[10]*1.3
TC[1] = T0 * (1 + 0.20 * (V/C) ^ 6)
TC[201] = MIN(T0*5, T0 * (1.5 + 0.18 * (V/C) ^ 4))
COST[255] = TIME * 2
}
Highway Program > Control statements > GOTO

GOTO
Jumps immediately to a named statement.
GOTO label

When GOTO is processed, flow immediately branches to the target statement, named
“:label.” Each GOTO statement must have an associated :label statement. Use care when
the :label statement is within a different IF or LOOP block. The target statement must begin
with a colon (:).

NOTE: GOTO is not valid in the SETUP phase. You cannot place a :label statement inside a
JLOOP statement. However, you can use a GOTO statement inside a JLOOP to jump to a
:label statement outside the JLOOP.
Highway Program > Control statements > GOTO > Example

Exam ple
GOTO buildhwy
GOTO :buildhwy
Highway Program > Control statements > GOTO > Example

Exam ple
GOTO tolls
...
:tolls
...
IF (expression) GOTO :tolls
; It is permissible to go backwards.
Highway Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF

IF ... ELSEIF ... ELSE ... ENDIF

Performs certain operations based on conditions.
IF expression ELSEIF expression ELSE expression ENDIF

Use IF/ENDIF blocks to determine if certain operations are to be performed. IF blocks may
be nested, but they may not overlap LOOP, JLOOP, or other IF blocks. If a variable in the
expression is MI.n.name, ZI.n.name, or MW[], the same rules for indexing in a COMP
statement are applied. MI.n.name or MW[] should realistically only be used within a
JLOOP. Lengthy IF expression solutions could be time consuming; use them judiciously.
Although IF expressions can be quite powerful for zonal selection, sometimes INCLUDE
and EXCLUDE filters may provide a much more efficient selection process (see the
examples below).
You may append the following control statements to a single IF statement:
• BREAK

• COMP

• CONTINUE

• EXIT

• GOTO

• PRINT
Highway Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF > Example

Exam ple
IF (LI.DIST< 20) LIST=a,b,LI.dist; single IF with process
IF (expression) EXIT

IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) )

.
ELSEIF (loop_cntr > 10)
.
ELSEIF (loop_cntr > 5 && diff.time < 32)
.
ELSE
.
ENDIF
Highway Program > Control statements > JLOOP ... ENDJLOOP

JLOOP ... ENDJLOOP

Controls a loop through the columns of a matrix row.
Keywords include:
• J

• E XCLU D E

• IN CLU D E

Each row represents an origin zone and each column represents a destination zone.
Typically, you use JLOOP ... ENDJLOOP blocks for matrix computations that you cannot
complete with a single COMP MW control statement.
JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks.
J LOOP k e y wo rd s

Ke y wo rd D e s c rip tio n

J |I| Optional. List of up to three integers that define the value of

the loop control variable. You may define each integer with
an expression. Specify as:
J=Jbeg, Jend, Jinc
where:
• Jbeg defines the initial value of the loop’s control
variable, J. Default value is 1. If you do not define
Jbeg, you cannot define Jend or Jinc. In that case,
Jend defaults to the number of zones in the network,
and Jinc defaults to 1.
• Jend defines the terminal value of the loop’s control
variable, J. Valid values range from 1 to the network’s
maximum number of zones. If not specified, Jend
defaults to Jbeg, and Jinc defaults to 1.
• Jinc defines the increment for the loop’s control
variable, J. If not specified, set to 1 or -1, depending
on the direction from Jbeg to Jend.
Because the list of values for J can be expressions, you
must separate the values with commas. Enclose
expressions containing commas in parentheses.

EXCLUDE |I| Optional. List of origin zones that the program will not
process. If you include this keyword, the program will not
process statements for these zones, and instead skip to the
next zone.

INCLUDE |I| Optional. List of origin zones that the program will process. If
you include this keyword, the program will only process
statements for these zones.

A JLOOP block causes the program to loop between the JLOOP statement and its
ENDJLOOP statement, moving J from Jbeg to Jend in increments of Jinc. The logic for
JLOOP and ENDJLOOP processing is:
• At JLOOP:
m
If J is specified, establish values for Jend and Jinc, else set J=1, Jend=Zones, Jinc=1.
m
If (J < 1 or J > Zones or Jend <1 or Jend > Zones), terminate fatally.
m
If (statement contains INCLUDE keyword and J is not listed among INCLUDE keyword values)
go to ENDJLOOP.
m
If (statement contains EXCLUDE keyword and J is among listed EXCLUDE keyword values) go
to ENDJLOOP.
m
Process statements within JLOOP.

• At ENDJLOOP:
m
Add Jinc to J.
m
If (Jinc > 0 and J <= Jend) go to statement following JLOOP.
m
If (Jinc < 0 and J >= Jend) go to statement following JLOOP.
m
Control passes to statement following ENDJLOOP.

The program processes all statements between the JLOOP and ENDJLOOP statements,
including COMP MW statements, with the current value of J.
The following statements are valid within a JLOOP block:
• BREAK

• COMP

• CONTINUE

• EXIT

• GOTO

• IF ... ELSEIF ... ELSE ... ENDIF

• PRINT

• REPORT

• SET

NOTE: You cannot place a :label statement inside a JLOOP; a GOTO statement cannot jump
into a JLOOP. However, you can place a GOTO statement inside a JLOOP to jump to a :label
statement outside the JLOOP.
Highway Program > Control statements > JLOOP ... ENDJLOOP > Example

Exam ple
;process only intra zonal values, but exclude externals
JLOOP J=I EXCLUDE 500-535
...
ENDJLOOP
ROWSUM1 = 0 ROWSUM3=0
JLOOP ; get rowsums for matrices
ROWSUM1 = ROWSUM1 + MW[1]
ROWSUM3 = ROWSUM3 + MW[3]
ENDJLOOP
Highway Program > Control statements > LINKLOOP ... ENDLINKLOOP

LINKLOOP ... ENDLINKLOOP

Controls a link loop for processing link records in the ILOOP phase. LINKLOOP serves as
a shorthand for a LOOP statement iterating through available links with a user-defined
index (see Example 1 below).
By default, the link loop processes through all link records at an increment of one. You
can use LINKNO, the default loop index, to reference the current link number. The
program supplies all link arrays the default [LINKNO] in a LINKLOOP block.

NOTE: You can nest LINKLOOP blocks within other blocks such as IF or LOOP, but not
another LINKLOOP. You cannot overlap them with IF blocks.
Highway Program > Control statements > LINKLOOP ... ENDLINKLOOP > Example 1

Exam ple 1
; Print each Link’s number and Distance
LINKLOOP
PRINT LIST="LINKNO=", LINKNO," LI.DISTANCE=",LI.DISTANCE
ENDLINKLOOP

; Equivalent to this LOOP block:

LOOP k=1,NUMLINKS
PRINT LIST="LINKNO=", k," LI.DISTANCE=",LI.DISTANCE[k] ;note [k] index
ENDLOOP
Highway Program > Control statements > LINKLOOP ... ENDLINKLOOP > Example 2

Exam ple 2
; double LW.VAR for even number zones
IF (I%2==0)
LINKLOOP
LW.VAR=LW.VAR*2 ; no [LINKNO] subscript needed
ENDLINKLOOP
ENDIF
Highway Program > Control statements > LOOP ... ENDLOOP

LOOP ... ENDLOOP

Controls a general variable loop.
LOOP Lvar=Lbeg,Lend,Linc
...
ENDLOOP

where:
• Lvar — Name of the loop control variable. Lvar is not protected during the loop;
computational, program, and other LOOP statements can alter its value. Lvar must be
followed by Lbeg, and optionally, Lend and Linc.

• Lbeg — Numeric expression that initializes Lvar.

• Lend — Optional. Numeric expression that Lvar is compared to when processing the
ENDLOOP statement. If not specified, no comparison is made and loop ends at ENDLOOP
statement.

• Linc — Optional. Numeric expression added to Lvar before making the ENDLOOP comparison.
If not specified, Linc is set to 1 (or -1 if Lbeg and Lend are both constants and Lbeg <
Lend; a backwards loop).

Use LOOP…ENDLOOP blocks to repeat a series of statements. LOOP initializes a variable;

ENDLOOP compares the contents of the variable to another value, and branches back to
the statement following the LOOP statement if the comparison fails. You can nest LOOP
blocks, but you can overlap them with IF blocks. The process differs considerably from
JLOOP. The logic is as follows:

• At LOOP:
m
Initialize Lvar to Lbeg.
m
Drop through to next statement.

• At ENDLOOP:
m
If Lend not specified, jump to next statement.
m
Compute Lend.
m
If Linc not specified, set Linc to 1 or –1(if Lbeg and Lend are constants, and Lbeg >
Lend), otherwise compute Linc.
m
Add Linc to Lvar.
m
Compare Lvar to Lend.
m
If (Linc > 0 and Lvar > Lend) jump to statement after ENDLOOP
 m
If (Linc > 0 and Lvar <= Lend) jump to statement after LOOP
m
If (Linc < 0 and Lvar < Lend) jump to statement after ENDLOOP
m
If (Linc < 0 and Lvar >= Lend) jump to statement after LOOP

This logic offers considerable flexibility, but can result in unpredictable results or endless
loops. Endless loops could happen if the Lend and/or Linc values are expressions that
contain variables that could change during the loop. On the other hand, the flexibility
provides for powerful control. The loop will be processed at least one time regardless of
Lend and Linc values. Most uses will involve constants. Because Lvar values can be
expressions, Lbeg, Lend, and Linc must be separated by commas (standard white
space delimiting cannot be interpreted properly).
Highway Program > Control statements > LOOP ... ENDLOOP > Example

Exam ple
LOOP pass=1,10 ; perform 10 passes
...
ENDLOOP
LOOP xyz=abc*def,ghi+jkl,mno/pqr
LOOP abc=xyz,xyz+2,2 ; nested LOOP
...
ENDLOOP
ENDLOOP
LOOP jj=10,3,-2.5 ; 10, 7.5, 5.0
...
ENDLOOP
Highway Program > Control statements > PARAMETERS

PARAMETERS
Sets general parameters.
Keywords and sub-keywords include:

• AAD • MA XIT E R S

• A LLOW LA MB D A 0 • MA XMW

• A LLOW A LLU T U R N S • MA XS T R IN G

• A LLOW U T U R N S • MA XV A R S

• CA P FA C • MOD E LP E R IOD

• COMB IN E • P D IFF
m BiFWVERSION • P D IFFV A LU E
m ENHANCE • RAAD
m FRACTIONS • R E LA T IV E GA P
m LAMBDASEARCH • R MS E

m LINKRANDSERIES • T CCOE FF

m STOCHASTICSEED • T CE XP

m • T U R N COS T FA C
VARIABLEDEMAND /
ALLJ • T U R N GA P W T
m WEIGHTS • U S E _V _ON LY
• CON S OLID A T E • ZON E MS G
• D IS T R IB _E S T M • ZON E S
• D P _COMB IN E P A T H • T R A CE S U MMA R Y
• D P _KE E P P A T H FILE

• E QU IT U R N COS T FA C

• GA P

• MA T OA D J U S T

P A R A ME T E R S k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

AAD |KR| Specifies the cutoff point based

upon the average absolute
difference in volumes
betwCOMBINEeen two
iterations.
Default value is 0.5. 1
A LLOW LA MB D A 0 |K?| Allow LAMBDA values to go to
zero. Default is True. If this
option is set to true or left as
default, then highway
assignment iterations will stop
once LAMBDA reaches zero,
since no additional
convergence can be achieved,
once LAMBDA is zero.
AllowLambda0 does not apply
when
LAMBDASEARCH=EQUATION.

A LLOW A LLU T U R N S |?| Option to allow U-turn at all

nodes and assumes U-turn
uses a shared-lane with left turn
lane if this movement is not
banned or prohibited in junction
file and/or turn penalty file. If
there are extra specification in
junction file, then the local setting
overwrites the global setting.
EXAMPLE A:

A LLOW U T U R N S |?| Option to allow U-turn at all

nodes if this movement is
allowed in junction file. Global U-
Turn control settings and
interaction with Junction file level
controls and EXAMPLE B:

CAPFAC |KR| Specifies a value to convert

input capacity to the same unit
as V. It is not used if C is
specified in the LINKREAD
phase. When C is not specified
in the LINKREAD stack and is
obtained directly from the input
network, C = CAPFAC * input
capacity. (See “LINKREAD
phase” on page 171 for details
on how Cube Voyager obtains
capacity from input network.)
Default value is 1.

COMBINE |KS| Specifies the method to

combine the results of iteration
volumes. Default value is EQUI.
Possible values include:
EQUI
Equilibrium assignment.
Iteration volumes are
factored by the
equilibrium weights
computed for each
iteration.
For important details on
usage, please see
“EQUI” on page 186.
AVE
Average all the iteration
loadings. See “AVE” on
 page 187.
WTD
Weighted Average
assignment. Similar to
AVE above, but the user
can specify a specific
weight for each iteration.
See “WTD” on
page 187.
ITE
Iterative assignment
keeps only last iteration
volumes as output. See
“ITE” on page 187.
SUM
Sum assignment is one
in which the final
volumes are the result
of adding the volumes
from each iteration. This
is traditionally known as
incremental loading.
For more information,
see “SUM” on
page 187.
PATH

HIGHWAY includes
support for path based
assignment using a
gradient projection
algorithm.
For details on usage,
see “PATH” on
page 188.
PROBIT

Supports stochastic
assignment.
For important usage
information, see
“PROBIT and
BURRELL” on
page 188.
BURRELL
Supports stochastic
assignment.
For important usage
information, see
“PROBIT and
BURRELL” on
page 188.

COMB IN E B iFW V E R S ION |I| Subkeyword used with

COMBINE=EQUI ENHANCE=2.
This keyword enables compatibility
of the Bi-conjugate Frank-Wolfe
algorithm with Cube Voyager 6.0.2.
Set BiFWVERSION=602 to
enable the compatibility. Default
 value is 0.

COMBINE E N H A N CE |I| HIGHWAY supports additional

assignment algorithms for the
COMBINE=EQUI mode. To
access these, include this
keyword immediately after the
COMBINE=EQUI statement. The
values for this keyword are:
m 0 — Normal Frank-
Wolfe algorithm
(default)
m 1 — Conjugate Frank-
Wolfe algorithm
m 2 — Bi-conjugate
Frank-Wolfe algorithm
When ENHANCE=2 you may
enable backwards-compatibility
of Bi-conjugate Frank-Wolfe
from Cube Voyager 6.0.2 using
the BiFWVERSION
subkeyword; see
“BiFWVERSION” on page 258.

COMB IN E FRACTIONS |RV*| Specifies the fractions to be

when COMBINE is set to SUM.
The number of fractions sets the
value for MAXITERS. The sum of
all the values should be 1.00; if
the sum is not 1.00, a warning
message will be issued. That
will not preclude the program
from executing. During the
ADJUST phase for each
iteration, V will be factored
according to the FRACTIONS for
that iteration, and added to the V
accumulated for the prior
iterations.

COMB IN E LAMBDASEARCH |S| Specifies alternate methods for

computing Lambda in EQUI
processing.
You can select one of two
Lambda search processes:
AREA
Indicates to
minimize the area
under all the V vs.
Cost curves
computed for
incremental
estimates of
lambda for every
link. Appropriate
when using a
generalized cost
function as depicted
in Example 8:
Multiple User Class
Assignment with
Cost based on User
 Class.
EQUATION
Estimates lambda
by solving an
expression based
on the TC functions.
Available only with
single user class
assignment, and
when using the
default
FU N CT ION
COS T =TIME.
Default value is AREA.
NOTE: Both processes estimate
Lambda so the results might be
slightly different. See the
description of these two
processes in “ADJUST phase”
on page 180.

COMB IN E LINKRANDSERIES |?| Switch to decide whether the

random number generator will
bind to the network or not. Only
valid for COMBINE=BURRELL
or PROBIT.

COMB IN E STOCHASTICSEED |I| Random seed to use for the

stochastic process. If not set it
will not set the seed number and
will continue to use the current
random series. If set to zero it
will reset the seed with the
current time to create a “random”
starting point. Only valid for
COMBINE=BURRELL or
PROBIT.

COMB IN E V A R IA B LE D E MA N D |?| The keywords

VARIABLEDEMAND and ALLJ
can be included immediately
A LLJ
after the COMBINE=PATH
statement, which gives
additional flexibilities to handle
complex scenarios. The values
of the two keywords are T/F,
and both of them default to false.
If VARIABLEDEMAND is true,
demands are allowed to
change between iterations.
ALLJ only applies when
VARIABLEDEMAND=T. If ALLJ
is true, all destinations (J) are
processed even if the demand
is zero.

COMB IN E WEIGHTS |RV*| Specifies the weights to be used

when COMBINE is set to WTD.
The number of weights sets the
value for MAXITERS.

CONSOLIDATE |I| Specifies minimum string length

for link consolidation, if
 CONSOLIDATE=T is specified
on the PATHLOAD statement.
Default value is 2.
If the default is used (2), then
links of two or more strings will
be consolidated. If
CONSOLIDATE is set to 3 then
links of three or more strings will
be consolidated, and so on.

D IS T R IB _E S T M |?| Option to distribute the ESTM

processing.

D P _COMB IN E P A T H |?| Option to combine the individual

path files from each cluster
node. Default value is true.

D P _KE E P P A T H FILE |?| Option to keep the individual

path file from each cluster node.
Individual Cluster node path files
are valid path files but only
contain paths from the zonal
range processed by that Cluster
node. If DP_COMBINEPATH is
true and DP_KEEPPATHFILE is
true, the path files will be
combined but the individual
Cluster node path files will be
kept as well. If
DP_COMBINEPATH is false,
then DP_KEEPPATHFILE will
not apply, since the individual
Cluster node path files will be
kept regardless.

EQUITURNCOSTFAC |KR| Factor used to convert turn

delays from minutes to cost for
estimating Lambda in the
equilibrium process. Default
value is 0.
If the default value (0) is used,
turning volumes and delays
from JUNCTIONI processing are
not included in the estimation.
This value is used only if: there
are turning volumes and
COMBINE is set to EQUI. When
use, this value typically
specifies the same value as
TURNCOSTFAC.

GAP |KR| Specifies the cutoff point based

upon the relative difference in
system cost (volume * cost)
between two iterations. Default
value is 0.005. 1

MATOADJUST |KI| Specifies how often MATO

matrices are combined during
assignment (see COMBINE).
Enter the number of iterations to
combine at once, using the
same factors used to combine
volumes. Default value is 1 — the
 matrices are combined each
iteration.
A lower number requires less
disk space but more processing
time. A higher number results in
faster processing, but requires
more disk space to store
intermediate matrices. With a
high number and numerous
iterations, you could exhaust
disk space.
Citilabs recommends leaving
this value at 1 (matrices will be
combined after each iteration). If
you wish to improve run times
and disk space is not a concern,
you may use a larger value
such as 5.

MAXITERS |KI| Specifies maximum number of

assignment iterations to be
performed. Default value is 20 if
COMBINE=EQUI; otherwise, the
default value is 1. The highest
allowed value is 1000 iterations.
1

MAXMW |KI| Optional. Maximum index for

work matrices (MWs). Valid
values range from 1 to 999.
Default value is 999. Normally,
you do not specify this keyword
and override default value.

MAXSTRING |KI| Specifies the maximum length

for a string variable. Default is
100. If you expect to compute
longer strings, you must define a
larger number. All string
variables will have this possible
length.
The maximum is 1000
characters.

MA XV A R S |KI| MAXVARS configures the size of

an internal buffer in Highway
which holds user-defined
variables.
Citilabs recommends leaving
MAXVARS unset unless a print
file message (698) suggests it
be increased. Default is 1000.

MODELPERIOD |KR| Duration of the model period in

minutes. The input demand
matrix should be in units of
vehicles (or PCU) per model
period. If no value is specified, a
default of sixty minutes (one
hour) will be used.
NOTE: This value is only used
when junctions are being
modelled, or during an
 AVENUE run. MODELPERIOD,
when specified, takes
precedence over the value of
FILEI JUNCTIONI PERIOD.

PDIFF |KR| Specifies the cutoff point based

upon the fractional portion of
links that have a change in
volume (between two iterations)
less than the value of
PDIFFVALUE. Default value is
1.00. 1

PDIFFVALUE |KR| Specifies the value to be used

with PDIFF. Default value is 0.0.
The default value of 0.0 will
result in null PDIFF outputs since
no links will satisfy the condition.
1
[ABS(V1-V2) / (V1)] <
PDIFFVALUE
Where V1 and V2 are the link
flows of consecutive iterations.

RAAD |KR| Specifies the cutoff point based

upon the relative average
absolute difference in volumes
between two iterations. Default
value is 0.005. 1

RELATIVEGAP |KR| Specifies an alternative GAP

measure as the cutoff point.
Default value is 0.005. 1

RMSE |KR| Specifies the cutoff point based

upon the root mean squared
error of the differences in
volumes between two iterations.
Default value is 0.1. 1

TCCOEFF |RV*| Represents the coefficient term

in a LINKCLASS- specific TC
function relating congested
volumes from the assignment to
congested travel times on the
links. Default value is 0.15.
TC functions are the labels in the
software given to volume delay
functions (commonly referred to
as VDFs). TC stands for
Congested Time or TC. The
LINKREAD Phase of this
program allows the user to
associate every link in the
network with an internal
LINKCLASS variable. The TC
functions can be indexed by
LINKCLASS to specify different
volume delay relationships for
different classes of facility. If no
LINKCLASS is defined for a link
it defaults to LINKCLASS=1. If no
 TC functions are defined then a
default TC function is applied.
The default TC function is the
standard BPR with the form:
TC[1] = T0 *(1 + TCCOEFF *
(V/C) ^ TCEXP)
The default values for TCCOEF
and TCEXP result in the
Standard BPR formula. If you
code LINKCLASS values but do
not code alternative TC
functions by LINKCLASS, the
default BPR form will be used
but the LINKCLASS-specific
values of TCCOEFF and
TCEXP (if coded) will be
substituted into the formula for
the LINKCLASS. For example, if
four LINKCLASSes are defined
in the LINKREAD phase, and no
TC functions are specified then
TC[1] as specified above is in
effect for all links. If the user
codes:
PARAMETERS
TCCOEFF[1]=0.15,
TCEXP[1]=4,
TCCOEFF[2]=0.16,
TCEXP[1]=4.5,
TCCOEFF[3]=0.17,
TCEXP[1]=6,
TCCOEFF[4]=0.18,
TCEXP[1]=8,
Then these LINKCLASS-specific
values of TCCOEFF and
TCEXP are substituted into
TC[1] for the appropriate
LINKCLASS of a given link. This
allows you to have one common
functional form but apply
different coefficient and
exponent values by
LINKCLASS. You can also code
your own functional form if the
BPR form is not what is desired.
In general, TC[#]=f(T0, V/C,
TCCOEFF, TCEXP) but the user
is free to experiment with any
forms that make sense to them
for their application.

TCEXP |RV*| Represents the exponential

term in a LINKCLASS-specific
TC function relating congested
volumes from the assignment to
congested travel times on the
links. See the discussion for
TCCOEFF above for usage.
Default value is 4.0.

TURNCOSTFAC |KR| Factor to convert turn times to

equivalent costs for use in
summary statistics and GAP
calculations. If the value is 0, the
 summary report will not include
turn volume costs. Default value
is 1.

TURNGAPWT |R| Constant that indicates how

much weight each turn
movement should have when
turn cost is used in GAP
calculations. Default value is 1.
A value of 1 indicates that each
movement is to be considered
with the same weight as a link. A
value of 2 indicates that the turn
cost should be multiplied by 2
(each turn movement is to be
considered equal to 2 links
during testing).

U S E _V _ON LY |K?| Option to stop computing all the

individual volume sets, when in
the adjust phase, to speed up
the run when individual volume
sets are NOT used in the TC
and COST functions. Default is
false, so each volume set
volumes are processed to
make the individual set
combined volume (V1, V2 etc.)
available to the TC and Cost
functions. These are generally
not needed except for some
generalized cost model that use
the individual volumes instead
of the total volume. If a large
number of volume sets are
used, it adds considerable
amount of run time to the adjust
phase. This option can be used
to reduce this run time. It does
not verify that the individual
volumes are not used in the
functions (TC and COST). If the
individual volume sets are used
and the option to skip individual
volume computation is on
(USE_V_ONLY = T), then the
value for V1, V2 etc. may-be all
zero or some random number.
Only use this option if a large
number of volume sets are used
in highway assignment and
check to make sure that
individual volume sets are not
used in TC and COST functions.

ZONEMSG |KI| Optional. Frequency with which

the program writes zonal timing
messages to the run monitor or
console.
Value corresponds to number of
zones. For example, with a
value of 1, the program writes a
message for every zone. With a
value of 10, the program writes a
 message for every 10 zones.
With a value of 0, the program
writes no zonal messages.
Specify a larger value to reduce
run times.
Program writes to the run
monitor when initiated through
Application Manager or
voyager.exe. The program
writes to the console when
initiated through runtpp.exe.
Valid values are greater than or
equal to zero. Default value is 1.

ZONES |KI| Establishes the number of

zones to process. Default value
is taken from NETI.
If ZONES is not specified, and
the program has no other way to
identify the appropriate number
of zones, it will be set to 100.
Normally, the NETI or MATI
matrices will establish the
number of zones, but there could
be cases where the user wishes
to use a different value.

TRACESUMMARY |K?| Controls the printed path

information from the TRACE
PRINTO keyword in
PATHLOAD statement. By
default, TRACESUMMARY is
set to FALSE, in which case the
whole path information will be
printed to the PRINTO file. If
TRACESUMMARY is set to
TRUE, only the last link in the IJ
path is printed to the PRINTO
file along with any other path
variables (e.g. _PathCost) listed
by the user in the PRINT LIST
statement.

1 These keywords are used to control when to not do any more assignment iterations. In the USA, GAP is a
commonly used criteria. Thus, if GAP=0.01, this implies that when the system costs do not change by
more than one percent, the process is to terminate. The first of these criteria that is satisfied controls the
process. It is suggested that MAXITERS always be used to preclude endless processing. Some networks
may never converge, and oscillations may start. Using MAXITERS can prevent useless processing. If
MAXITERS ends up being the controlling value, the results printed at the end of the program should be
examined to determine if oscillation has occurred, or if more iterations are really needed.
Highway Program > Control statements > PARAMETERS > Example

Exam ple
ZONES=3000
COMBINE=WTD, WEIGHTS=1,1,2,3*3,5; 7 iterations
COMBINE=EQUI, MAXITERS=30
PARAMETERS COMBINE=SUM, FRACTIONS=.30,.20,5*.10
; 7 Iterations - Incremental
; SAMPLE INCREMENTAL ASSIGNMENT WITH “PROJECTED” RESTRAINT
PARAMETERS COMBINE=SUM, FRACTIONS=.5,.2,.2,.1
ARRAY CSCALE=4
CSCALE[1]=.5, CSCALE[2]=.7, CSCALE[3]=.9, CSCALE[4]=1
PHASE=LINKREAD
C = LI.CAPACITY * CSCALE[ITERATION]
Highway Program > Control statements > PARAMETERS > TRACESUMMARY Example

TRACESUM M ARY Exam ple

RUN PGM=HIGHWAY
FILEO PRINTO[1] = "myPath.dat"
FILEI NETI = "C:\Cubetown\Model\HIGHWAY_0001.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\PKHOURTRIPS.MAT"
PARAMETERS TRACESUMMARY = T
PROCESS PHASE=LINKREAD
C = LI.CAP
ENDPROCESS
PROCESS PHASE=ILOOP
PATHLOAD PATH=TIME TRACE=(I=1 & J=2) PRINTO=1 LIST= I, J A, B, _PATHCOST
ENDPROCESS
ENDRUN

Output with TRACESUMMARY = F (default)

Output with TRACESUMMARY = T

Highway Program > Control statements > PARAMETERS > Global U-Turn control settings and interaction with Junction file
level controls

Glo bal U-Turn co ntro l settings and interactio n with Junctio n file level co ntro ls

J unc tio n D a ta U -T urn

P a ra me te rs Co ntro l R e s ult

AllowAllUturns AllowUTurns Allow Ban U-Turns

FALSE FALSE Any Any Not Allowed

FALSE TRUE Unchecked Unchecked Not Allowed

FALSE TRUE Checked Unchecked Allowed

FALSE TRUE Unchecked Checked Not Allowed

TRUE Any Unchecked Unchecked Allowed

TRUE Any Checked UnChecked Allowed

TRUE Any Unchecked Checked Not Allowed

Highway Program > Control statements > PARAMETERS > Global U-turn control settings and interaction with Turn Penalty
file level controls

Glo bal U-turn co ntro l settings and interactio n with Turn Penalty file level co ntro ls

P e na lty File U -T urn

P a ra me te rs P e na lty V a lue R e s ult

AllowAllUturns AllowUTurns -1 0 >0

FALSE FALSE Not Allowed Not Allowed Not Allowed

FALSE TRUE Not Allowed Not Allowed Allowed

TRUE Any Not Allowed Allowed Allowed

Highway Program > Control statements > PARAMETERS > EXAMPLE A:

EXAM PLE A:
RUN PGM=HIGHWAY
FILEI TURNPENI = "myTurnPen.pen"
FILEO JUNCTIONO = "myJunOut.INT"
FILEO NETO = "myLoaded.NET"
FILEI JUNCTIONI = "myJunctions.ind",
period=60,set=1
FILEI NETI = "myBase.net"

PARAMETERS COMBINE = AVE

PARAMETERS RELATIVEGAP=0.0001 GAP = 0.0, MAXITERS=10
PARAMETERS AllowAllUTurns=T ;model U-turns movements at all nodes unless it is
banned in the Junction file

ZONESMSG=1
TURNS N=1-99999

PROCESS PHASE=LINKREAD
C = LI.CAP
ENDPROCESS

PROCESS PHASE=ILOOP
MW[1]=500
PATHLOAD PATH = TIME, VOL[1]=MW[1], PENI=1,2
ENDPROCESS

PROCESS PHASE=ADJUST

FUNCTION {
V=VOL[1]
TC = T0 *(1+0.18*(V/C)^8.5)
}
ENDPROCESS

ENDRUN
Highway Program > Control statements > PARAMETERS > EXAMPLE B:

EXAM PLE B:
RUN PGM=HIGHWAY
FILEI TURNPENI = "myTurnPen.pen"
FILEO JUNCTIONO = "myJunOut.INT"
FILEO NETO = "myLoaded.NET"
FILEI JUNCTIONI = "myJunctions.ind",
period=60,set=1
FILEI NETI = "myBase.net"

PARAMETERS COMBINE = AVE

PARAMETERS RELATIVEGAP=0.0001 GAP = 0.0, MAXITERS=10
PARAMETERS AllowUTurns=T ;only model U-turns movements where they are set to ALLOW
in the Junction file

ZONESMSG=1
TURNS N=1-99999

PROCESS PHASE=LINKREAD
C = LI.CAP
ENDPROCESS

PROCESS PHASE=ILOOP
MW[1]=500
PATHLOAD PATH = TIME, VOL[1]=MW[1], PENI=1,2
ENDPROCESS

PROCESS PHASE=ADJUST

FUNCTION {
V=VOL[1]
TC = T0 *(1+0.18*(V/C)^8.5)
}
ENDPROCESS

ENDRUN
Highway Program > Control statements > PATHLOAD

PATHLOAD
Builds a path, generates related matrices, and loads path links.
Keywords and subkeywords include:

• CON S OLID A T E • PENI

• E S T MO • P E N IFA CT OR
m ALLJ • SPREADPERC

• E XCLU D E GR OU P • S P R E A D P E R CV A R

• E XCLU D E J • S P R E A D MA X

• FR OMN OD E • S U B A R E A MA T

• IN CLU D E J m MAXMSG

• LIN KID A R R A Y • T OLLFA CT OR

m LINKIDCNTMW • T OLLMA T I
m m TOLLPATHSET
LINKIDLASTUSE
m LINKIDMW • T H R U N OD E
m LINKID#MW • T R A CE

• MA XP A T H COS T • T REEO
m NAME
• MW [ ]
m NOACCESS • V OL[ ]
m m Valuename
SELECTGROUP
m
SELECTLINK
m SELECTLINKGROUP
m SELECTTOLL

• PAT H
m DEC

• PAT HO
m ALLJ
m FULLPATH
m INCLUDECOST
m NAME
m PATHOGROUP

Use a PATHLOAD statement build a path, and then complete other processes based on
that path. Selected I-J path traces can be written to the standard output print file,
matrices can be generated based upon path criteria, link volumes can be obtained by
routing matrix values along the path. Although any of the keywords on the statement can
be in any order, the statement is processed in the following specific order:
1. PATH — Built using any EXCLUDEGROUP and PENI values specified
2. TRACE

3. LINKIDARRAY

4. MW — Processed in the input order

5. VOL — Loaded in input order

P A T H LOA D k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

CONSOLIDATE |?| Flag that specifies whether to consolidate

links that are part of the same road
segments prior to path building. Default
value is F, no link consolidation.
Consolidating the links reduces the size of
the link table and the thus reduces
pathbuilding time. Depending on the level
of inefficiency in the input network,
reductions in runtime could be significant.
Also see PARAMETERS keyword
CONSOLIDATE on page 260 for
information on controlling the effective level
of consolidation.

ESTMO |I| Integer specifiying which output ICP file,

specified by FILEO ESTMICPO, will trap the
assigned volumes on screenline links.

ESTMO ALLJ |?| Flag that indicates if ESTMO processing is

used for all I-J paths, or for only the I-J paths
where an actual assignment is performed.
Default value is FALSE.
If the value is TRUE, all potential paths are
considered, mostly likely resulting in longer
processing times and larger output files.

EXCLUDEGROUP |IP| Specifies that links that have any of the

designated group codes will be excluded
from the path building process.
For example, if HOV links were assigned to
group 4, and 4 were one of the excluded
values, then none of the paths would
contain HOV links.

EXCLUDEJ |IVP| Specifies that the processes for the named

keywords will exclude the specified
destination zones.

FR OMN OD E |RS| Format and report paths from a single

origin to a range of destinations, regardless
of the current I value. Origin and destination
can be any zone or node number but the
main purpose of this keyword is to report
 node to node paths. Zone to zone paths
can be reported using just the TRACE
keyword without using FROMNODE. Once
the FROMNODE keyword is used, none of
the other assignment and path related
action keywords such as VOL, MW,
TREEO, PATHO, ESTMO etc. will be
processed. FROMNODE specifies the
origin zone or node number. Users can
specify FROMNODE as a constant numeric
value, or a variable (e.g. FNODE). To
specify the destinations of the paths, use
the TONODE variable that represent the
destination zone/node number in the
TRACE expression. For example, TRACE=
(TONODE=1-10, 90000-90005 ||
TONODE=TND). TONODE can be
compared to a numeric value, a range (e.g.
1-10) or a variable (e.g. TND). The
selected path statistics will be listed in the
run print file. Or alternatively, users can use
PRINT statement to write path statistics to
an external PRINTO file. When using the
LIST keyword to output path trace, do not
use the variables I and J (when using the
FROMNODE keyword), use the variables
FROMNODE and TONODE instead.
See “FROMNODE example 1” on
page 290.
Note: An "IF (I=1)" block is suggested when
using the FROMNODE keyword in the
ILOOP phase to avoid printing the paths
multiple times, one for each I zone.

INCLUDEJ |IVP| Specifies that the process for the named

keywords will include only the specified
destination zones

NOTE: INCLUDEJ and EXCLUDEJ should really be mutually exclusive, but they can be
combined. When both are used, The INCLUDEJ is processed first, and than the EXCLUDEJ
follows. Thus, if INCLUDEJ=100-200 and EXCLUDEJ=140-150, zones 100-139 and 151-200 would
be the only destination zones processed.

LINKIDARRAY |S| Specifies an array of link attributes; it must

be either an LI.array or an LW.array.

LINKIDARRAY LINKIDCNTMW |I| Specifies the MW[] in which to store the

number of links in the list.

LINKIDARRAY LINKIDLASTUSE |I| Specifies the MW[] in which to store the

information for the last link in the list.

LINKIDARRAY LINKIDMW |IP| List of MW numbers where the monotonic

succession of link crossing information
(beginning at 1) is to be stored.
For example, LINKIDMW=10-13,6,8
means that the first link’s information will be
stored in MW[10]; the second link’s
information will be stored in MW[11]; the fifth
link’s information will be stored in MW[6],
and so on.

LINKIDARRAY LINKID#MW |IP| List of MW numbers where the monotonic

succession of numbers of the links
 (beginning at 1) is to be stored.
For example, LINKID#MW=10-13,6,8
means that the number of the first link will be
stored in MW[10]; the second link will be
stored in MW[11]; the fifth link will be stored
in MW[6]. Link arrays can then be
addressed directly by using these values.
For example, ANODE = A[MW[1]] xxx
= LW.xyz[MW[2]].

MA XP A T H COS T |RS| Restricts the path builder to build path only

to zones/nodes that are less and equal to
the value specified by MAXPATHCOST.
MAXPATHCOST can only be specified
once per PATHLOAD statement. It can be
either a numeric constant or an expression.
The default value is 0, which means no
restrictions.
Note: MAXPATHCOST applies to both path
skimming and traffic assignment. When it is
used with assignment, trips going to zones
beyond the MAXPATHCOST will not be
assigned. Therefore, it needs to be used
with care
Example.
IF (I=1) PATHLOAD PATH=TIME,
VOL[1]=MI.1.1,
MAXPATHCOST=I*10+10
PATHLOAD PATH=COST,
VOL[1]=MI.1.1, MAXPATHCOST=50

MW[] |N| Generates a matrix row, almost in the same

manner as a regular COMP MW[]=
statement. The primary difference is that
this expression has access to the values
from the I-J paths that result from the PATH
keyword. Two-level indexing is not allowed
here; the computation implies a J=1,Zones
loop. If there are INCLUDEJ and/or
EXCLUDEJ values on the statement, only
those corresponding columns in the MW
will be processed; the excluded cells will
not be altered. There may be multiple MWs
specified on the statement; they will be
processed in the order they appear on the
statement.
Typical types of matrices computed
include:
• Path-based matrix — A matrix with I-J
path values, such as distance, cost,
time, etc. This is often referred to as a
LOS (level-of-service) matrix. Many
traditionalists refer to such matrices
as “skim” values, because the values
are “skimmed” from the network. To
obtain zone-zone values, the
PATHTRACE(name) function is used.
For example, to obtain zone-to-zone
times, MW[1] =
PATHTRACE(TIME). When the
PATHTRACE for the intrazonal value
(J=I) cell or a cell with no access is
 obtained, the value will be a big
number, because there is no path
between the zones.
(continued)

MW[] In some cases, a big number is

(continued) acceptable, and in other cases, it is not.
To solve this dilemma, you can use the
subkeyword NOACCESS to specify a
value to be returned from the
PATHTRACE function when there is no
path.
The keyword PATHCOST may be used
to obtain the value directly from the
path tables. This is different than
PATHTRACE, because PATHTRACE
actually traces the path and sums the
value from the network links that are in
the path. PATHCOST is much faster,
because it obtains the values without
tracing paths; it also contains any
penalty values that were included in
building the paths. To provide similar
capabilities with PATHTRACE, the
argument list to PATHTRACE may
include the penalty set numbers that
should be added to the values for the
first argument to PATHTRACE. Penalty
set numbers should be listed
individually and cannot be given as a
range.
Warning: The program determines
when the last iteration has been
performed, and no paths or matrices
are built from the final network link
values. Following the last iteration,
MATOs written during normal iteration
processing are combined according to
the COMBINE option on the MATO
statement. Thus, if “skims” had been
written in each iteration, and
COMBINE=T, the final skim MATO will
be the weighted values from all the
iterations. This is normally done for trip
matrices, but it may be useful for
specific travel cost matrices. If
COMBINE=F, the MATO will contain the
values obtained during the last iteration
-- not after the iteration. To obtain the
“true” equilibrium zonal travel time
and/or distance, one should run
another Highway step using the loaded
network as input and skim the shortest
path time/distance.
(continued)

MW[] (continued) Example of PATHTRACE

PATH=TIME,
MW[1]=PATHTRACE(TIME),
; zone-to-zones times
MW[2]=PATHTRACE(LI.DISTSNCE),
; zone-to-zone
 distances
MW[3]=PATHTRACE(TIME,2),
; same as MW[1],
penalties added
MW[4]=PATHCOST
; same as MW[3]
• Select-link matrix — A matrix of values
for the zones that meet select link
criteria. There are several different
subkeywords that can be used to
specify the select-link criteria:
SELECTLINK, SELECTGROUP, and
SELECTLINKGROUP. Their detailed
descriptions are below. All the
SELECT... keywords are combined for
the MW that they directly follow. Each
results in a true or false condition, and
if any of them is true, the MW=
expression is computed. In the
following example, if any of the
SELECT criteria is satisfied for a given
J, MW[3] for that J will be computed to
be the value from MI.1.TRIPS.
Example of Select Link
PATH=COST,
MW[3]=MI.1.TRIPS,
SELECTLINK=(L=1000-1001 &&
L=2000-2001),
SELECTGROUP=1-3,5,
SELECTLINKGROUP=((GRP[1]=1 &&
GRP[2]=2) || (GRP[3]=1))

MW[] NOACCESS |R| Specifies a number to be returned from the

PATHTRACE function when there is no
path from the current I to the destination (J)
zone. Default value is 1,000,000.

MW[] SELECTGROUP |IPa| Specifies the group codes for selection. A

path has to include at least one link that has
any of the specified group codes. If the
selection is 1-3, 7, then at least one link in
the path has to have a group code of either
1, 2, 3, or 7.

MW[] SELECTLINK |s| Expression used to determine if the I-J path

uses certain facilities. The expression must
be enclosed within parenthesis, and can
contain any of the following variables:
A
The A-node of a link; only useful to
select links with a path begins at A.
B
The B-node of a link; only useful to
select links with a path ends at B.
N
A node that must be used in the path.
L
A link that must be used in the path.
Links are coded as A-B (directional) or
A-B* (non-directional – link may be
 traversed in either direction).
Any of these variables can have multiple
values specified for them. Nodes (A, B, N)
can be specified as single values and/or
as ranges; L can have multiple links
specified. When the multiple value
specification is used, the implication is a
logical OR amongst the values. Example:
N=100,105,200-205 means if N is 100, or if N
is 105, or if N is a value between 200 and
205, inclusive. There is no limitation on the
number of nodes.
The selection is processed by examining
each link/node in the path, on both an
individual link and a total path basis. The
process is from left to right. Each link/node
is processed, and as long as it does not fail
any conditions, it is considered as a
candidate for processing in the total path. In
the total path basis, the link/node is
considered in conjunction with other
links/nodes in the path. Examples may
better illustrate the process.
(continued)

MW[] SELECTLINK Sample path: 1-101-102-103-104-105-2

(continued) (A=1) Node 1 is on the path in any link
except the last: true
(A=1 && B=102) Node 1 is on the path in
any link except the last, and node 102 is on
the path in any link but the first: true
(L=101-102,104-200) Link 101-102, or Link
104-200 is on the path: true
(L=102-101*) The path contains link 101-102
or link 102-101: true
(L=101-102* && L=104-105*) The path
contains link (101-102 or 102-101) and link
(104-105 or 105-104): true
(N=101 && N=105-110 && L=101-102*) The
path contains node 101 and any node in the
range of 105-110, and link (101-102 or 102-
101): true
((N=100-105) && (N=8,57 || L=105-104)) The
path crosses any node 100-105, and (it
crosses node (8 or 57) or link 105-104):
false. If L=104-105* instead of L=104-105,
the expression would be true.
Citilabs recommends using nested
parentheses to help categorize the
comparison sets. With this type of Boolean
selection, most any desired combination of
path usage can be specified.
Finally, when using SELECTLINK and the
TURNS control statement in the same
HIGHWAY program, care must be taken. Please
see “TURNS” on page 301 for more information.

MW[] SELECTLINKGROUP |s| Expression used to determine if the I-J path

meets select link criteria based upon some
level of link group codes. The expression
should contain mostly GRP[] values and
 perhaps I and J; nothing else is really
appropriate. The tracing mechanism
accumulates how many links of each group
code are used in the path. Those totals are
available to the expression. The following
example says “if the path uses at least
three links with group code 1 and at least
one link with group 2 or if the path uses at
least five links with group 7 or if the path
uses exactly two group 6 links” the path
meets SELECTLINKGROUP criteria.
Example
SELECTLINKGROUP=((grp[1]>3 &&
grp[2]>=1)|| grp[7]>=5 ||
grp[6]=2)

MW [ ] S E LE CT T OLL |s| Expression used to determine if the I-J path

uses certain toll facilities. The expression
must be enclosed within parenthesis, and
can contain any of the following variables:
T - The toll trip entry-exit pair specified
using toll gate numbers. E.g. T=1-4 means
any trips using entry gate 1 and exit gate 4.
G - A toll gate (entry or exit) that must be
used in the path.
E - An entry gate that must be used in the
path.
X - An exit gate that must be used in the
path.
Any of these variables can have multiple
values specified for them. Gates (G, E, X)
can be specified as single values and/or
as ranges; T can have multiple entry-exit
pairs specified. When the multiple value
specification is used, the implication is a
logical OR amongst the values. Example:
G=100,105,200-205 means if G is 100, or if G
is 105, or if G is a value between 200 and
205, inclusive. Example 11: Using
TOLLMATI and TOLLVOLO.

Example:

PATH |KS| Specifies the link value on which the paths

are to be built.
Valid values are: Cost, Time, Dist, LI.name,
or LW.name.

PATH DEC |S| Specifies the accuracy of the link value on

which the paths are to be built. Default
value is F.
Valid values for DEC are: 0, 1, 2, 3, 4, and F,
which represent 0, 1, 2, 3, 4 decimal places
and floating point, respectively. Using lower
accuracy will speed up the assignment
process considerably, especially for larger
networks.

PATHO |I| Number (#) to specify that a path file is to be

written to FILEO PATHO[#]. The file will
 contain I-J paths generated by this
PATHLOAD statement. The number of I-J
paths will be determined by the value of the
PATHLOAD PATHO ALLJ keyword. If
PATHO is not specified, the PATHO file will
not be written for this statement. The path
file can be used in Cube for analysis of
what happened during this assignment, or
for various post processing capabilities,
such as selected link analysis, or
recreation of parts of the assignment. The
generated file can be very large and writing
it can cause a considerable increase in
running time.

PATHO ALLJ |?| Switch that indicates if PATHO write

processing is to be invoked for all I-J paths,
or for only the I-J paths where an actual
assignment is performed. By default this
value is false, unless this application is
path building only (No FILEO
NETO=value and no PATHLOAD VOL=
value).

PATHO FULLPATH |?| T/F flag used with PATHOGROUP to keep

partial or full paths for the specified
GROUP(s).

PATHO INCLUDECOST |?| Switch to indicate if the path records are to

include the cost values (based upon the
PATH=array values). The cost through
every link in every path is written; this can
cause a considerable increase in the size
of the file.

PATHO NAME |S| Name to be applied to the paths written for

this statement. A PATHO file may have
multiple path sets written to it by different
PATHLOAD statements. However, the
same NAME path set may not be written to
a file more than one time for an I zone. If an
attempt to write the same NAME to a file for
the same I zone is made, only the first set
will be written, and there will be no
message indicating that this attempted
duplication occurred.

PATHO PATHOGROUP |IP| List of numbers (1-32). The numbers are

associated with GROUP ADDTOGROUP=
process in LINKREAD. The ADDTOGROUP
numbers are typically associated with
specific LI. or LW. values via a conditional
statement thus links are either associated
with the group or not. When the trace of a
path is examined, if the trace does not
contain any of the selected links in the
group(s) nothing is written to the PATHO file.
If the path does contain a specified link in
the group(s), and the FULLPATH
subkeyword is F, the trace will contain only
I, the nodes of the specified links in the
group(s), and J. If the path does contain a
specified link in the group(s), and the
FULLPATH subkeyword is T, the trace will
 contain I, all the nodes of any path that uses
any of the specified links in the group(s),
and J.
The use of PATHOGROUP= with
FULLPATH=T/F and setting appropriate
group(s) with ADDTOGROUP= allows the
user to limit the paths written to the PATHO
file by keeping only those paths and the
portions of the paths the user may be
interested in for further analysis and
display. This can considerable reduce the
size of the stored path file.

PENI |IP| Specifies the PENI set(s) that are to be

used in building this path. You can specify
any combination of valid PENI indices. A
set number must be 1-8; the valid numbers
on the TURNPENI file. If a JUNCTIONI file is
provided, then the SET keyword is required
to reserve one penalty set numbers for use
with the junction delays. The set number
used for the junction delays must be listed
on the PENI keyword value along with any
additional turn penalty set that may be
specified with TURNPENI in the same run.

PENIFACTOR |N| Expression that specifies a factor for all

penalties during path building. This is not
specifically related to JUNCTION; it applies
to all penalties (TURNPENI and SET=).

SPREADPERC |R| Stochastic Assignment – used with

COMBINE=PROBIT|BURRELL, and in
conjunction with SPREADPERCVAR and
SPREADPERCMAX.
SPREADPERC specifies the percent
spread used to calculate the spread range
value, it must be a numeric constant.
Default is 10(%).
A random link cost value (for PATH=x) will
be selected from the +/- spread range
value from the original link cost value (C) as
follows:
Min(SPREADPERC/100 * sqrt(C), C,
SPREADMAX)

S P R E A D P E R CV A R |S| Single variable or link array (must be LI. Or

LW.) which indicates the percent spread for
a link during stochastic assignment. If it is a
link array, then every link can have a
different spread percentage. If the value for
a link is negative, then the SPREADPERC
value will be used.

S P R E A D MA X |R| Specifies the maximum spread value

allowed for stochastic assignment
(COMBINE=PROBIT|BURRELL). Default is
unlimited.

SUBAREAMAT |N| Expression that the program computes for

every J and writes the resulting value onto
any subarea extracted records.
For example: SUBAREAMAT[1] = MW[3]
 specifies that for every J of the current I path
set, if the path from I-J has some portion
within the subarea, a value is to be inserted
to the subarea matrix.
There must be an index for the keyword.
The highest index sets the number of
matrices on the SUBAREAMAT file. See
“ILOOP phase” on page 175.

SUBAREAMAT MAXMSG |I2| Specifies how many messages to print

about improper cordon crossings and the
error level to assign to the messages.
Two values are allowed:
• The first value specifies how many
messages are printed for the
SUBAREAMAT.

• The second value specifies the error

level to assign to the message when
the number of messages reaches the
first value.
The printed messages will be assigned an
error level of 1 less than the second value
for all messages except the last one.
For example: MAXMSG=50,2 indicates that
the first 50 improper crossings are to be
printed at error level 1, but the program will
terminate with error level 2, at the 50th
message.

TOLLFACTOR |N| Expression that specifies a factor for

converting tolls to COST units. Generally
paths are built on TIME and TIME is in the
units of minutes. If a generalized COST
function is used for path building, all
components of this function are typically
appropriately factored to be in generalized
minutes.
Units must be (path cost units)/(toll cost
units). For example, if tolls are coded in
$US and path costs in minutes, then the
TOLLFACTOR expression must specify a
value in minutes/$US. An assumed traveler
value of time of US$15/Hour would be
implemented by setting TOLLFACTOR to 4
(60/VOT).

TOLLMATI |IP| Indicates that gate-to-gate tolls are to be

included in the COST used for path building
and specifies the FILEI TOLLMATI[#]= file
number and toll set on the file to be used.
Specifying TOLLMATI=1,2 indicates to
use toll set 2 on TOLLMATI file 1.
See “Path-based tolls” on page 162.

TOLLMATI T OLLP A T H S E T |I| This keyword, when specified, triggers the

saving of the toll trips for output to the
TOLLVOLO files at the end of the process. It
is also the identifier to the toll trips saved
from this PATHLOAD. The value can be
between 1 and 1000. Along with toll matrix
and toll set number specified in the
TOLLMATI keyword, the VOL sets
 specified in the PATHLOAD statement,
these four constitute the unique identifiers
for a specific group of toll trips (TOLLMATI,
TOLLSET, PATHSET and VOLSET). Toll
trips with the same 4 identifiers will be
summed together into a group. Example 11:
Using TOLLMATI and TOLLVOLO.

TOLLMATI Example:
In the above
simple PATHLOAD statements, there are
three unique set of toll trips
1. TOLLMATRIX=1, TOLLSET=1,
PATHSET=1, VOL=1
2. TOLLMATRIX=1, TOLLSET=1,
PATHSET=1, VOL=2
3. TOLLMATRIX=1, TOLLSET=2,
PATHSET=2, VOL=3

THRUNODE |I| Sets the minimum node number allowed to

be included in the path building process.
The value has to be a positive integer. The
default value is ZONES+1. The default
value excludes centroids as intermediate
points of a path.

TRACE |S| Specifies if any paths fromI/FROMNODE to

the selected destinations are to be
formatted and reported for this path. The
select expression must be enclosed within
parenthesis. Most likely, the variables used
in the expression would be I, J,
TONODEand Iteration, but any valid
variable can be used. The TRACE
expression is evaluated for J=1,Zones
when FROMNODE is not specified and
TONODE=1 to HighestNodeNumber when
FROMNODE is specified. If PARAMETER
TRACESUMMARY is set to true, only the
last link in the path is printed to the PRINTO
file along with any other path variables (e.g.
_PathCost) listed by the user in the PRINT
LIST statement.
Example:
PATHLOAD PATH=TIME TRACE=(I=1-10
& J=100-150)
PATHLOAD PATH=TIME
FROMNODE=10000 TRACE=
(TONODE=100-150)
PATHLOAD PATH=TIME FROMNODE=100
TRACE=(TONODE=11000-11500)
PATHLOAD PATH=TIME
FROMNODE=10000 TRACE=(TONODE=1-
100 || TONODE=11000-11500)
The selected path traces will be listed in
the run print file.
The TRACE keyword can use the PRINT
statement keywords as subkeywords to
format and direct the print of the path
trace(s) to an external PRINTO file. The
following additional subkeywords can be
 used:
PRINTO (REWIND PRINT) CSV CFORM
FORM LIST
See “PRINT” on page 293 for
details on these subkeywords.
The LIST subkeyword may be any valid
input (li.) or work (lw.) array or it can be set
to _pathcost to list the accumulated value of
the COST function along the path trace.
See “TRACE example” on page 289.

T REEO |I| Index of the output T R E E O file, to which the

path trees from the P A T H LOA D should be
output.
See more information on TREEO from
Example 10: Shortest Path Trees Using
TREEO.

TREEO N A ME |S| Name for this path set, which will be output
to the T R E E O file.

VOL[] |N| Specifies an expression to be solved for J,

and that the result of the expression is to be
assigned to the links in the path generated
by the PATH keyword. VOL should be
indexed [], but if it is not, the index is implied
to be 1. The index range is 1-1000; there
may be up to 1000 volume sets in a single
application of Highway. The values are
added to the volumes. In most cases, there
will be a single VOL for a PATHLOAD
statement, but there are many cases, where
it will be advantageous to have more than
one VOL. For example, if a standard
assignment is to be performed, and it is
desired to have another assignment made
of just the trips that meet select link criteria,
that is easily accomplished. Or, perhaps it
is desired to assign all vehicles, and to
determine what types of trips make up the
volumes on each link. The examples below
illustrate these capabilities. It should be
noted that when specifying multiple VOL
keywords, you must specify the FUNCTION
V so the program knows which VOL
combinations are to be used for capacity
analysis.

VOL[] V a lue na me |S| Specifies the name of a link value that

should be used in restricting the links that
should be included in the VOL assignment.
The primary use of this keyword is for air
quality analysis. An example would be to
obtain what portion of the volume on a link
is in cold start mode. In that case,
VOL[2]=MI.1.TRIPS, TIME=0-7.5
would mean to assign only to the links that
are within 7.5 minutes from the origin zone.
A single range of numbers is required for
this keyword. In the example, if a 3 minute
link’s A node were 6 minutes from I, only
50% of the trip value would be added to the
link volume (7.5 is 50% of the way from 6
 minutes to 9 minutes). Normally, the range
would be 0-some number, but if the range
were say, 7.5-99999, only the hot running
portion of the trip would be assigned.

T R A CE e xa mp le
RUN PGM=HIGHWAY
FILEO PRINTO[1] = PATH.CSV
FILEO PRINTO[2] = PATH_TRACE_RPT.DAT
FILEI NETI = TEST.NET

FromZone=150
ToZone=187
PHASE = LINKREAD
lw.fac_dist=10*li.DISTANCE
ENDPHASE

PROCESS PHASE=ILOOP
IF (I=FromZone) ; build paths for select I
PATHLOAD PATH=li.TIME mw[1]=PATHTRACE(li.TIME),
mw[2]=PATHTRACE(li.DISTANCE), TRACE=(I=FromZone
& J=ToZone) PRINTO=2 PRINT=T
F=6.0,LIST=I,J,A,B,li.TIME(8.3),_pathcost(8.3),
li.DISTANCE(8.4),lw.fac_dist(10.2)
EXIT
ENDIF
ENDPROCESS
ENDRUN

FR OMN OD E e xa mp le 1
RUN PGM=HIGHWAY
FILEI NETI = "Highway.NET"
FILEO PRINTO[1] = PATH_TIME_DISTANCE.PRN
FILEO PRINTO[2] = PATH_100500.PRN
FILEO PRINTO[3] = PATH_101000_TIME.PRN

LOOKUP NAME=FROM_TO,
LOOKUP[1]=1, RESULT=2, ; lookup from node
LOOKUP[2]=1, RESULT=3, ; lookup to node
R= '1 106500 76011',
'2 106722 83000',
'3 107100 92650',
'4 107122 100000',
'5 103500 101000'

PROCESS PHASE=ILOOP
IF (I=1)
LOOP _N=1,5
FND=FROM_TO(1,_N)
TND=FROM_TO(2,_N)

PATHLOAD PATH=LI.TIME FROMNODE=FND, TRACE=(TONODE=TND)

PATHLOAD PATH=LI.TIME FROMNODE=FND, TRACE=(TONODE =

75180-75190 || TONODE>=107170) PRINTO=1,
LIST=FROMNODE,TONODE,A,B,LI.TIME(10.2),LI.DISTANCE(10.2)
PATHLOAD PATH=LI.TIME FROMNODE=100500, TRACE=
(TONODE=TND) PRINTO=2
LIST=FROMNODE,TONODE,A,B,LI.TIME(10.2)
ENDLOOP

PATHLOAD PATH=LI.TIME FROMNODE=101000, TRACE=

(TONODE=76000,100000-100100) PRINTO=3
LIST=FROMNODE,TONODE,A,B,LI.TIME(10.2)
ENDIFENDPROCESS
ENDRUN

E xa mp le : us ing T R A CE S U MMA R Y to p rint p a th c o s t fro m

o rig in no d e to d e s tina tio n no d e
RUN PGM=HIGHWAY
FILEI NETI = "Highway.NET"
FILEO PRINTO[1]="PATHCOST.PRN"

PARAMETERS TRACESUMMARY=T
PHASE=ILOOP
IF (I=1)
PATHLOAD PATH=LW.TIME FROMNODE=100500, TRACE=
(TONODE=76000,100000-100100) PRINTO=1
LIST=FROMNODE,TONODE,_pathcost(10.2)
ENDIF
ENDPHASE
ENDRUN

An example of getting toll costs would entail having a LOOKUP function where the
lookup value is the gate-gate combination traversed on the path and the result of the
function is the toll value associated with gate-gate movement.
LINKIDMW=1-2
Cost = tolllook(MW[1]*1000+MW[2])

See “Example 6: Toll Gate accumulation using LINKIDARRAY” on page 314 for an
example of using the LINKIDARRAY keyword and its subkeywords in a script.
Highway Program > Control statements > PATHLOAD > PATHLOAD example

PATHLOAD exam ple

PATHLOAD PATH=COST, VOL[1]=MI.1.ODTRIPS
PATHLOAD PATH=COST, MW[6]=MW[3], SELECTLINK=(L=2001-2004),
VOL[1]=MW[3], VOL[2]=MW[6],VOL[3]=MW[3],TIME=0-7.5

This first PATHLOAD statement causes the COST paths to be built, and then the values
from MI.1.ODTRIPS are assigned and added to VOL[1].
The second PATHLOAD statement causes the following sequence of events:
1. COST paths are built.

2. MW[6] is set equal to the values in MW[3] for the Js whose path from I crosses link 2001-
2004. Note that MW[6] was cleared at the beginning of the ILOOP for I, but if the user
caused any values to be set into MW[6] prior to this statement, the MW[6] values could be
incorrect.

3. The values from MW[3] are assigned to the COST paths and added into VOL[1] volumes.

4. The values from MW[6] (the selected link trips) are assigned to the COST paths and added
into VOL[2].

5. The values from MW[3] are assigned to only the links that are within 7.5 minutes from I and
added into VOL[3] (these are the cold start volumes).
Highway Program > Control statements > PATHLOAD > Example

Exam ple
/*
The first PATHLOAD statement below (PATH is a trigger keyword – PATHLOAD is not
required) builds the DISTANCE paths and illustrates two different ways to extract a
LOS matrix for the path.
The second PATHLOAD statement builds the COST path using penalties and shows that
the two extracted matrices are not necessarily the same because of the penalties.
The comments illustrate how to properly skim a path when penalties should be
incorporated.
*/
PATH=LI.DISTANCE,MW[1]=PATHTRACE(LI.DISTANCE),MW[2]=PATHCOST
; MW[1] and MW[2] are the same in this case
PATH=TIME, PENI=1,3 MW[1]=PATHTRACE(COST),MW[2]=PATHCOST
; MW[1]and MW[2] could be different because penalties are used
; in the path. If MW[1]=PATHTRACE(TIME,1,3),they would be the same.
/*
Following is an example of trip splitting based upon the relative difference of time
if a link (say, a bridge) is added to the network. In this example the link is
already in the network, and it can be unavailable to the path builder by excluding
links with group code 1. The steps are:
1. Compute the time path with the bridge included and extract the times along the
path into MW[1].
2. Compute another path with the bridge excluded (group=1)and extract the times
along the path into MW[2]
3. Compute a path split based upon the total times for the two sets of paths. The
portion of trips that would use the bridge path is computed based upon the values in
the two time LOS matrices [1] and [2]. If the time saved exceeds 10 minutes and the
relative saving (time saved / total trip time) is greater than 15 percent, the
portion of trips that will use the bridge path is set equal to the relative saving.
(This is to illustrate a method of application, and is not meant to imply any type
of realistic diversion.)
4. Assign a portion of the trips to the one path set, and the remaining trips to the
other path set. The two assignments are made to the same volume set, but, they could
have just as easily be kept separate.
*/
PHASE=LINKREAD
If ((A=1001 & B=1002) | (A=1002 & B=1001)) ADDTOGROUP=1
PHASE=ILOOP
PATHLOAD PATH=TIME, MW[1]=PATHTRACE(TIME) ;w bridge
PATHLOAD PATH=TIME, EXCLUDEGROUP=1 MW[2]=PATHTRACE(TIME) ;wo bridge
JLOOP; MW[3] = the fraction of trips diverted to the bridge path
TimeSaved = MW[2] - MW[1]; 2 is always >= 1.
Divert = 0
RelativeSaving = TimeSaved / MW[2]
IF (TimeSaved > 10 && RelativeSaving >.15)Divert = RelativeSaving
MW[3] = Divert
ENDJLOOP
;assign bridge trips
PATHLOAD PATH=TIME, VOL[1]=MI.1.TRIPS*MW[3]
PATHLOAD PATH=TIME, EXCLUDEGROUP=1, VOL[1]=MI.1.TRIPS*(1-MW[3])
Highway Program > Control statements > PRINT

PRINT
Formats and prints a line of information. See “PRINT” on page 69 for details.
Highway Program > Control statements > PRINT > Example

Exam ple
IF (ITERATION = 0) ; LIST INPUT LINKS
LIST= A(5), B(5), NI.DIST(6), T0(6.2)
ENDIF
IF (ADJUST=1 && ITERATION >5 && VC >2.0) LIST='BIGVC for: ',A,B,VC(5.2)
Highway Program > Control statements > PRINTROW

PRINTROW
Formats and prints row(s) of matrices. See “PRINTROW” on page 77 for details.
Highway Program > Control statements > PRINTROW > Example

Exam ple
PRINTROW mw=1-2,1 form=LRD title='form=LRD'
PRINTROW mw=1-21 form=6D base1=y maxperline=10 form=6D,
base1=y maxperline=10
Highway Program > Control statements > PROCESS ... ENDPROCESS

PROCESS ... ENDPROCESS

Establishes phase blocks. Keywords include:
• PHASE

• ENDPHASE

A user process phase stack is defined by a PROCESS statement that names it and an
ENDPROCESS statement that ends it. To simplify coding, the PROCESS control word is not
necessary; PHASE=name may be used directly. And, to further simplify coding, the
ENDPROCESS statement is not necessary; the occurrence of another PROCESS statement
acts as the ENDPROCESS statement. If ENDPROCESS is used, it may be coded as either
ENDPROCESS or ENDPHASE.

P R OCE S S k e y wo rd s

Ke y wo rd D e s c rip tio n

PHASE |KS| Names the phase stack. The

control statements that follow it, until
an ENDPROCESS statement or
another PROCESS statement is
encountered, will be executed
when the phase is internally
executed.
Exception: Static statements, such
as PARAMETERS, FILEI, FILEO, and
LOOKUP, are not processed within
the stack, even if that is where they
are coded.
The following names may be
specified:
• SETUP
• LINKREAD
• ILOOP
• ADJUST

ENDPHASE |K| Defines the end of the user control

statements for a stack.
Highway Program > Control statements > PROCESS ... ENDPROCESS > Example

Exam ple
PHASE=LINKREAD
T0 = LI.DISTANCE*60 / SPEED
ENDPHASE
PHASE=ILOOP
PATH=TIME, VOL[1]=MI.1.ODTRIPS
ENDPHASE
PHASE=ADJUST
LW.TIME = TIME * LW.FLAGCODE
ENDPHASE
Highway Program > Control statements > REPORT

REPORT
Requests reports and establishes tracing.
Keywords and sub-keywords include:
• CA P A CIT Y

• PENI

• SPEED

• T R A CE

• VDT SPD
m I
m J
m FILE
m RANGE
m VOL

• ZD A T
m DEC

R E P OR T k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

CAPACITY |?| Switch that indicates if the

capacity portion on the
SPDCAP tables is to be
reported.

PENI |?| Switch to turn off dynamic

printing of the turn delays
calculated by the junction model
and reported every iteration. If
there are a larger number of
junctions coded in the network
then PENI=T could result in
voluminous print file.

SPEED |?| Switch that indicates if the speed

portion on the SPDCAP tables is
to be reported.

TRACE |K?| Controls the listing of the stack

statements as they are
processed (can be quite
voluminous, so be careful).
Trace can be turned on and off
at any time, thus controlling the
amount of output as desired. If a
COMP is traced, only the first
five J values will be reported.
VDTSPD |?| Switch that indicates if the
vehicle distance traveled
stratified by average trip speed
is reported. Note that this report
requires considerably more
computer resources (both
process time and disk space). If
no subkeywords are appended
to this keyword, the program will
simulate: RANGE=0-100-1.
There may be any number of
VDTSPD keywords.

VDTSPD I |IV| Specifies which origin zones are

to be included in this report. If
this keyword is not specified, all
origin zones will be included.

VDTSPD J |IV| Specifies which destination

zones are to be included in this
report. If this keyword is not
specified, all destination zones
will be included.

VDTSPD FILE |F| Specifies a file where the

VDTSPD reports are to be
written (exported) in a format that
can be easily read by most
spreadsheet software.
Specifying FILE will not preclude
the reports from being printed. If
the same file is specified
following different VDTSPD
keywords, the output will be
stacked onto the file.

VDTSPD RANGE |IP| Specifies the speed

stratification for this report. The
values can have at most one
decimal place. There must be at
least two values, and possibly
three for each sub report. For
example:
• RANGE=0-100 specifies
that the report is to have
only one number reported.
• RANGE=0-100-1
specifies that the report is
to have 100 values
reported.
• RANGE=0-7.5, 7.5-
100-5 specifies that two
different schemes are to
be obtained.
With multiple RANGE sets, an I-J
value can be placed into more
than one RANGE set. Each
subreport will not only contain
values for the RANGE specified,
it will also include any values
less than the low value and any
values greater than the highest
 value.
If RANGE=2-5-1 is specified,
the printed report will appear as:
x-2
Interval includes speeds >=
x and < 2, x is the lowest
speed found
2-3
Interval includes speeds >=
2 and < 3
3-4
Interval includes speeds >=
3 and < 4
4-5
Interval includes speeds >=
4 and < 5
5-y
Interval includes speeds >=
5, y is the highest speed
found

VDTSPD VOL |IP| Specifies which volume sets are

to be included in this report. If
this keyword is not specified, the
program will report all volume
sets.

ZDAT |?| Switch that indicates if all the

internal arrays obtained from
FILEI ZDATI files are to be
reported.

ZDAT DEC |I| Sets the maximum number of

decimal places to be printed for
any variable. This one value
applies to all variables on all
ZDATI statements.
Highway Program > Control statements > REPORT > Example

Exam ple
TRACE=y ; turn stack tracing on
REPORT CAPACITY=yes
; report the capacities by lane by CAPCLASS
REPORT VDTSPD=T,
VOL=1, I=1-933, J=1-933,
RANGES=0-7.5, 7.5-100-5,
FILE=VDTSPD.TXT
Highway Program > Control statements > SET

SET
Sets multiple variables or arrays to the same value.
• VAL

• VARS

Use SET to set any number of variables to some value. All variables are set to zero when
they are first allocated. COMP statements produce most changes. A COMP statement is
not as efficient as a SET statement.
S E T k e y wo rd s

Ke y wo rd D e s c rip tio n

VAL |R| Value that the VARS that follow will be set
to. It must be a numeric constant. VAL is
initialized to zero when the statement is
encountered.

VARS |S| List of variables that are to be set to the

more recent value of VAL obtained from
this statement. If a VARS is the name of an
array established on an ARRAY
statement, the entire array will be set to
VAL.
Highway Program > Control statements > SET > Example

Exam ple
SET VAL=0, VARS=TOT1,TOT2,COUNTER
TOT1=0 TOT2=0 COUNTER=0
; is a COMP statement to do the same thing
SET VARS=TOT1 TOT2 COUNTER ; is also the same (VAL is 0)
SET VAL=123 VARS=C123, VARS=TOT1, TOT2, TOT3
; sets all to 123
SET VAL=0, VARS=VA1,VA2,VA3, VAL=100, VARS=VX, VY
Highway Program > Control statements > SETGROUP

SETGROUP
Sets group codes for a link.
• A D D T OGR OU P

• R E MOV E FR OMGR OU P

Use SETGROUP to set group codes for a link; it is applicable during only the LINKREAD
phase. Group codes are used primarily for designating links that are to be excluded in
path-building, and for inclusion in select link analysis. Each link can have up to 32
different group codes assigned to it. The codes are numbered 1-32. There are no
preconceived definitions for the codes; that is the user’s responsibility. Group codes can
be quite helpful in project analysis or for determining specific interchange to interchange
movements.
S E T GR OU P k e y wo rd s

Ke y wo rd D e s c rip tio n

ADDTOGROUP |KIP| Specifies that the current

link is to be assigned the
codes that are in the value
list.

REMOVEFROMGROUP |KIP| Specifies that the current

link is to have the
designated values
removed from its codes.
This keyword normally
should not be used.
Highway Program > Control statements > SETGROUP > Example

Exam ple
PHASE=LINKREAD
IF (LI.SPDCLASS==1-3,6,9,55) ADDTOGROUP=1
Highway Program > Control statements > SORT

SORT
Sorts user-defined arrays. See “SORT” on page 81 for details.
Highway Program > Control statements > SPDCAP

SPDCAP
Revises speed and capacity tables.
• CA P A CIT Y

• LA N E S

• SPEED

The SPDCAP statement is the same as that used in the Network program to revise the
SPEED and CAPACITY tables attached to the network. If this statement is used in the
control file for the Highway program, the values from the NETI are updated when NETI is
opened. This capability allows you to test various scenarios without having to modify the
network. The revised tables will be written to the NETO file.
S P D CA P k e y wo rd s

Ke y wo rd D e s c rip tio n

CAPACITY |RV*99| Capacity in vehicles per lane per

hour. Actual link capacity is obtained
by multiplying the link capacity based
upon its capacity classification
(CAPCLASS) value by the number of
LANES. All values must be 0-9999,
inclusive. The capacity array is
initialized to 20 times the index
number, for all lane stratification
(CAPACITY[1]=20,
CAPACITY[2]=40...).

LANES |IV| Lane stratification that any following

CAPACITY and/or SPEED values are
to apply to. LANES may be
interspersed with other keywords and
values on the statement. All values
must be 1-9, inclusive.

SPEED |RV*99| Speed to be applied to the link. All

values must be 0-3276.7, inclusive.
The speed array is initialized to the
index number, for all lane stratification
(SPEED[1...99]=1,2,...99). Speed is
maintained with one decimal place.

A network contains an array of capacity and speed data. Each array is dimensioned with
ninety-nine values for each of nine lane stratification, and contains 891 values. When an
array is accessed, the program uses the number of lanes (LANES) as the row index, and
the capacity and/or speed classification (CAPCLASS, SPDCLASS) as the column index to
obtain a value for a link. If CAPACITY or SPEED is encountered prior to a LANES keyword on
the statement, LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector
data, and may be indexed to set a specific loading place, and may have null fields to
skip the revision of certain columns. The SPEEDFOR and CAPACITYFOR functions
can be used to obtain values for these tables.
Highway Program > Control statements > SPDCAP > Example

Exam ple
;Set entire table to 50,
; then revise the values for 20,21, and 24 for lanes 1,3,8
SPDCAP CAPACITY=99*50, LANES=1,3,8, CAPACITY[20]=300,400,,,700
SPDCAP LANES=2,4-9, SPEED=20.5,30.3,50.6,,,88.2, LANES=5,SPEED[15]=15
SPDCAP SPEED=30, LANES=2-8; Inappropriate; the LANES will not be used.
Highway Program > Control statements > TURNS

TURNS
Requests turning movement volumes.
• N

• T

Use TURNS to request that the volumes at specific interchanges (nodes) be accumulated.
If there is at least one TURNS statement, the program will accumulate turns for every
PATHLOAD VOL[]= statement that is present. At the end of each iteration (in the Adjust
phase), a single total turn volume will be computed for each movement at the nodes
where turns are requested (these volumes may also be used by an intersection model, if
one exists).
By default, the single volume is computed by adding all the individual turn volume sets
together (T = TURN[1] + TURN [2] + TURN [..] ...). This default accumulation process
can be overridden by using the T= capabilities on this statement. Usually, the T=
expression should be parallel to the V= expression that is specified on a FUNCTION
statement. If additional volume sets are required for SELECTLINK analysis, only the turn
volume sets corresponding to the original volume indices should be summed. This
avoids double counting in the TURNS request.
For example, when
FUNCTION V = VOL[1] + VOL[2]

Then the corresponding TURNS request should be:

TURNS T = TURN[1] + TURN[2]

The value of T for each movement will be computed in the Adjust phase, and then
combined with other iteration values to form the “combined” volume.
By default, when there is no 'N=XXX-XXX' set specified by the user (or no TURNS
statement), the Highway program will only consider junction related nodes and links
(from the input junctions file) in the turn volume accumulation and corresponding
iteration-by-iteration statistics' calculation. Users should decide to set N=XXX-XXX
accordingly to their requirements in terms of turn volumes accumulation and
corresponding statistics calculation (e.g., when using TURNPENI, to accumulate non-
junction nodes).
To accumulate turn volumes, you must specify a FILEO TURNVOLO statement. The turn
volumes will be written to the file(s) specified on that statement.
T U R N S k e y wo rd s

Ke y wo rd D e s c rip tio n
N |IP| List of nodes at which turning volumes are
to be accumulated. Default: only junction
related nodes.

T |N| Expression used to compute the total

volume at each of the nodes.
Highway Program > Control statements > TURNS > Example

Exam ple
FILEO TURNVOLO=myfile.trn, FORMAT=BIN
TURNS N=1000-2000,3000,5000-6000,19000-32000, T=TURN[1] + TURN[3]
Highway Program > Theory

Theory
This section discusses topics related to the theory used in the Highway program. These
include:
• Process overview

• Stochastic traffic assignment theory

• User stacks
Highway Program > Theory > Process overview

Process overview
It is important to have a basic understanding of the logic of the program, so that when
certain special operations are to be performed, they can be placed properly. Although
you can place phases in the script in any order, Citilabs suggests that you use a basic
template for all applications. If you use a basic template, then only the actual operations
of each segment need be completed.

E xa mp le o f s ug g e s te d b a s ic a p p lic a tio n te mp la te
RUN PGM=HIGHWAY
FILEI
FILEO
FUNCTION ; include V, TC, and COST functions
here
PHASE=SETUP ; normally this phase is not used
...
PHASE=LINKREAD ; insert any statements required to:
; extract custom information from the
input network.
...
PHASE=ILOOP ; build paths, skim paths, load trips
to paths
...
PHASE=ADJUST ; revise special LW.values for next
iteration
...
PHASE=CONVERGE ; optional for user specified
convergence tests
...
ENDRUN

The internal logic of the program is as follows:

• PHASE = SETUP
m
Establish user SET arrays, etc. This phase is not specified by most users. If there is a
PHASE=SETUP block, perform the statements of the block.
m
ENDPHASE

• PHASE = LINKREAD
m
Loop LINKNO=1,NUMLINKS
• Read each link record.
• If there is a user supplied LINKREAD block, process it, then set the required values
that LINKREAD did not set properly
• Set the Time and Cost values
m
EndLoop
 m
ENDPHASE

• LOOP ITERATION=1,MAXITERS

• PHASE = ILOOP
m
Loop I=1,ZONES
• Read required MATIs.
• Process the ILOOP stack.
• Write requested MATOs.
m
EndLoop
m
ENDPHASE

• PHASE = ADJUST
m
Loop LINKNO=1,NUMLINKS
• Read each link record.
• Obtain link values using most of the LINKREAD process
• Apply the appropriate Functions (V, TC, COST) for the link.
• Process the user’s ADJUST stack to either list the results of the assignment, or to
revise LW.values, or Time for the next iteration.
• Apply Function Cost.
m
EndLoop.
m
Depending upon the values for COMBINE and ITERATION:
• Combine link volumes.
• Combine MATO matrices.
m
Process the CONVERGE stack (user or default)
m
If Convergence met, exit ITERATION Loop.
m
ENDPHASE

• ENDLOOP ; Iteration loop

Highway Program > Theory > Stochastic traffic assignment theory

Stochastic traffic assignment theory

This section provides theoretical background on the Probit and Burrell stochastical traffic
assignment methods. After applying either of these methods during an iteration,
Highway will find an All or Nothing Path based on the current congestion level. The
stochastic assignment methods use Method of Successive Averages (MSA), for
combining the volumes from the different iterations. Users are recommended to run
considerable number of iterations to achieve reasonable convergence.
Burrell's method and Probit method are descibed below, or, you may skip ahead to All or
Nothing Path.
Highway Program > Theory > Stochastic traffic assignment theory > Burrell's method

Burrell's method
The travelers’ perceived travel cost follows a Uniform Distribution of the individual link
cost, where the mean of the link cost and variance is supplied by the user.
m
The loading process is based on perturbing link cost values used in path building away
from the mean value (input by user), which gives rise to one sample set of paths for
each origin. It generates one path per OD pair at each iteration based on the uniformly
distributed link cost.
Highway Program > Theory > Stochastic traffic assignment theory > Probit method

Probit method
The travelers’ perception error follows a Normal Distribution, where the random
perceived link cost has mean equal to the measured link travel cost and its variance is
proportional to the measured link travel cost. The proportional parameter can also be
controlled by the user.
• The probit-based stochastic assignment is able to alleviate the drawbacks of logit-based
stochastic assignment (i.e., the inability to account for correlations between alternatives?
utilities, and the inability to account for perception variance with respect to trips of different
costs.), and provides reasonable results.

• Probit-Loading process is simple, and it does not require the sampling of the perceived
path travel times; only perceived link travel times are sampled at each iteration thus
avoiding path enumeration. Probit-loading process requires higher computational time than
the logit-based loading based on Dial’s method. At the price of high computational time, it
provides reasonable results.
Highway Program > Theory > Stochastic traffic assignment theory > All or Nothing Path

All or N othing Path

Last, during each iteration, the algorithm finds an All or Nothing path based on the
current congestion level (sampled based on link travel time’s mean and variance
restricted by the user specified spread factor). This avoids the requirement to explicitly
generate path. In Cube, the spread factor is controlled by SPREADPERC and
SPREADPERCVAR, and the stability of the random sample are ensured by
LINKRANDSERIES (i.e. bind the sample with given network and make the results
repeatable).
Now if LINKRANDSERIES is true, then STOCHASTICSEED must be set to a constant value,
otherwise you will get random results. If STOCHASTICSEED is not specified, then it takes a
default value of 1. If LINKRANDSERIES is false and STOCHASTICSEED is not specified, then
it is defaulted to a random seed based on the current time. Basically one can have
random result, for which you will not set LINKRANDSERIES and STOCHASTICSEED . If you
want consistent results, then you will have to set LINKRANDSERIES and STOCHASTICSEED .
If you set STOCHASTICSEED only, then you will get exact same result if there is no change
in the network.
Highway Program > Theory > User stacks

User stacks
These are stacks of control statements that you provide to perform certain operations at
various times in the process. The term stack, as used here, means all the user supplied
statements for the phase. Stack and phase are sometimes used interchangeably.
Phase refers to a phase the program automatically processes, and stack refers to the
user supplied statement for that phase. The ILOOP stack is required, but all the others
are optional. Most times, the other stacks will not be necessary, but it does provide a
mechanism for altering program variable values at crucial times. Each stack begins with
a PROCESS PHASE = StackName statement. (PHASE is a trigger key, so most users
will just code PHASE= without the leading control word.) The operational statements
that are to be preformed in this stack follow the PHASE statement. The stack is
terminated by the presence of another PHASE = stackname statement, an ENDPHASE
statement, or the end of input. Non-operational statements (FILEI, FILEO,
PARAMETERS, FUNCTION and others) can be within a stack, but they are ignored
during stack processing. It is suggested that all non-operational statements be placed at
the beginning of the input for reader clarification. Each of the phases, may be specified
one time only. IF and LOOP blocks must be complete within a stack, and GOTO and
associated label statements must be within the same stack. EXIT and ABORT will
cause termination of a stack, but will have impact on the actual program process only
from ILOOP.
Highway Program > Theory > User stacks > LINKREAD stack

LINKREAD stack

This stack is in the LINKREAD phase, and is used as explained above in that section.
Primarily, it is used to obtain required link values (if they are not directly available from
the input network), and to set link LW.values and GROUP codes.
Highway Program > Theory > User stacks > ILOOP stack

ILOOP stack

This stack is the entire ILOOP phase, and is described previously. It MUST be present.
Highway Program > Theory > User stacks > ADJUST stack

ADJUST stack

This stack is processed as the last operation in the ADJUST phase link loop. It provides
a place for computing and accumulating special values such as objective functions
(currently undocumented). It also provides the capability to print certain link values
during the process. If LW.values are dependent upon Time and/or Cost, and it is
necessary to reflect the changes in those values to the LW.values for the next iteration,
the adjustment can be made here. Alternatively, the LW.values can be adjusted with
ILOOP statements.
Highway Program > Theory > User stacks > CONVERGE stack

CONVERGE stack

This stack is processed during convergence testing in the ADJUST phase. Its primary
purpose is to set BALANCE to 1 if certain conditions are met. Most users will not have
any need for this stack.
Highway Program > Examples and FAQ

Examples and FAQ

This section contains examples for using the Highway program, along with a link to
Frequently Asked Questions.
• Example 1: Simple Equilibrium Assignment

• Example 2: Level-of-Service Skimming

• Example 3: Junction-Constrained Equilibrium Assignment

• Example 4: Subarea Assignment and Extraction

• Example 5: Select-Link Assignment

• Example 6: Toll Gate accumulation using LINKIDARRAY

• Example 7: Using TOLLMATI to incorporate closed system Tolls in the Pathbuilding

process

• Example 8: Multiple User Class Assignment with Cost based on User Class

• Example 9: Multiple User Class Assignment with Cost based on Link Class

• Example 10: Shortest Path Trees Using TREEO

• Example 11: Using TOLLMATI and TOLLVOLO

• Frequently asked questions

Highway Program > Examples and FAQ > Example 1: Simple Equilibrium Assignment

Example 1: Simple Equilibrium Assignment

This example shows a simple equilibrium assignment procedure assuming a typical
input highway network providing CAPACITY, DISTANCE AND SPEED on the link
attributes.

RUN PGM=HIGHWAY
FILEI NETI = Network.net
FILEI MATI[1] = TRIPS.mat
FILEO NETO = LOADED.NET
PARAMETERS COMBINE=EQUI MAXITERS = 99 GAP=.0001
PROCESS PHASE = LINKREAD
C = LI.CAPACITY ; set capacity equal to a link field
; assumes DISTANCE and SPEED are available on the input network
; no LINKCLASS defined, therefore defaults to 1 for all links
ENDPROCESS
PROCESS PHASE=ILOOP ; main loop for program
PATHLOAD PATH=TIME, ; build path based on time
VOL[1]=MI.1.CAR ; load trips from input matrix to volume set 1
ENDPROCESS
; No TC functions defined therefore congested travel times computed using
; the standard BPR formula for all links.
; No COST function defined therefore COST defaults to TIME
ENDRUN
Highway Program > Examples and FAQ > Example 2: Level-of-Service Skimming

Example 2: Level-of-Service Skimming

This is a simple example of using HIGHWAY to ”SKIM” level of service information from
the loaded highway network from Example 1. This example builds paths on the
congested travel time variable in the loaded network and ”Skims,” or extracts, the zone-
to-zone times and distances for those paths to an external matrix file.

RUN PGM=HIGHWAY
FILEI NETI = LOADED.NET

FILEO MATO[1] = HWY_SKIMS.MAT,

MO=1-2,NAME= 'HWY Time', ‘HWY Distance’
PROCESS PHASE=LINKREAD
T0=li.TIME_1 ; Final congested travel times on the input network
ENDPROCESS
PROCESS PHASE=ILOOP
; Loop across all origin zones and build path using congested time.
; skim TIME and DISTANCE for the min TIME paths into work matrices 1 and 2
PATHLOAD PATH=TIME, MW[1]=PATHTRACE(TIME), MW[2]=PATHTRACE(LI.DISTANCE)
; For intrazonals, make the intrazonal time equal to half the time to the nearest
zone
COMP MW[1][I] = rowmin(1) * 0.5 ; Intrazonal time
; Set the intrazonal distance equal to 0
COMP MW[2][I] = 0
ENDPROCESS
ENDRUN
Highway Program > Examples and FAQ > Example 3: Junction-Constrained Equilibrium Assignment

Example 3: Junction-Constrained Equilibrium

Assignment
This example script runs a junction constrained equilibrium assignment dumping the
path file, final turn delays and the binary junction data file.

RUN PGM=HIGHWAY
FILEI NETI = NETWORK.NET
FILEI MATI[1] = VEHICLETRIPS.MAT
FILEI JUNCTIONI = JUNC_BASE.IND,
period=60,set=1
FILEO NETO = LOADED.NET
FILEO PATHO[1] = ROADPATHS.PTH
FILEO TURNPENO = TURNDELAYS.DAT
FILEO JUNCTIONO = TURNS.INT
; set convergence method and criteria
PARAMETERS COMBINE = EQUI, GAP = 0.005, maxiters=99
PARAMETERS EQUITURNCOSTFAC=1
; ----- SET CAPACITY and group links
PROCESS PHASE=LINKREAD
C = LI.CAP
IF (LI.FUNC_CLASS = 1-2) LINKCLASS=1
IF (LI.FUNC_CLASS = 3-10) LINKCLASS=2
ENDPROCESS
PROCESS PHASE=ILOOP
PATHLOAD PATH = TIME, VOL[1]=MI.1.1,
PATHO=1, NAME='assignment',ALLJ=T,
INCLUDECOSTS=T,PENI=1
ENDPROCESS
PROCESS PHASE=ADJUST
function {
tc[1]=t0*(1.0+0.15*((v/c)^8))
; congested time function for major roads
tc[2]=t0*(1.0+0.15*((v/c)^4))
; congested time function for minor roads
ENDPROCESS
ENDRUN
Highway Program > Examples and FAQ > Example 4: Subarea Assignment and Extraction

Example 4: Subarea Assignment and Extraction

This script shows an example of both subarea assignment and subarea matrix
extraction for multiple trip purposes. The subarea network is created with CUBE/VIPER
POLYGON tools with the default renumbering of the network.

RUN PGM=HIGHWAY
NETI=DEMO.NET
; subarea network created with POLYGON tools in CUBE/VIPER
FILEI SUBAREANETI=subarea1.net
MATI=TRIPSBYPURPOSE.MAT
FILEO NETO=Loaded_DEMO.NET
FILEO SUBAREAMATO=submat1.mat NAME=HTW,WTH,HTO,OTH,NHB,TOTAL
PARAMETERS COMBINE=EQUI GAP=.0001
PHASE=LINKREAD
LINKCLASS=LI.CLASS
C=LI.CAPACITY
ENDPHASE
PHASE=ILOOP
; this PATHLOAD statement builds paths on TIME, assigns each trip purpose
; and the total trips to separate volume sets,
; extracts a subarea matrix for each trip purpose and the total trips
PATHLOAD PATH=TIME,VOL[1]=mi.1.1,,VOL[2]=mi.1.2,VOL[3]=mi.1.3,VOL[4]=mi.1.4,
VOL[5]=mi.1.5,VOL[6]=mi.1.6,
SUBAREAMAT[1]=mi.1.1,SUBAREAMAT[2]=mi.1.2,
SUBAREAMAT[3]=mi.1.3,SUBAREAMAT[4]=mi.1.4,
SUBAREAMAT[5]=mi.1.5,SUBAREAMAT[6]=mi.1.6
ENDPHASE
PHASE=ADJUST
; volume function V sets the volume to use for V/C in the delay function
; No delay functions (TC[#]=) are specified here so the default BPR
; formula is used for all link classes
FUNCTION V=VOL[6] ; set volume to use in congested travel time functions
ENDPHASE
ENDRUN
Highway Program > Examples and FAQ > Example 5: Select-Link Assignment

Example 5: Select-Link Assignment

This script has two steps. In step 1 several examples of select link assignment are
shown. In step 2, a MATRIX job is run to build trip end reports for the select link trip
matrices created in step 1.

; Step 1 Select Link Assignment

RUN PGM=HIGHWAY
MATI=TRIPS.MAT
NETI=DEMO.NET
NETO=DEMOSelectLink.NET
MATO = MATVOUT.MAT,mo=1-2,4 dec=2, combine=Y
; this is an example of an incremental assignment procedure
; the number of fractions defines the number of iterations
; at each iteration the listed fraction of the trip table is assigned
COMBINE=SUM,FRACTIONS=0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.05,0.05,0.05,0.05,0.05,0.05
; Equilibrium assignment could be performed specifying COMBINE=EQUI
; or volume averaging by specifying COMBINE=AVE if desired
PHASE=LINKREAD
LINKCLASS=LI.CLASS
C=LI.CAPACITY
ENDPHASE
PHASE=ILOOP
PATH=TIME,VOL[1]=mi.1.6, mw[1] = mi.1.6, selectlink = (L=1449-1495),
vol[2] = mw[1]
mw[2]=mi.1.6

/* this step says “build paths based on time, assign trips from mi.1.6 to these
paths and put them in Volume set 1 (V1_1 on the output network), put trips from
mi.1.6 into working matrix 1 if they are on paths that use the selected links (L=),
assign the trips in working matrix 1 (the select link trips) back to the time based
paths and put them into Volume set 2 (V2_1 on the output network), and lastly put
the total trips assigned from mi.1.6 into working matrix 2. Note that on the MATO
line mo=1-2 will output the selected trip matrix (1) and the total trip matrix
assigned (2) */

PATH=TIME,VOL[3]=mi.1.6, mw[4] = mi.1.6, selectlink = (L=1494-1423),

vol[4]=mw[4]

/* this step says “build paths based on time, assign trips from mi.1.6 to these
paths and put them in Volume set 3 (V3_1 on the output network), put trips from
mi.1.6 into working matrix 4 if they are on paths that use the selected links (L=),
assign the trips in working matrix 4 (the select link trips) back to the time based
paths and put them into Volume set 4 (V4_1 on the output network). Note that on the
MATO line mo=4 will output the selected trip matrix (4) for the links L=. Now you
have 4 volume sets, but only want to calculate congested travel times based on the
true total volumes on each link. This is why you need the function V=vol[1]. Note
that V=vol[3] would give the same result as these two sets are the same. The V
function is automatically executed during the adjust phase. */

ENDPHASE
PHASE=ADJUST
function { V=vol[1] }

/* this function sets the volume for the capacity restraint to be the total volume.
Without this statement, V is set to the sum of all volume sets which double counts
volume when you have a select link volume set */

ENDPHASE
ENDRUN

; Step 2 Extract and report select link trip ends

RUN PGM=MATRIX
; note this example was for a 25 zone network
FILEI MATI=matvout.mat
mw[1]=mi.1.1
array sum_mat = 25
array row_tot = 25
row_TOT[I] = rowsum(1)
Jloop
sum_mat[J] = sum_mat[J] + mw[1][J]
endjloop
IF (I=25)
LOOP INDEX=1,25
PRINT FORM=10.0, LIST=INDEX,ROW_TOT[INDEX],SUM_MAT[INDEX],
file =SelectTripEnds.txt
ENDLOOP
ENDIF
ENDRUN
Highway Program > Examples and FAQ > Example 6: Toll Gate accumulation using LINKIDARRAY

Example 6: Toll Gate accumulation using

LINKIDARRAY
This script is an example of using LINKIDARRAY to accumulate information about toll gate
use from the paths into working matrices. In this example, the LINKIDARRAY uses
li.TOLL. This network data field contains a value of 1-8 corresponding to one of the eight
toll bridges in the San Francisco Bay Area network. The output work matrices include:
#1 is the travel time on the I-J path, #2 is the number of toll gates traversed on the path,
#3 is the number of the last toll gate traversed on the path and #4-#8, include the 1st,
2nd, 3rd and 4th gate number traversed on the path if used.

RUN PGM=HIGHWAY
FILEI NETI = SF_BAY_AREA.NET
FILEO MATO[1] = test.mat,
mo=1-8
PHASE=LINKREAD
LW.TIM=LI.DISTANCE/LI.FFS * 60
If (li.USE=2,3) ADDTOGROUP=1 ; don't use HOV facilities,
; they by pass tolls
ENDPHASE
PHASE=ILOOP
PATHLOAD PATH = LW.TIM, EXCLUDEGROUP=1,
MW[1] = PATHTRACE(LW.TIM), LINKIDARRAY=li.TOLL,
LINKIDCNTMW=2 LINKIDLASTUSE=3 LINKIDMW=4-8
ENDPHASE
ENDRUN
Highway Program > Examples and FAQ > Example 7: Using TOLLMATI to incorporate closed system Tolls in the
Pathbuilding process

Example 7: Using TOLLMATI to incorporate closed

system Tolls in the Pathbuilding process
This example uses TOLLM ATI to incorporate closed system tolls into the pathbuilding
process. In this example, the paths are built on COST and the COST function will
include any gate to gate tolls traversed on a path.

RUN PGM=HIGHWAY
FILEI TOLLMATI[1] = "TOLL.DBF",
ENTRYGATE=ON_RAMP, EXITGATE=OFF_RAMP, TOLLS=COST_CAR,COST_TRUCK,
NETIENTRY=ONRAMP, NETIEXIT=OFFRAMP, NETITOLLROAD=TOLLROAD
FILEI NETI = "BASE.NET"
FILEI TURNPENI = "PROHIBIT1.PEN"
FILEI MATI[1] = "PKHOURTRIPS.MAT"
FILEO TURNVOLO[1] = "TURNS.DBF",
FORMAT=DBF
FILEO NETO = "TOLLLOAD.NET"
FILEO PATHO[1] = "TOLLPATH.PTH"
FILEO JUNCTIONO = "JUNCTION1.DAT"
FILEO MATO[1] = "TOLLSKIM.MAT",
MO=1-5,99 NAME=PATHCOST,COST,PATHTOLL,TIME,VEHTOLLS,LOADS

PAR MAXITERS=20
TURNS N=1-9999

PROCESS PHASE=LINKREAD

C = LI.CAP
IF (LI.FUNC_CLASS = 1-2)
LW.COEF=0.15
LW.EXPO=8.00
ELSE
LW.COEF=0.15
LW.EXPO=4.00
ENDIF

ENDPROCESS

PROCESS PHASE=ILOOP
; -----------------------------------------------------------
; trips to load
MW[99]=MI.1.1+MI.1.2
; -----------------------------------------------------------
; Assign WITH TOLL COST CONSIDERED
PATHLOAD PATH=COST, VOL[1]=MW[99],
PENI=1 TOLLMATI=1,1,
TOLLFACTOR=2.0, ; toll factor is in min/toll units,
; here 2min/$ (implies VOT=$30/hr)
MW[1]=PATHCOST, NOACCESS=0,
MW[2]=PATHTRACE(COST,1), NOACCESS=0,
MW[3]=PATHTOLL,
MW[4]=PATHTRACE(TIME,1),NOACCESS=0,

MW[5]=mw[3]*mw[99] ; cross trips with tolls

ENDPROCESS

PROCESS PHASE=ADJUST
function {
tc=t0*(1.0+LW.COEF*((v/c)^LW.EXPO))
; congested time function for major roads
}
ENDPHASE
ENDRUN
Highway Program > Examples and FAQ > Example 8: Multiple User Class Assignment with Cost based on User Class

Example 8: Multiple User Class Assignment with Cost

based on User Class
These examples use generalized cost functions customized for different user classes.
Highway will then use the COST of the system to compute Lambda and the
convergence measures.
• The examples are described under Multiple user class assignment using generalized cost
functions.
Highway Program > Examples and FAQ > Example 9: Multiple User Class Assignment with Cost based on Link Class

Example 9: Multiple User Class Assignment with Cost

based on Link Class
This example shows a multi user class equilibrium assignment, building paths on a
generalized cost function with the cost functions differentiated by the facility type
(LINKCLASS). Turn penalties are included in the path building process and the PATH
file is saved for graphical analysis.
Compared to the previous Example 8: Multiple User Class Assignment with Cost based
on User Class, here there is only one PATHLOAD that assigns both VOL[1] and VOL[2]
based on PATH=COST. Both user classes are thus assigned based on the same cost
function.

RUN PGM=HIGHWAY
FILEI NETI = NETWORK.NET
FILEI MATI[1] = TRIPS.MAT
FILEI TURNPENI = TURNPEN.PEN
FILEO NETO = LOADED.NET
FILEO PATHO[1] = HWY_PATHS.PTH
; set parameters and values for time and distance costs
PARAMETERS COMBINE = EQUI GAP = 0.005
time_cost1 = 0.5
time_cost2 = 0.7
distance_cost1 = 0.2
distance_cost2 = 0.4
; ----- SET CAPACITY and LINKCLASS
PROCESS PHASE=LINKREAD
CAPACITY = LI.CAPACITY * 1.0
; set link classes for major roads
IF (li.CLASS = 1-4) LINKCLASS = 1
; set link classes for minor roads
IF (li.CLASS = 5-10) LINKCLASS = 2
; group railway links for exclusion from assignment
IF (li.CLASS = 11 | li.CLASS = 12) ADDTOGROUP=1
ENDPROCESS
PROCESS PHASE=ILOOP
PATHLOAD PATH=COST, PENI=1-2, ; include turn penalties,
VOL[1]=MI.1.CAR, ; load car trips,
VOL[2]=MI.1.TRUCKS, ; load truck trips,
EXCLUDEGROUP=1, ; exclude rail links
PATHO=1 NAME=COST_PATH INCLUDECOSTS=T ALLJ=T
; save path file ENDPROCESS
PROCESS PHASE=ADJUST
; Define cost and delay functions
function {
tc[1]=t0*(1.0+0.15*((v/c)^8))
; congested time function for major roads
tc[2]=t0*(1.0+0.15*((v/c)^4))
; congested time function for minor roads
cost[1]=time*time_cost1+li.distance*distance_cost1
 ; cost function for major roads
cost[2]=time*time_cost2+li.distance*distance_cost2}
; cost function for minor roads
ENDPROCESS
ENDRUN
Highway Program > Examples and FAQ > Example 10: Shortest Path Trees Using TREEO

Example 10: Shortest Path Trees Using TREEO

The FILEO TREEO and PATHLOAD TREEO can be used to output shortest path trees.
Below is a sample script, descriptions of the outputs and step-by-step guide on how to
read the output file.
RUN PGM=HIGHWAY
NETI=Highway.net
TREEO[1]="PathTree.txt",
FORMAT=TXT,
ROWTYPE=0,
CELLTYPE=1,
FORM=10, 6, 6,
ORIGINTYPE=0,
LISTNETNODE=T,
LISTCOLNUMS=T,
LISTLINKS=T,
LISTALTNODES=T,
ALTNODEFIELD=EMNODENUM
PHASE=ILOOP
PATH=LI.T0,
TREEO=1, NAME='Free Flow'
ENDPHASE

ENDRUN

Output Descriptio n 1: ROWTYPE, LISTCOLNUMS, LISTLINKS, LISTNETNODE,

CELLTYPE

Output Descriptio n 2: FORM

Output Descriptio n 3: ORIGINTYPE, LISTALTNODES, ALTNODEFIELD

How to read a TREEO file?
To build a path from zone 4 to node 19, we follow the steps below:
Step 1:Go to the row for origin zone 4 (row #4) and column for node 19 (column #10).
Get the cell value. This value (in this case node 16) is the first node from the destination
19 (16 -> 19).
Step 2:Go to the row for origin zone 4 (row #4) and column for node 16 (column #7). Get
the cell value (in this case 15). The path tree further advances as 15 -> 16 -> 19.
Step 3:Go to the row for origin zone 4 (row #4) and column for node 15 (column #6) . Get
the cell value (in this case 18). The path tree further advances as 18 -> 15 -> 16 -> 19
Step 4:Go to the row for origin zone 4 (row #4) and column for node 18 (column #9) . Get
the cell value (in this case 4). The path tree further advances as 4 -> 18 -> 15 -> 16 ->
19
This completes the minimum cost path for origin zone to destination 19.
ROW TYPE= 0: Number of cells in each row is the number of nodes in the network
CELLTYPE= 1: The cell values are set to the highway node numbers
Highway Program > Examples and FAQ > Example 11: Using TOLLMATI and TOLLVOLO

Example 11: Using TOLLMATI and TOLLVOLO

RUN PGM=HIGHWAY
FILEI NETI=Toll.net
FILEO NETO=Tollload.net
FILEI MATI[1]=Trips.mat
FILEI TOLLMATI[1]=TollCost.dbf,ENTRYGATE=TollOn,EXITGATE=TollOff,TOLLS=Toll1,Toll2,
NETIENTRY=tollentry,NETIEXIT=tollexit,NETITOLLROAD=tollroad
FILEI TOLLMATI[2]=TollCost2.dbf,ENTRYGATE=TollOn,EXITGATE=TollOff,TOLLS=Toll1,Toll2,
NETIENTRY=tollentry,NETIEXIT=tollexit,NETITOLLROAD=tollroad
FILEI TOLLMATI[4]=TollCost4.dbf,ENTRYGATE=TollOn,EXITGATE=TollOff,TOLLS=Toll1,Toll2,
NETIENTRY=tollentry,NETIEXIT=tollexit,NETITOLLROAD=tollroad
FILEO tollvolo[1]=tolltrip.dbf, FORMAT=dbf,DEC=3, INCLUDE0=f
FILEO tollvolo[2]=dtowntest.mdb\tolltrip2,FORMAT=dbf,DEC[1]=d,INCLUDE0=f,
NAMES=OnGate,OffGate,-,-,-,-,MiNum,TSet,VSet,PSet,TollTrip
FILEO TOLLVOLO[3]=tolltrip.txt, FORMAT=txt,dec=1, INCLUDE0=f,ONGATES=1-2
FILEO TOLLVOLO[4]=tolltrip2.txt,FORMAT=txt,dec=2, INCLUDE0=f,OFFGATES=3-6,
NAMES=OnGate,OffGate,-,-,-,-,MiNum,TSet,VSet,PSet,TollTrip
FILEO TOLLVOLO[5]=tolltrip.csv, FORMAT=txt,dec=3,
INCLUDE0=f,DELIMITER=',',TOLLMATI=2-4
FILEO TOLLVOLO[6]=tolltrip2.csv,FORMAT=txt,DEC=4,
INCLUDE0=f,DELIMITER=',',TOLLMATI=2-4,
NAMES=OnGate,OffGate,-,-,-,-,MiNum,TSet,VSet,PSet,TollTrip

FILEO TOLLVOLO[7]=tolltrip.mat, FORMAT=mat,DEC=s,d,3*4, MO=M?T?V?P?

FILEO TOLLVOLO[8]=tolltrip2.mat,FORMAT=mat,DEC=s,d,3*4,PATHSETS=11,21,41,42,
TOLLSETS=2,MO=M1T1P12V3,M1T1P11V1,M4T1P?V?,M?T?V?P?
PHASE=ILOOP
MW[1] = MI.1.1
PATH=time, VOL[1]=MW[1] TOLLMATI=1,1 TOLLPATHSET=11
PATH=time, VOL[2]=MW[1] VOL[3]=MW[1] VOL[4]=MW[1] TOLLMATI=1,2 TOLLPATHSET=12
PATH=time, VOL[3]=MW[1]
PATH=time, VOL[4]=MW[1] TOLLMATI=2,2
PATH=time, VOL[4]=MW[1] TOLLMATI=2 TOLLPATHSET=20
PATH=time, VOL[1]=MW[1] TOLLMATI=4,1 TOLLPATHSET=41
PATH=time, VOL[2]=MW[1] VOL[3]=MW[1] VOL[4]=MW[1] TOLLMATI=4,2 TOLLPATHSET=42
PATH=time, VOL[3]=MW[1]
PATH=time, VOL[4]=MW[1] TOLLMATI=2,1 TOLLPATHSET=21
PATH=time, VOL[4]=MW[1] TOLLMATI=4 TOLLPATHSET=40
ENDPHASE
ENDRUN
Highway Program > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see Highway in Chapter 17, “Frequently Asked Questions.”
Intersection Modeling > Introduction to intersection modeling

Introduction to intersection modeling

This section provides an overview to intersection modeling. Topics include:
• Why use intersection modeling?

• How the intersection models work

• Limitations of intersection modeling

• Cube Voyager intersection modelling and other programs

• Methodology for U-Turns at Signalized Intersections

• Methodology for Free Right Turns at Signalized Intersections

Intersection Modeling > Introduction to intersection modeling > Why use intersection modeling?

Why use intersection modeling?

In a traditional capacity restrained transport planning model, the effects of congestion
are represented by link cost functions that assign costs to each link as a monotonic non-
decreasing function of the flow on that link. This form of model has a unique Wardrop
equilibrium solution. Furthermore, the Frank-Wolfe algorithm (invoked by default in Cube
Voyager) gives us a reasonably good solution algorithm. Thus later in the planning
process, when we wish to compare schemes, we can be sure that, provided both
models have been run to an adequate level of convergence, we have stable
comparable results. Furthermore we can achieve good convergence in reasonable time.
Models with separable costs and monotonic nondecreasing cost functions have been
very successful in modelling interurban travel. They have been applied to most kinds of
geographic region and most kinds of planning decision.
However, in congested urban environments, it can easily be observed that most of the
delay arises from the conflicts between streams at intersections. In such a situation, it
may be necessary to use nonseparable cost functions to achieve adequate
verisimilitude in the sensitivities of the costs to the flows. Furthermore, if the policy
responses being evaluated include traffic management measures (for example,
changing the form of control at key intersections) it must be possible to represent the
proposals in the model.
Intersection Modeling > Introduction to intersection modeling > How the intersection models work

How the intersection models work

Cube Voyager intersection modelling occurs during the ADJUST phase of a capacity
restrained assignment. Data from a file of “Junction Descriptions” is read to determine
the exact model form for each modelled node. When the costs arising from a flow
pattern are required, the flow pattern is passed to the intersection model. The model will
allocate the turning movements (which can be defined by the TURNS command) into
lane groups, with each lane group having a capacity. Note that the capacity of a lane
group will be reduced by any conflicting flows through the intersection. A delay function
is applied to calculate the average delay per vehicle for vehicles in the lane group.
These calculated delays are then applied as turn penalties in the next path build.
Intersection Modeling > Introduction to intersection modeling > Limitations of intersection modeling

Limitations of intersection modeling

As noted above, intersection modelling tends to make the overall network model less
stable. Consequently the assignment may take many more iterations to converge.
Indeed, using the default method of combination, the model may never reach adequate
levels of convergence. If necessary, you can change to using COMBINE=AVE to
guarantee eventual convergence.

NOTE: A global minimum capacity of 1 vehicle (or PCU) per hour is now enforced. A PCU
is similar to a vehicle but it is adjusted for vehicle length, so a car counts 1, a bus counts
2. Trucks vary between 1.5 (light van) and 2.5 (tractor-trailer).
Intersection Modeling > Introduction to intersection modeling > Cube Voyager intersection modelling and other programs

Cube Voyager intersection modelling and other

programs
This chapter describes only those junction description keywords that are directly
relevant to Cube Voyager intersection modelling. However there are several other
keywords permitted in an intersection description. Some of these extra keywords are
used by Cube graphics to assist in editing and display of intersections. Some of these
extra keywords are used to preserve data that is required or used by Cube Dynasim.
Intersection Modeling > Introduction to intersection modeling > Methodology for U-Turns at Signalized Intersections

Methodology for U-Turns at Signalized Intersections

The methodology for modeling U-turn is to compute a HCM like saturation flow
adjustment factor for U-turns and include it as a factor in the HCM computation for the U-
turn lane group (either shared or exclusive).
A shared u-turn movement is generally allowed from the left turn lane or from the left
most, left turn lane if the intersection has more than one left turn lane. A shared lane
here means that either movement (left or u-turn) may be made from the same lane.
Some intersections configurations also provide an exclusive u-turn lane in addition to
one or more exclusive left turn lanes. When a u-turn movement is allowed from a shared
left turn lane the increasing proportion of the u-turning flow can affect the overall capacity
of the movement. This reduction in capacity is estimated by applying an adjustment
factor.
The HCM determination of Saturation Flow Rate (S) is a function of a base flow rate
(generally assumed to be 1900 vph/ln) times the number of lanes and then factored by
various adjustment factors based on prevailing conditions at the approach under
consideration. The proposed methodology introduces an additional adjustment factor
specifically for a u-turn movement. A simplified formulation for saturation flow rate is:
where,
= base flow rate (assumed to be 1900 vph/ln)
= number of lanes for U-turn movement
= various adjustment factors based on prevailing conditions at the approach for U-
turn from HCM2000
= U-turn adjustment factor based on estimates from Carter, D. et al. TRR 1912,
2005.
= proportion of U-turn flow on the approach
Under protexted phasing:
Exclusive lane:
= 0.82 (no protected right turn overlap)
= 0.67 (protected right turn overlap)
Shared Lane:
protected right turn over lap otherwise

In implementation the user can provide the relationship between U-turn flow proportion
and U-turn Adjustment Factor based on their own observed data if available via a U-turn
 slope parameter such that:
Otherwise u-turn slope parameter would take on a default values base on
the relationships estimated by Carter, D et al.
The table below provides an example of the effects of increasing u-turn flow proportion
on the saturation flow rate of a shared left/u-turn lane. In this example we use the default
u-turn slope parameter of 0.18 and assume that there is no right turn overlap condition
(as that is likely to be the case for all intersections in the current Abu Dhabi network).
The proportion of u-turn flow is then the ratio of u-turn flow to approach flow, the u-turn
adjustment factor Fut = 1.0-0.18*Put and S = S 0*Fut and S 0=1900. When the u-turn
flow proportion is 1.0 the lane is effectively an exclusive u-turn lane with an adjustment
factor of 0.82.
Effect o f U-turn flo w o n lane Saturatio n Flo w Rate S

Le ft U -T urn A p p ro a c h
Flo w flo w flo w P ut F ut S

1000 0 1000 0.0000 1.0000 1900

900 100 1000 0.1000 0.9820 1866

800 200 1000 0.2000 0.9640 1832

700 300 1000 0.3000 0.9460 1797

600 400 1000 0.4000 0.9280 1763

500 500 1000 0.5000 0.9100 1729

400 600 1000 0.6000 0.8920 1695

300 700 1000 0.7000 0.8740 1661

200 800 1000 0.8000 0.8560 1626

100 900 1000 0.9000 0.8380 1592

0 1000 1000 1.0000 0.8200 1558

Intersection Modeling > Introduction to intersection modeling > Methodology for Free Right Turns at Signalized Intersections

Methodology for Free Right Turns at Signalized

Intersections
In general a free-right turn is a right turn movement at a controlled intersection whereby
the use of a slip lane or channel lane, the right turn movement can be made without
being subjected to the signal control - thus the term 'free' implying the movement is free
of the signal delay effects. In the ideal case a free-right turn lane configuration would
have adequate entry and exit lane lengths to minimize or eliminate delay associated with
accessing the entry lane or merging from the exit lane thus rendering the delay
associated with the movement negligible. In practice however, often this ideal case is not
the case and entry and exit lane lengths vary across a range from non-existent to the full
length of the block face. This is the case in the reality where the as built conditions can
vary widely from one intersection configuration to another. The methodology for
modeling free right turn is sensitive to this level of variability in as built conditions.
The flow capacity for the free right movement is determined by the limiting flow rate
between the entry/deceleration lane and the exit/acceleration lane. If through flow
queuing during the red phase blocks entrance to the deceleration lane this could be the
limiting flow rate for the free right movement. However, limits due to yielding and/or
merging due to conflicting traffic at the acceleration lane could also be the limiting flow
rate.
The flow capacity for the free right movement of a signalized intersection approach can
then be defined as:
where,
= capacity of a free right movement for an approach j at a signalized
intersection
= capacity based on entry into right turn deceleration lane during the
red time for approach j
= capacity based on exit from the right turn acceleration lane during the
red time for approach j during signal phase i
S = saturation flow for the free right movement during the green phase as defined
in HCM2000 equation 16-4
= green time at phase i
= green time for through movement at approach j (free right is protected)
= total green time for all signal phases at the intersection
Entry Capacity
The entry lane capacity can be affected by the signal cycle if the queue length of the
vehicles in the right most through lane during the red phase of the approach exceeds
the length of the deceleration or slip lane. This entry lane limiting blocking capacity is
based on the average maximum number of right lane vehicles served before through
traffic blocks the entry into the right turn pocket/channel and can be computed as:

where,
= number of vehicles (PCUs in STEAM model context) that can queue up in the
right most through lane before it blocks the entry into the right turn pocket/channel
(length of right turn storage bay in vehicles or distance from the stop line to the entry
point to the right turn channel in vehicles if no right turn storage bay). This parameter
value is computed from the user supplied length of the entry lane (Free Turn Entry
Length) in meters (or feet if US units) and the average queued vehicle density
(Queued Vehicle Spacing in meters/feet) specified by the users. Presence of some
positive value for Free Turn Entry Length triggers the free right turn model to be
applied for the right turn movement of the approach.
= right turn volume at approach j (vph)
= volume in the right most through lane at approach j (vph)

where,
= total volume in the through lane group at approach j (vph)
= total number of lanes in the through lane group at approach j (vph)
= lane utilization factor at approach j from HCM2000 exhibit 10-23
This entry capacity is independent of the presence multiple lanes for the free right
movement as it only depends on the through queue blocking entry.
Exit Capacity

A gap acceptance model for the determination of the flow rate at the exit would be
appropriate for the case with little or no acceleration lane however some adjustment
needs to be made to account for the length of the acceleration lane if one is present. As
the length of the exit/acceleration lane increases the less impact there is on the lanes
flow rate due to merging and lane changing with conflicting flow such that the flow rate
should approach the saturation flow rate s, as defined in HCM2000.
The exit lane capacity for approach j during signal phase i can be defined as:
If :
 else if :

Else
where,
= length in meters (or feet) of the right turn exit/acceleration lane. This parameter is
specified by the users. Measured from the first point a vehicle could enter the
conflicting traffic stream to the last point a vehicle could enter the conflicting traffic
stream.
= maximum exit lane length. Lane lengths at or greater than this value have no
effect on capacity. This defaults to 160m but can be overridden by the user.
= gap acceptance model based capacity computed as a signal time weighted
average capacity computed for each interval of the signal cycle during the red
phase for the approach. During the green phase of the approach the capacity is
assumed to be at saturation flow (1900vph). Functional form uses TWSC gap
acceptance model per HCM2000 equation 17-3 but with adjusted critical gap and
follow-up time parameters:

where,
= conflicting flow rate for the free right movement at approach j
= critical gap, i.e., the minimum time that allows vehicle for a free right movement.
It's a user-specified parameter with a default value of 4 seconds.
= follow-up time, i.e., the time between the departure of one vehicle from
approach and the departure of the next under a continuous queue condition. A
user-specified parameter with a default value of 2.5 seconds.
Given the default values of critical gap and follow-up time, the above relationship to
compute exit lane capacity based on a gap acceptance model adjusted for the length
of the exit lane is depicted in the figure below:
The upper limiting value of the capacity from the gap acceptance model
is the value computed as the conflicting flow approaches zero and is a
function of the assumed critical gap and follow up time parameters
used. Based on the default values for these parameters this upper
limiting value is 1440.
In cases where multiple lanes are present for the free right movement the number of
lanes is included in the computation for the exit saturation flow. However a reduction
factor should be applied similar to the method used for two lane entry to round about
circulation lanes.
Once the entry and exit capacities are determined, is determined and used to
 compute delay from a modified HCM Exhibit 17-38 formula as:

where,
= capacity of a free right movement for an approach j at a signalized
intersection
= analysis time period (h)
= right turn volume at approach j (vph)
Intersection Modeling > Control statements

Control statements
A junction file contains a sequence of statements, of which at most one is a UNITS
statement, and the remainder are JUNCTION statements.
This section describes:
• JUNCTION

• UNITS
Intersection Modeling > Control statements > JUNCTION

JUNCTION
Each JUNCTION statement, listed below, describes the control of some particular
intersection in the network. It follows the usual syntax for Cube Voyager script
statements. Comments, also following the usual Cube Voyager script syntax, are also
allowed in the file.
J U N CT ION s ta te me nt k e y wo rd o v e rv ie w

A ll- R o und a b o ut
wa y P rio rity P rio rity Ga p R o und a b o ut S ig na ls S ig na
Ke y wo rd S to p Ge o me tric S a tura tio n a c c e p ta nc e E mp iric a l Ge o me tric S a tur

ACTUALGREEN |R| v v

APPROACH |KIV10| v v v v v v v

APPROACH1 |KI| v v v v v v v

APPROACH-WIDTH |R| v

AVERAGELANE-WIDTH |R| v

BUSBLOCKAGE |RV2*| v

CANSHARE-LEFT |?| v v v

CANSHARE-RIGHT |?| v v v

CAPACITY-INTERCEPT |R| v

CAPACITY-SLOPE |R| v

CENTRAL-BUSINESS- |K?| v
DISTRICT

CENTRAL-RESERVATION- |KR| v
WIDTH

CRITICALGAP |R| v

CYCLETIME |KR| v v

ENTRYANGLE |R| v

ENTRYRADIUS |R| v

ENTRYWIDTH |R| v

ESTIMATED-DELAY |R| v v v v v v v

EXCLUSIVE-LANES |I| v v v

EXITONLY |?| v v v v v v v

FLARELENGTH |R| v

FOLLOWUP-TIME |R| v
FOURLANE-MAJOR |K?|

FREEFLOWCAP |R| x v x x x x x

FR E E T U R N E N T R Y |R| v v

FR E E T U R N E XIT |R| v v

FR E E T U R N FOLLOW U P |R| v v

FR E E T U R N GA P |R| v v

GRADE |R| v

H CMV E R S ION |I| v v v

INITIALQUEUE |R| v v v v v v v

INSCRIBED-DIAMETER |R| v

LANEADJUST |K?| v

MAJORROAD-WIDTH |KR| v

MINIMUM-CAPACITY |R| v v v v v v v

MOVEMENT |S| v v v v v v v

NODE |KI| v v v v v v v

NUMBEROF-LANES |I| v

PARKING-MANEUVERS |RV2*| v

PHASE |KI| v v

PHASES |I| v v

RANDOMNESS |R| v v v v v v v

SATFLOWPER-LANE |R| v v

SINGLELANE |?| minor v v v

only

STORAGESPACE |KR|

TURN-CHANNELIZED |?|

TYPE |KS| v v v v v v v

U T U R N CON T R OL |R| v v v v v v v

U T U R N S LOP E |R| v v v v v v v

V E H LE N GT H |R| v v

VISIBILITY |R| v

WIDTH |R| v

See the individual topics for descriptions of each keyword.

Intersection Modeling > Control statements > UNITS

UNITS
Defines units of measurement for junction geometry. Keywords and include:
• LE N GT H

This statement defines whether the lengths used to define junction geometry are
measured in feet or meters. The value of the Length may be either “feet” or “meters”
(case insensitive). At most one UNITS statement may appear in a junction file. If no UNITS
statement is found, measurements will be taken to be in meters.
The keywords, in the Junction statement, that have units of length are: AverageLaneWidth,
ApproachWidth, EntryWidth, EntryRadius , FlareLength, InscribedDiameter, Width, Visibility, MajorRoadWidth
and CentralReservationWidth.
Intersection Modeling > Control statements > UNITS > Example

Exam ple
UNITS LENGTH=FEET
UNITS LENGTH=METERS
Intersection Modeling > Common keywords

Common keywords
This section describes common keywords, applicable to multiple intersection types:
• APPROACH

• APPROACH1

• ENABLE

• ESTIMATEDDELAY

• EXITONLY

• HCMVERSION

• INITIALQUEUE

• MINIMUMCAPACITY

• MOVEMENT

• NODE

• RANDOMNESS

• TYPE

• U-TURN CONTROL

• U-TURN SLOPE
Intersection Modeling > Common keywords > APPROACH

APPROACH
The APPROACH keyword takes a list of integers as its value. It has two functions within the
junction description:
1. It begins a sequence of keywords which describe the specified approach. This sequence
continues until the next occurrence of Node, Type, LaneAdjust, CentralBusinessDistrict, CycleTime, Phase,
MajorRoadWidth, CentralReservationWidth, StorageSpace, FourLaneMajor, Approach1 , Approach, or the end of the
JUNCTION statement.

2. It describes how neighbors of the modeled node are grouped into approaches. The value
of the keyword is a list of node numbers of nodes adjacent to the node being modeled. The
grouping of neighboring nodes into a single approach may be necessary, for example,
because Cube Voyager can only model three- or four-legged intersections (although, at
roundabouts, this restriction may be overcome by modeling the circulating section
explicitly); because some of the neighbors are fictional (for example, zone centroid
connectors); or because the two lanes of a road are represented by individual links.

Every node, which is a neighbor of the modeled node, must appear in exactly one
Approach clause.
Cube Voyager requires that the legs of a junction can be assigned a clockwise ordering
by using the coordinates of the nodes involved. Any grouping of links into legs must not
invalidate the ordering. For example, in the diagram below, a is a modeled node. Any
valid approach which includes both nodes b and d must also include node c.
Intersection Modeling > Common keywords > APPROACH1

APPROACH1
Every junction description must contain exactly one occurrence of the integer-valued
keyword APPROACH1. Its value is the node number of a node adjacent to the modeled
node, Node. The approach containing the specified node, is taken to be the first
approach and the other approaches are numbered in relation to it.
By default, the approaches are numbered in anti-clockwise order, but if LEFTDRIVE = y is
in force, the approaches are numbered in clockwise order.
At two-way stop-controlled and priority (two-way yield-controlled) intersections, the first
and third approaches are major and the second and fourth (if any) approach are minor.
At three-legged intersections, the value of APPROACH1 determines which movements are
available from each approach:

Le ftD riv e =
n Le ftD riv e = y

First Approach Through Through

Right Left

Second Approach Right Left

Left Right

Third Approach Left Right

Through Through

At other modeled intersections, the choice of APPROACH1 is arbitrary with no modeling

consequences.
Intersection Modeling > Common keywords > ENABLE

ENABLE
Every junction description may contain at most one occurrence of the logical-valued
keyword ENABLE. If it has the value false, Cube Voyager will ignore the entire junction
description (that is, no intersection modeling will occur at the node).
ENABLE is a quick way of turning modeling on and off at a particular node from within the
junction file during model development. Modeling can also be turned on and off in the
Cube Voyager Highway script file using the N clause of the FILEI JUNCTIONI command.
Intersection Modeling > Common keywords > ESTIMATEDDELAY

ESTIMATEDDELAY
NOTE: Keywords are case insensitive. Capitalizing as EstimatedDelay might improve
readability.

This real valued keyword specifies the delays, in minutes per vehicle, to be used during
the first PATHLOAD command to be executed. This occurs prior to the first Adjust phase,
so no calculated values will be available yet. Once an Adjust phase has been executed,
calculated values will replace these initial estimates.
By default, a value of 0.0 minutes is used. However, in urban areas, this is a very poor
estimate and it is very desirable that better values be supplied.
An approach’s ESTIMATEDDELAY value is analogous to a link’s initial travel time. On the
assignment’s first iteration, no volumes exist yet to use for junction-delay calculations.
During the first iteration, this user-specified value provides an initial estimate of the
movement delay during path building.
Intersection Modeling > Common keywords > EXITONLY

EXITONLY
NOTE: Keywords are case-insensitive. Capitalizing as ExitOnly might improve readability.

For any “approach,” EXITONLY=y indicates that the leg is not an approach; it is an exit
only. No other keywords, except EXITLANES, may be coded for the approach.
The coding of EXITONLY must agree with the network (that is, the exit only approach must
correspond to a set of one-way links leading away from the modeled intersection).
Intersection Modeling > Common keywords > HCMVERSION

HCMVERSION
This keywoard signifies if the delay calculations should be based on HCM 2000 or HCM
2010. Valid values are either 2000 or 2010. Depending upon which type of delay
calculations the user wishes to use, the respective value will be used. For the new
calculators, it is set to 2010.
Intersection Modeling > Common keywords > INITIALQUEUE

INITIALQUEUE
NOTE: Keywords are case insensitive. Capitalizing as InitialQueue might improve
readability.

This is the number of vehicles (pcu) that are waiting to make the specified movement
from the specified approach at the beginning of the model period. It defaults to zero.
INITIALQUEUE is the queue at the start of the modeled period. INITIALQUEUE generates
additional delay after Cube Voyager assigns flows and calculates delay because the
vehicles arriving during the assignment must wait for the queue in front of them to
discharge before they reach the stop line (or give-way line). Consequently, if there is no
assignment (that is, just path building for skimming), INITIALQUEUE has no effect. Note
that the initial queue’s discharge rate is not a constant; the discharge rate depends on
the junction’s conflicting flows. Rather than being additional time added to the delay at
the end of the process, INITIALQUEUE is more like additional demand added to the
assigned demand prior to junction calculations. However, the delay to the vehicles in the
initial queue is not part of the results. The results only include the delay that these initially
queueing vehicles cause to the vehicles that arrive during the modeled period.
Intersection Modeling > Common keywords > MINIMUMCAPACITY

MINIMUMCAPACITY
The MINIMUMCAPACITY keyword takes a positive value in vehicles per hour as its
argument. It is coded by approach. If no value is coded, a default value of one vehicle
per hour is applied.
If the calculated capacity for any stream from an approach is less than the minimum
capacity value for that approach, the minimum capacity will be used instead of the
calculated value. This substitution occurs before any delay calculations are started.
The minimum capacity is most likely to apply when a movement is very lightly trafficked
but is very heavily opposed. In this circumstance, the delay for the lightly trafficked
movement will be close to 60/MinimumCapacity (that is, the default value leads to
delays being estimated as an hour).
The default minimum capacity of one vehicle per hour is sufficient to prevent division by
zero errors from crashing program execution but there are two arguments in favor of
applying a higher value:
1. Modeling expediency: If a minimum capacity of one vehicle per hour results in a predicted
delay of the order of an hour, trips will be diverted away from that turn during subsequent
iterations. So long as the turn has low traffic there is little reason for the turn model to
allocate capacity to that movement (especially at adaptive signal models where the signal
optimizer will be trying to allocate the available green time where the flow is heaviest).
Thus a positive feedback may occur between having low traffic on the turn and having high
delay on the turn.

2. Driver behavior: If conditions are very congested, drivers will no longer wait for an
appropriate gap in the opposing stream. Eventually, they will just force their way into a
smaller gap. This is especially true when the opposing stream is a slow moving queue.
Intersection Modeling > Common keywords > MOVEMENT

MOVEMENT
The MOVEMENT keyword takes one of three case-insensitive values:
• Left

• Right

• Through

Each occurrence begins a sequence of keywords which describe the specified

movement from the current approach. The sequence continues until the next
occurrence of APPROACHWIDTH, AVERAGELANEWIDTH, BUSBLOCKAGE, CAPACITYINTERCEPT,
CAPACITYSLOPE, ENTRYANGLE, ENTRYRADIUS, ENTRYWIDTH, EXITONLY, FLARELENGTH, GRADE,
INSCRIBEDDIAMETER, MINIMUMCAPACITY, MOVEMENT, NUMBEROFLANES,
PARKINGMANEUVERS, RANDOMNESS, SINGLELANE, TURNCHANNELIZED, FREEFLOWCAP, or the
end of the approach.
Care should be taken when coding CRITICALGAP and FOLLOWUPTIME which can occur as
keywords at both the approach and movement levels. When coding gap-acceptance
roundabouts, these two keywords should appear within each approach, before any
movements for that approach are described. When coding two-way stop-controlled
intersections, it will not usually be necessary to code CRITICALGAP or FOLLOWUPTIME, but
if they are coded they must be coded by movement.
Intersection Modeling > Common keywords > NODE

NODE
Every junction description must contain exactly one occurrence of the integer-valued
keyword NODE. Its value is the node number of the junction to be modeled.
Intersection Modeling > Common keywords > RANDOMNESS

RANDOMNESS
RANDOMNESS is a real-valued keyword which specifies how random the service times are
with respect to the arrival times. Its value must satisfy the inequality 0.0 < RANDOMNESS
<= 1.0. At geometrically modeled signals, the platoon ratio is estimated as 2(1.0 -
RANDOMNESS)

By default, RANDOMNESS is 0.55 for signalized intersections and 1.0 for unsignalized
intersections. These values are appropriate for isolated junctions (that is, arrivals are
random). The lower value for signals reflects that even if arrivals at a signal are random,
the service times depend on whether the arrival was at a green signal aspect or a red
one.
However, in urban areas where there are signal linkage effects, the appropriate
RANDOMNESS values are reduced. RANDOMNESS values of 0.1 or 0.2 are appropriate for
signals in advanced traffic management systems (for example, SCOOT, SCATS,
OPAC) or in offline signal plans at the time that they are installed. Unsignalized
intersections in this region should have RANDOMNESS values of the order 0.3 or 0.4.
Offline signal plans are generally not completely up to date so they are usually more
random than ATMS. Consequently, in areas where offline signal plans operate
RANDOMNESS values for signals should be 0.3 or 0.4; values of 0.6 to 0.8 are appropriate
for unsignalized intersections in these areas. When using “dummy links” to model
internal parts of a signal (such as modelling a five-armed signal as two nodes)
synchronization across the dummy link is perfect. Therefore, code very low values of
randomness, such as 0.01, for the relevant approaches.
Intersection Modeling > Common keywords > TYPE

TYPE
Every junction description must contain exactly one occurrence of the keyword TYPE. It
determines the type of junction to be modeled. Its value should be taken from the
following list:
• Roundabout

• Priority

• FixedTimeSignal

• Adaptive Signal

• TwoWayStop

• AllWayStop

The keywords are case insensitive; the capitalization in the list above is merely to
improve readability.
Note that the type field only distinguishes between different types of intersection on the
ground. When Cube Voyager offers more than one methodology for modeling a
particular kind of junction control, other keywords will be used to distinguish between
them:
• The presence or absence of CRITICALGAP and FOLLOWUPTIME (by approach) distinguishes
between gap-acceptance and empirical roundabout modeling

• The presence or absence of MAJORROADWIDTH distinguishes whether a priority junction uses

geometric modeling or measured saturation flows

• The value of LANEADJUST distinguishes whether a fixed time signal uses geometric modeling
or measured saturation flows

• The value of HCMVERSION determines teh delay calculation methodolgy to use. (only
applies to All-Way, Two-Way and Roundabouts)

The exception to the above rule is signals when there are several layers of choice of
modeling methodology. When observed base-year signal settings are available, use
TYPE=FixedTimeSignal to perform delay calculations for those settings. However, given a
feasible signal setting and a set of constraints, Cube Voyager can optimize the settings
for the forecast flows. This facility is invoked using TYPE=AdaptiveSignal. (Note that when
forecasting future years, adaptive modeling is always recommended; even if the signal
controller is fixed time, some traffic engineer will reset the signals every few years.)
The next level of modeling methodology chooses between calculating capacities using
supplied saturation flows or calculating them using the methodology described in HCM
2000, Chapter 16. The HCM methodology is invoked using the keyword LANEADJUST.
Both methodologies may be invoked either using supplied settings or adaptive green
time calculations. Note that the HCM methodology can model semi-actuated signal
controllers. Giving the keyword UnitExtension to a positive value for some approach
invokes this model. The issues of “adaptive settings” (that is, future or base year) and
“actuated controllers” (that is, hardware in the field) are independent of each other.
When HCM capacity calculations are executed, by default Cube Voyager also applies
the HCM delay calculations. However, for all other models, a delay equation formulated
by Ian Catling is used. If you code DELAYEQUATION=Catling you can force the use of
Catling’s delay formulation at an HCM signals.
Note that the type of control called a “priority junction” in the U.K. (where they are very
common) would be called a “two-way yield-controlled intersection” in the U.S. (where
stop-controlled intersections are the norm).
Intersection Modeling > Common keywords > U-TURN CONTROL

U-TURN CONTROL
U-turn control keyword specifies if the intersection has U-turn movement coded locally. It
has 3 check boxes at each approach to specify if U turns are allowed or banned, and if it
has an exclusive lane. If users check Allow only, it means that U-turn movement does
not have an exclusive lane but shared with the left most lane with the left turn lane(s).
Allow and Ban cannot be checked together. If they are both unchecked, then it means it
will be controlled by the keyword set in Voyager (Allo wAllUTurns) . If any of the three boxes
are checked, it means that this intersection node has local settings. See
PARAMETERS.
Intersection Modeling > Common keywords > U-TURN SLOPE

U-TURN SLOPE
This keyword is the U turn saturation flow reduction factor value. If specified, it will
override the global default setting, regardless of the turn overlap condition. The valid
range for this key word is [0.01, 0.66]. The Intersection Data Editor only takes values
with 2 decimal places. If provided with more than 2 decimal places, the values will be
rounded up with 2 decimal places. There is a file default specified for the whole junction
data file (See Data file settings) option for No Turn Overlap and With Turn Overlap
condition. If not specified in the File Settings, it will default to 0.18 and 0.33 for no overlap
and with overlap. The overlap condition is determined by the software automatically from
the phase setting. See Methodology for U-Turns at Signalized Intersections.
Intersection Modeling > Signal-controlled intersections

Signal-controlled intersections
This section describes signal controls. Topics include:
• Overview of signals

• Generic keywords

• Geometric keywords

• Geometric signals example

• Saturation flow signals example

Intersection Modeling > Signal-controlled intersections > Overview of signals

Overview of signals
Signalized intersections are controlled by sets of traffic lights. At any given time, vehicles
making a particular movement through the intersection will see a particular signal
aspect:
• In the U.K., red, green, amber, red amber, flashing amber.

• In the U.S., green, yellow, red, green.

Modelers reclassify the aspect into effective green (when the traffic can go) and effective
red (when the traffic stops). Note that effective green begins and ends later than actual
green (due to reaction times).
A set of signal aspects for all movements through an intersection is called a phase. Note
that the total duration of all the phases should be significantly less than the duration of
the signal cycle. The difference is primarily due to two factors: lost time while the signals
are changing phase and pedestrian phases.
Cube Voyager offers two ways of modeling the capacity of signals. There is a detailed
model of junction geometry, which has been calibrated to traffic conditions in the U.S.
(Geometric / HCM model), and there is a model which requires saturation flows to be
estimated or measured externally, which has been calibrated to traffic conditions in the
U.K.(Saturation Flow model). The detailed model also imposes more constraints on the
allowed signal phasing than the saturation flow only model.
Cube Voyager offers four signal intersection types, i.e. signal saturation flows, signal
geometric (HCM), adaptive signal saturation flows, and adaptive signal geometric
(HCM).
• S ig na l, S a tura tio n Flo ws mo d e l :
It is developed to model capacities, queues, delays and LOS at
fixed time signal controlled isolated intersections. The user inputs include geometric
characteristics of the intersection, signal timing arrangements, and demand flow
information. The methodology is based on the Catling's delay method and the TRRL
(Transport and Road Research Laboratory, UK) Report 105.

• S ig na l, Ge o me tric (H CM) mo d e l :
It addresses the capacities, queues, delays and LOS for lane
groups and the LOS for intersection approaches and the intersection as a whole at
signalized intersections. Each lane group is analyzed separately in the HCM model. It
considers a wide variety of prevailing conditions, including the amount and distribution of
traffic movements, traffic composition, geometric characteristics, and details of intersection
signalization. The methodology is based on the HCM 2000 signal model.

• A d a p tiv e S ig na l, S a tura tio n Flo ws mo d e l :

It is an advanced model based on the Signal,
Saturation Flows model. The model optimizes the signal timing based on the intersection
geometric characteristics, signal parameter bounders and demand flow information. The
 methodology tries to iteratively fit delay parabolas based on three distinct and reasonable
signal timing plans, i.e. phase timings and cycle time, and picks the plan at the minimum
delay point, until no delay reduction could be reached. The delay is calculated by the
Catling's delay method. The methodology was inspired by the TRANSYT model.

• A d a p tiv e S ig na l, Ge o me tric (H CM) mo d e l :

The model is similar as the Adaptive Signal,
Saturation Flows model, except the delay is calculated by the HCM 2000 method.

The above intersection types output not only delay, capacity, queue and LOS, but also
low flow delay. The low flow delay is a measure commonly used by European users. It is
the additional travel time experienced by drivers of each movement at low degree of
saturation (flow to capacity ratio << 1). According to Catling's delay method, the delay at
low degree of saturation is almost equal to that occurring when the traffic intensity is
uniform. The low flow delay is calculated as the inverse of the capacity for Saturation
Flows models, and is calculated as the half cycle time times the square of the red time
proportion for Geometric (HCM) models.
A left turn (right turn when LEFTDRIVE=T) which sees a green phase will either be
protected (that is, no opposing flow is running) or permitted (that is, the vehicles must
give way to some oncoming traffic). Both methodologies can model both permitted and
protected phases.
Cube Voyager does not offer any model of “right turn on red” although this is allowed in
many areas of the U.S. (The LEFTDRIVE=T equivalent, “left turn on red,” is not permitted
in the U.K.) This is best handled by introducing a dummy link into the network, allowing
the right-turners to bypass the signal control, and omitting some lane(s) from the
definition of the approach.
References

• Catling, I. (1977). A time-dependent approach to junction delays. Traffic Engineering and

Control, 18(11), pp. 520-523, 526.

• Kimber, R. M., Mcdonald, M., Hounsell, N. B. (1986). The prediction of saturation flows for
single road junctions controlled by traffic signals. Transport and Road Research
Laboratory Report RR 67.

• Burrow, I. J. (1987). OSCADY: a computer program to model capacities, queues and

delays at isolated traffic signal junctions. Transport and Road Research Laboratory Report
RR 105.

• Kimber, R.M. and M.C. Semmens (1983). Traffic signal junctions: a track appraisal of
conventional and novel design. Transport and Road Research Laboratory Report RL 1063.

• Transport Research Laboratory. TRANSYT. http://www.trl.co.uk/Transyt.htm

• Transportation Research Board. Highway Capacity Manual 2000.

Intersection Modeling > Signal-controlled intersections > Generic keywords

Generic keywords
This section describes generic keywords used for signals:
• CANSHARELEFT

• CANSHARERIGHT

• CYCLETIME

• EXCLUSIVELANES

• LANEADJUST

• PHASE and ACTUALGREEN

• PHASES

• SATFLOWPERLANE

• SINGLELANE
Intersection Modeling > Signal-controlled intersections > Generic keywords > CANSHARELEFT

CAN SHARELEFT
NOTE: Keywords are case insensitive. Capitalizing as CanShareLeft might improve
readability.

This keyword specifies that there is a shared lane to the left of the exclusive lanes for
this movement (that is, the movement can share with the movement to its left). Note that
this keyword does not mean “can share with left turners” unless either the movement is
THROUGH or the movement is on the minor leg of a three-arm junction.

If a movement has CANSHARELEFT = T coded, then there must be a movement to this

movement’s left and the movement to this movement’s left must have CANSHARERIGHT =
T coded.
If SINGLELANE = T then CANSHARELEFT should not be coded.
Intersection Modeling > Signal-controlled intersections > Generic keywords > CANSHARERIGHT

CAN SHARERIGHT
NOTE: Keywords are case insensitive. Capitalizing as CanShareRight might improve
readability.

This keyword specifies that there is a shared lane to the right of the exclusive lanes for
this movement (that is, the movement can share with the movement to its right). Note
that this keyword does not mean “can share with right turners” unless either the
movement is THROUGH or the movement is on the minor leg of a three-arm junction.
If a movement has CANSHARERIGHT = T coded, then there must be a movement to this
movement’s right, and the movement to this movement’s right must have CANSHARELEFT
= T coded.
If SINGLELANE = T then CANSHARERIGHT should not be coded.
Intersection Modeling > Signal-controlled intersections > Generic keywords > CYCLETIME

CYCLET IME
NOTE: Keywords are case insensitive. Capitalizing as CycleTime might improve readability.

This real-valued keyword is required for all signals. Its value is the length of the signal
cycle in seconds.
The cycle time must be strictly greater than the sum of all the coded green times.
At actuated signals, the CYCLETIME value is taken to be part of the example feasible
solution and the subkeywords MAXIMUM and MINIMUM may be used to supply
constraints. For example:
Actual Cycle = 120, Minimum = 60, Maximimum=180,
If no constraints are placed on the cycle time at an adaptively modeled signal, the
constraints will be deduced from the constraints on the individual green times.
Intersection Modeling > Signal-controlled intersections > Generic keywords > EXCLUSIVELANES

EX CLUSIVELAN ES
NOTE: Keywords are case insensitive. Capitalizing as ExclusiveLanes might improve
readability.

This integer-valued keyword gives the number of lanes, on the specified approach,
which are reserved for the exclusive use of vehicles making the specified movement.
If SINGLELANE = T, then EXCLUSIVELANES should not be coded.
Intersection Modeling > Signal-controlled intersections > Generic keywords > LANEADJUST

LAN EADJUST
NOTE: Keywords are case insensitive. Capitalizing as LaneAdjust might improve readability.

Set LANEADJUST to Y at a signal to invoke the HCM2000 capacity calculations.

Set LANEADJUST to N at a signal if you are supplying saturation flows.
Intersection Modeling > Signal-controlled intersections > Generic keywords > PHASE and ACTUALGREEN

PHASE and ACT UALGREEN

These keywords occur in pairs; every occurrence of the integer-valued keyword, PHASE
must be followed by a single occurrence of the real-valued keyword ACTUALGREEN.
There should be one such pair for each phase of the signals during which vehicles
move (that is, all-red and/or pedestrian phases should not be coded).
The values of the PHASE keyword should form a continuous sequence, starting at one
and increasing, without gaps, until the number of phases is reached. Every phase must
be mentioned in a PHASE keyword for some movement at the intersection.
The value of the ACTUALGREEN keyword is the duration, in seconds, of the effective
green-time associated with the phase. The effective green time is the period during
which vehicles move across the stop line. It starts shortly after the signals change to
green (because the vehicle drivers must react to the change in signal aspect) and
continues through the following red/yellow. The CYCLETIME must greater than the
summation of the ACTUALGREEN.
If the signal is being modeled adaptively, then the keywords maximum (required) and
minimum (optional) may be used to specify constraints, and the coded value of
ACTUALGREEN is taken to be part of the example feasible solution. If no minimum is
applied, Cube Voyager may remove the phase altogether (that is, set green-time to
zero).
Intersection Modeling > Signal-controlled intersections > Generic keywords > PHASES

PHASES
The keyword PHASES is integer-valued but, conceptually, it consist of either one phase
number (that is, digit) or of two phase numbers (that is, two digits). The vehicles making
the movement see a green signal aspect when the specified phase(s) is/are running
and red otherwise.
Note that the (node-level) keyword PHASE is used to define phases and the (movement-
level) keyword PHASES associates movements with the defined phases.
At geometrically specified signals, then any two-digit phase specifications must specify
contiguous phases. No such restriction is required when saturation flows are coded.
Intersection Modeling > Signal-controlled intersections > Generic keywords > SATFLOWPERLANE

SAT FLOWPERLAN E
NOTE: Keywords are case insensitive. Capitalizing as SatFlowPerLane might improve
readability.

This real-valued keyword allows the specification of saturation flows in pcu (vehicles)
per hour per lane.
Saturation flows at signals are the flows that would be observed if the movement had a
continuous green all other movements had no flow and no green.
Saturation flow at a priority junction (two-way yield-controlled intersection) is defined
similarly, except that no signal aspects are involved. SATFLOWPERLANE is only applicable
to Saturation flow model. The suggested value is 1700 pcu/h for THEOUGH and
UNOPPOSED movements and 1279 pcu/h for OPPOSED movements.
Intersection Modeling > Signal-controlled intersections > Generic keywords > SINGLELANE

SIN GLELAN E
NOTE: Keywords are case-insensitive. Capitalizing as SingleLane might improve readability.

The logical-valued keyword is used to indicate that an approach consists of a single

lane. It is applicable to many junction types:

J unc tio n ty p e Use

Signal-controlled Geometric SINGLELANE may be

intersection Data coded

Saturation SINGLELANE may be

Flows coded

All-way stop- SINGLELANE may not be

controlled intersection coded;
code NUMBEROFLANES
=1

Two-way stop- SINGLELANE may be

controlled intersection coded for minor road
Use FOURLANEMAJOR
to describe major road

Priority intersection Geometric SINGLELANE may be

(two-way yield- Data coded for minor arms
controlled Major road width in
intersection) meters, not lanes

Saturation SINGLELANE may be

Flows coded

Roundabout Empirical SINGLELANE may not be

coded

Gap SINGLELANE may not be

Acceptance coded

Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES,

CANSHARERIGHT, or CANSHARELEFT on that approach.

At two-way stop-controlled intersections and priority junctions, a minor arm that does not
have SINGLELANE = Y explicitly coded, has two lanes.
Intersection Modeling > Signal-controlled intersections > Geometric keywords

Geometric keywords
This section describes geometric keywords:
• AVERAGELANEWIDTH

• CONFLICTINGBIKE

• BUSBLOCKAGE

• CENTRALBUSINESSDISTRICT

• DELAYEQUATION

• EXITLANES

• FREEENTRYLENGTH

• FREETURNEXITLENGTH

• FREETURNFOLLOWUP

• FREETURNGAP

• GRADE

• NODEFACTOUNOPPOSE

• NODEFACTOOPPOSE

• PARKINGMANEUVERS

• PEDESTRIANFLOW

• PEDESTRIANPHASE

• PHASES

• UNITEXTENSION

• VEHICLELENGTH
Intersection Modeling > Signal-controlled intersections > Geometric keywords > AVERAGELANEWIDTH

AVERAGELAN EWIDT H
NOTE: Keywords are case insensitive. Capitalizing as AverageLaneWidth might improve
readability.

This real-valued keyword describes the mean lane width, in meters or feet, of an
approach to a geometrically modeled signalized junction. If no value is provided, a
default of 3.6m is used.
The average lane width must be in the range from 2.4m to 4.8m. If the value falls outside
this range, the approach should be recoded to have more or fewer lanes, as appropriate.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > CONFLICTINGBIKE

CON FLICT IN GBIKE

NOTE: Keywords are case insensitive. Capitalizing as ConflictingBike might improve
readability.

The flow of bicycles in from the curb-side lane in units of bicycles per hour. Bicycle traffic
which weaves with turning traffic in advance of the stop line should be excluded from this
value, because these bicycles do not interact with the other vehicles while they are still
within the intersection.
The diagram below illustrates the relevant bicycle flow for right hand rule of the road. In
the diagram, the crossed box is the bicycle conflict zone where right turning traffic may
be impeded by any bicycles crossing the intersection. The CONFLICTINGBIKE is the flow
of bicycles through this region.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > BUSBLOCKAGE

BUSBLOCKAGE
NOTE: Keywords are case insensitive. Capitalizing as BusBlockage might improve
readability.

The real values supplied to this keyword are number of buses stopping per hour. The
first element refers to the normal curb side of the road; the second refers to the other
side of the road (for example, if there is a tram line in the center of the road or there is a
bus stop on the offside of a one-way street). Only buses stopping within 75 meters (246
feet) of the stop line (either upstream or downstream) should be included.
This keyword is only applicable at geometrically modeled signals.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > CENTRALBUSINESSDISTRICT

CEN T RALBUSIN ESSDIST RICT

NOTE: Keywords are case insensitive. Capitalizing as CentralBusinessDistrict might improve
readability. You can also use the abbreviation, CBD.

CENTRALBUSINESSDISTRICT is a logical-valued keyword which may be applied at

geometrically-modeled fixed-time signals. Coding CENTRALBUSINESSDISTRICT=Y causes all
calculated capacities to be 90% of the value that would be obtained otherwise.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > DELAYEQUATION

DELAYEQUAT ION
Selects the delay modeling methodology applied to the capacities calculated by the
HCM2000 signal capacity modeling methodology. The keyword accepts the values
“HCM” or “Catling” (case-insensitive). By default, The HCM delay equations are
invoked.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > EXITLANES

EX IT LAN ES
The number of lanes traveling away from the modeled intersection.
This key may occur on the same arm as the EXITONLY keyword but is invalid for a one-
way link that travels towards the intersection.
Cube Voyager only uses this value for pedestrian and bicycle modeling.

NOTE: If exit lanes

are omitted from an arm that pedestrians cross, the capacity of
movements entering the arm may be reduced significantly.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > FREEENTRYLENGTH

FREEEN T RYLEN GT H
This keyword defines the length in the entry leg measured from the stop line to the
earliest point when a free turn vehicle can enter the free turn pocket or channel in the
current unit (meter or feet. See Data file settings). If this value is greater than zero and
the turn is coded as exclusive, then it is considered a free turn. Default to 0 for not a free
turn. The Intersection Data Editor only takes values with 2 decimal places. If provided
with more than 2 decimal places, the values will be rounded up with 2 decimal places.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > FREETURNEXITLENGTH

FREET URN EX IT LEN GT H

This keyword defines the length in the exit leg measured from the earliest point to the
latest point a free turn vehicle can merge into the main flow of traffic in the current unit
(meter or feet). It only becomes effective when calculating the statistics for free right-turn
movements. It can be 0 for no merging lane, similar to a yield situation and it is default to
0. The Intersection Data Editor only takes values with 2 decimal places. If provided with
more than 2 decimal places, the values will be rounded up with 2 decimal places. If this
value is equal to or greater than the Free Turn Exit Lane Max Length value in the
Intersection File Settings screen (See Data file settings), then it is assumed that no
merging is needed or no impact on the free turn capacity.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > FREETURNFOLLOWUP

FREET URN FOLLOWUP

Free turn followup time in seconds. It only becomes effective when calculating the
statistics for free right-turn movements. It will default to the Intersection File Setting. If not
specified in file setting, default to 2.5 seconds. The Intersection Data Editor only takes
values with 2 decimal places. If provided with more than 2 decimal places, the values will
be rounded up with 2 decimal places.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > FREETURNGAP

FREET URN GAP

This keyword defines free turn critical gap in seconds. It only becomes effective when
calculating the statistics for free right-turn movements. It will default to the Intersection
File Setting (See Data file settings). If not specified in file setting, default to 4 seconds.
The Intersection Data Editor only takes values with 2 decimal places. If provided with
more than 2 decimal places, the values will be rounded up with 2 decimal places.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > GRADE

GRADE
The real-valued keyword GRADE describes the grade, expressed as a percentage, of an
approach to a geometrically modeled signals or a two-way stop-controlled intersection. It
is a signed value; negative values indicate that the approach is downhill and positive
values indicate that the approach is uphill.
By default the approach is assumed to be flat (GRADE = 0).
The models have been calibrated for grades the range -6% to +11%, but more extreme
grades do occur. For example the maximum grade in San Francisco is about 31%.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > NODEFACTOUNOPPOSE

N ODEFACT OUN OPPOSE

Option to stop the de-facto exclusive turn lane check on the unopposed turning
movement (right turn on right drive and left turn on left drive). This is a boolean keyword.
Setting this option to True will disable the check for exclusive turn lane modeling when
volumes exceed threshold. This setting is used to control the lane grouping for turn
movements.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > NODEFACTOOPPOSE

N ODEFACT OOPPOSE
Option to stop the de-facto exclusive turn lane check on the opposed turning movement
(left turn on right drive and right turn on left drive). This is a boolean keyword. Setting this
option to True will disable the check for exclusive turn lane modeling when volumes
exceed threshold. This setting is used to control the lane grouping for turn movements.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > PARKINGMANEUVERS

PARKIN GMAN EUVERS

NOTE: Keywords are case insensitive. Capitalizing as ParkingManeuvers might improve
readability.

The real values supplied to this keyword are number of maneuvers per hour. The first
element refers to the normal curb side of the road; the second refers to the other side of
the road (that is, if there is parking in a central reservation or on the offside of a one way
street). Only parking within 80 meters of the stop line should be included
By default, parking is not allowed. Coding PARKINGMANUEVERS = 0 means that parking is
allowed, but it is extremely rare.
This keyword is only applicable at geometrically modeled signals.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > PEDESTRIANFLOW

PEDEST RIAN FLOW

The number of pedestrians crossing the approach per hour. Note that this is a two-way
flow.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > PEDESTRIANPHASE

PEDEST RIAN PHASE

The keyword PEDESTRIANPHASE is integer-valued but, conceptually, it consist of either
one phase number (that is, digit) or of two phase numbers (that is, two digits). In this
respect, it is like the keyword PHASES. The phases mentioned are the phases when
pedestrians crossing the approach are given permission to use the crosswalk. The
symbols displayed to the pedestrians vary by country, for example in the U.S. the word
WALK or an icon of a man walking is displayed in white whereas in the U.K. an icon of a
man walking is displayed in green.
If using a two-digit number, the two phases must be adjacent.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > PHASES

PHASES
The keyword PHASES is integer-valued but, conceptually, it consist of either one phase
number (that is, one digit) or of two phase numbers (that is, two digits). The vehicles
making the movement see a green signal aspect when the specified phase(s) is/are
running and red otherwise.
Note that the (node-level) keyword PHASE is used to define phases and the (movement-
level) keyword PHASES associates movements with the defined phases.
At geometrically specified signals, any two-digit phase specifications must specify
contiguous phases. No such restriction is required when coding saturation flows.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > UNITEXTENSION

UN IT EX T EN SION
The minimum gap, in seconds, between successive vehicles moving on a traffic-
actuated approach to a signalized intersection that will cause the signal controller to
terminate the green display.
Intersection Modeling > Signal-controlled intersections > Geometric keywords > VEHICLELENGTH

VEHICLELEN GT H
This keyword defines queued vehicle spacing on the adjacent through lane in meter or
feet depending on the unit setting of the file. It only becomes effective when calculating
the statistics for free right-turn movements. It will default to the Intersection File Setting
(See Data file settings). If not specified in file setting, default to 6 meters. The
Intersection Data Editor only takes values with 2 decimal places. If provided with more
than 2 decimal places, the values will be rounded up with 2 decimal places.
Intersection Modeling > Signal-controlled intersections > Geometric signals example

Geometric signals example

Cube Voyager does not contain a model for right turn on red. The right filter phase
coded below might be used as a proxy for RTOR when the right turns are heavy.
Junction,
Node = 276,
laneadjust=t,
Type = FixedTimeSignal,
Approach1 = 291,
CycleTime = 90,
Phase = 1,
ActualGreen = 59,
Phase = 2,
ActualGreen = 5,
Phase = 3,
ActualGreen = 11,
Approach = 291,
AverageLaneWidth = 3.6,
minimumcapacity=50,
Movement = Left,
ExclusiveLanes = 1,
EstimatedDelay = 0.1,
Phases = 1,
Movement = Through,
EstimatedDelay = 0.1,
ExclusiveLanes = 1,
Phases = 1,
Movement = Right,
ExclusiveLanes = 1,
EstimatedDelay = 0.1,
Phases = 12,
Approach = 264,
AverageLaneWidth = 3.6,
minimumcapacity=50,
Movement = Left,
EstimatedDelay = 0.3,
ExclusiveLanes = 1,
Phases = 3,
Movement = Through,
EstimatedDelay = 0.3,
Phases = 3,
ExclusiveLanes = 1,
Movement = Right,
EstimatedDelay = 0.3,
ExclusiveLanes = 1,
Phases = 32,
Approach = 267,
AverageLaneWidth = 3.6,
minimumcapacity=50,
Movement = Left,
ExclusiveLanes = 1,
EstimatedDelay = 0.1,
Phases = 1,
 Movement = Through,
EstimatedDelay = 0.1,
ExclusiveLanes = 1,
Phases = 1,
Movement = Right,
ExclusiveLanes = 1,
EstimatedDelay = 0.2,
Phases = 12,
Approach = 306,
AverageLaneWidth = 3.6,
Movement = Left,
EstimatedDelay = 0.2,
ExclusiveLanes = 1,
Phases = 3,
Movement = Through,
EstimatedDelay = 0.2,
Phases = 3,
ExclusiveLanes = 1,
Movement = Right,
EstimatedDelay = 0.2,
ExclusiveLanes = 1,
Phases = 32
Intersection Modeling > Signal-controlled intersections > Saturation flow signals example

Saturation flow signals example

This example illustrates the coding of fixed-time signals:
Junction,
Node = 276,
Type = FixedTimeSignal,
Approach1 = 291,
CycleTime = 90,
Phase = 1,
ActualGreen = 59,
Phase = 2,
ActualGreen = 5,
Phase = 3,
ActualGreen = 11,
Approach = 291,
Movement = Left,
CanShareRight=y,
EstimatedDelay = 0.1,
Phases = 1,
Movement = Through,
CanShareLeft=y,
EstimatedDelay = 0.1,
ExclusiveLanes = 1,
Phases = 1,
Movement = Right,
ExclusiveLanes = 1,
EstimatedDelay = 0.1,
Phases = 2,
Approach = 264,
Movement = Left,
EstimatedDelay = 0.3,
CanShareRight=y,
Phases = 3,
Movement = Through,
EstimatedDelay = 0.3,
CanShareLeft=y,
Phases = 3,
ExclusiveLanes = 1,
Movement = Right,
EstimatedDelay = 0.3,
ExclusiveLanes = 1,
Phases = 23,
Approach = 267,
Movement = Left,
CanShareRight=y,
EstimatedDelay = 0.1,
Phases = 1,
Movement = Through,
CanShareLeft=y,
EstimatedDelay = 0.1,
ExclusiveLanes = 1,
Phases = 1,
Movement = Right,
 ExclusiveLanes = 1,
EstimatedDelay = 0.2,
Phases = 2,
Approach = 306,
Movement = Left,
EstimatedDelay = 0.2,
CanShareRight=y,
Phases = 3,
Movement = Through,
EstimatedDelay = 0.2,
CanShareLeft=y,
Phases = 3,
ExclusiveLanes = 1,
Movement = Right,
EstimatedDelay = 0.2,
ExclusiveLanes = 1,
Phases = 23
Intersection Modeling > Two-way stop-controlled intersections

Two-way stop-controlled intersections

This section describes two-way stop-controlled intersections. Topics include:
• Overview

• Keywords

• Example
Intersection Modeling > Two-way stop-controlled intersections > Overview

Overview
The two-way-stop-controlled (HCM 2000/2010) model offered by Cube Voyager is a
gap-acceptance model calibrated against traffic conditions in USA. Users in other
countries may need to adjust the base critical gap and base follow-up time to reflect local
conditions. The method is designed for steady-state conditions, i.e. the demand and
capacity conditions are constant during the analysis period. The model can be used to
analyze the capacity, delay, queue and LOS of two-way-stop-controlled (TWSC)
intersections. The low flow delay is the inverse of the capacity for TWSC intersections.

The capacity model, which has been implemented in Cube Voyager, is a gap-
acceptance model that has been calibrated against traffic conditions in the USA. Users
in other countries may need to adjust the base critical gap and base follow up time to
reflect local conditions.
If there is a central reservation, or there are islands, between the lanes of the major road,
minor road traffic, which crosses the major road, may do so in two stages. First the
vehicle crosses to the central reservation; then it completes its movement through the
intersection. This situation is enabled when a non-zero value of storage space is coded.
The value is the number of vehicles which can wait in the center of the major road
without obstructing major road flows.
References

• Brilon, W., and M. Großmann. Aktualisiertes Berechnungsverfahren für Knotenpunkte ohne

Lichtsignalanlagen. Forschung Strassenbau und Strassenverkehrstechnik, Heft 596, 1991.

• Transportation Research Board. Highway Capacity Manual 2000.

• Transportation Research Board. Highway Capacity Manual 2010.

Intersection Modeling > Two-way stop-controlled intersections > Keywords

Keywords
This section describes the keywords for two-way stop-controlled intersections:
• CRITICALGAP

• FLARESTORAGE

• FOLLOWUPTIME

• FOURLANEMAJOR

• FREEFLOWCAP

• GRADE

• PEDESTRIANFLOW

• PEDESTRIANSPEED

• SINGLELANE

• SIXLANEMAJOR

• STORAGESPACE

• TURNCHANNELIZED
Intersection Modeling > Two-way stop-controlled intersections > Keywords > CRITICALGAP

CRIT ICALGAP
NOTE: Keywords are case insensitive. Capitalizing as CriticalGap might improve readability.

The critical gap, in seconds, is one of the parameters of any gap-acceptance capacity
model. At two-way stop-controlled intersections, it is applicable by movement. It is
defined as the minimum time interval in a higher priority stream that allows intersection
entry for one vehicle. Note that the coded value is the base critical gap. It is modified to
allow for junction geometry.
The default value depends on the movement:
B a s e c ritic a l g a p (s e c o nd s )

V e hic le T wo -La ne Ma jo r Fo ur-La ne Ma jo r

Mo v e me nt S tre e t S tre e t

Left turn from 4.1 4.1

major

Right turn from 6.2 6.9

minor

Through traffic 6.5 6.5

on minor

Left turn from 7.1 7.5

minor

Normally this value is allowed to default; only code when there are observations
indicating site-specific driver behavior at the intersection
Intersection Modeling > Two-way stop-controlled intersections > Keywords > FLARESTORAGE

FLAREST ORAGE
The number of vehicles that may queue in the flared region of a minor approach without
disrupting the flowing or queueing of traffic in the main lane.
By default this value is zero, that is, no or negligible flare.
Intersection Modeling > Two-way stop-controlled intersections > Keywords > FOLLOWUPTIME

FOLLOWUPT IME
NOTE: Keywords are case insensitive. Capitalizing as FollowUpTime might improve
readability.

The follow-up time, in seconds, is one of the parameters of any gap-acceptance

capacity model. At two-way stop-controlled intersections, it is applicable by movement. It
is defined as the time between the departure of one vehicle the next using the same gap
in a higher priority stream, under a condition of continuous queuing on the entry.
The default value depends on the movement:

B a s e Fo llo w-U p T ime

V e hic le Mo v e me nt (s e c o nd s )

Left turn from major 2.2

Right turn from minor 3.3

Through traffic on minor 4.0

Left turn from minor 3.5

Normally this value is allowed to default; only code when there are observations
indicating site-specific driver behavior at the intersection
Intersection Modeling > Two-way stop-controlled intersections > Keywords > FOURLANEMAJOR

FOURLAN EMAJOR
NOTE: Keywords are case insensitive. Capitalizing as FourLaneMajor might improve
readability.

This logical-valued keyword determines the number of lanes on the major road of a two-
way stop-controlled intersection. If FourLaneMajor = y is coded, then the major road has
two lanes in each direction (total four); otherwise the major road has one lane in each
direction (total 2).
Intersection Modeling > Two-way stop-controlled intersections > Keywords > FREEFLOWCAP

FREEFLOWCAP
NOTE: Keywords are case insensitive. Capitalizing as FreeFlowCap might improve
readability.

This value is only relevant for major approaches where FOURLANEMAJOR is false. It is the
capacity for the unmodelled movements from the arm. By default, these movements
have infinite capacity, which, when combined with the capacity of the modelled turn,
gives strange large capacities in the results. If you code a sensible value (such as 1800
vph), the resulting capacity will be reduced, but there will be a corresponding increase in
delays.
Intersection Modeling > Two-way stop-controlled intersections > Keywords > GRADE

GRADE
The real-valued keyword GRADE describes the grade, expressed as a percentage, of an
approach to a geometrically modeled signals or a two-way stop-controlled intersection. It
is a signed value; negative values indicate that the approach is downhill and positive
values indicate that the approach is uphill.
By default the approach is assumed to be flat (GRADE = 0).

The models have been calibrated for grades the range -6% to +11%, but more extreme
grades do occur. For example the maximum grade in San Francisco is about 31%.
Intersection Modeling > Two-way stop-controlled intersections > Keywords > PEDESTRIANFLOW

PEDEST RIAN FLOW

The number of pedestrian platoons crossing the approach per hour.
Pedestrians may cross the road singly, or they may cross in groups, two or three
abreast. Each such group counts as one pedestrian platoon. For more details of
pedestrian platoons refer to:
• If using HCM 2000 methodology - refer to Equation 18-18 of HCM 2000 manual.

• If using HCM 2010 methodology - refer to Equation 19-70 of HCM manual.

Intersection Modeling > Two-way stop-controlled intersections > Keywords > PEDESTRIANSPEED

PEDEST RIAN SPEED

The average speed at which pedestrians cross the approach in feet or meters per
second. By default this value is 1.2 meters or, equivalently, 4 feet per second.
Intersection Modeling > Two-way stop-controlled intersections > Keywords > SINGLELANE

SIN GLELAN E
NOTE: Keywords are case insensitive. Capitalizing as SingleLane might improve readability.

The logical-valued keyword is used to indicate that an approach consists of a single

lane. It is applicable to many junction types:

J unc tio n ty p e Use

Signals Geometric Data SINGLELANE may be

coded

Saturation Flows SINGLELANE may be

coded

All-way stop- SINGLELANE may not

controlled be coded;
intersection code NUMBEROFLANES
=1

Two-way stop- SINGLELANE may be

controlled coded for minor road
intersection Use FOURLANEMAJOR
to describe major road

Priority intersection Geometric Data SINGLELANE may be

(two-way yield- coded for minor arms
controlled Major road width in
intersection) meters, not lanes

Saturation Flows SINGLELANE may be

coded

Roundabout Empirical SINGLELANE may not

be coded

Gap Acceptance SINGLELANE may not

be coded

Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES,

CANSHARERIGHT, or CANSHARELEFT on that approach.

At two-way stop-controlled intersections and priority junctions, a minor arm, which does
not have SINGLELANE = Y explicitly coded, has two lanes.
Intersection Modeling > Two-way stop-controlled intersections > Keywords > SIXLANEMAJOR

SIX LAN EMAJOR

This keyword is used if number of lanes on major street corssing the two-way stop
intersection is more than 2. If it is more than 3 and used as SIXLANEM AJOR .
Intersection Modeling > Two-way stop-controlled intersections > Keywords > STORAGESPACE

ST ORAGESPACE
NOTE: Keywords are case insensitive. Capitalizing as StorageSpace might improve
readability.

This integer-valued keyword applies to two-way stop-controlled intersections. It is the

number of vehicles (PCU) that can wait in the central reservation without impeding major
road traffic. It does not matter whether the central reservation is curbed or striped (ghost
islands).
Intersection Modeling > Two-way stop-controlled intersections > Keywords > TURNCHANNELIZED

T URN CHAN N ELIZED

NOTE: Keywords are case insensitive. Capitalizing as TurnChannelized might improve
readability.

The turn referred to is the turn which follows the curb (by default, the right turn; when
LEFTDRIVE = T, the left turn). The turn is said to be channelized if there is a triangular,
curbed island separating the turners from the other movements on the approach. The
effect of turn channelization is ensure that the turning flows do not act as conflicting flows
during the calculation of capacities on other legs.
Setting TURNCHANNELIZED to T for an approach indicates that the unopposed turn from
that approach is channelized. By default, no turns are channelized.
Intersection Modeling > Two-way stop-controlled intersections > Example

Example
The example describes a two-way-stop-controlled intersection with two-lane majors,
two-lane minors and a central reservation.
Junction Node = 9 Type = TwoWayStop Approach1 = 8,
FourLaneMajor = y, StorageSpace = 3,
Approach = 6, TurnChannelized = y,
Approach = 7,
Approach = 8,
Approach = 5,
Intersection Modeling > All-way-stop-controlled intersections

All-way-stop-controlled intersections
All-way-stop-controlled intersections are unsignalized intersections with “stop” signs at
every approach.
Cube 6.4 version supports both HCM2000 and HCM 2010 modeling of All-way stop
controlled intersections. This can be set up using the HCM Versio n keyword. The model is
described for different cases based on intersection geometry and the arrival patterns at
the stop line. The model's only variable is the number of lanes for each arm. The model
can be used to analyze the capacity, delay, queue and LOS of all-way-stop-controlled
(AWSC) intersections. The low flow delay is the adjusted saturation headway or the
inverse of the capacity for AWSC intersections.
The capacities reported by models of undersaturated all-way-stop-controlled
intersections can appear very large. However, the model is very nonlinear and, as the
flows are increased, the capacities will decrease.
A ll-wa y -s to p -c o ntro lle d inte rs e c tio n k e y wo rd

Ke y wo rd D e s c rip tio n

N U MB E R OFLA N E S |I| Number of lanes at an

approach to an all-way-stop-
controlled intersection. Valid
values are 1, 2, or 3.

H E A V Y V E H ICLE S |I| Number of heavey vehicles per

approach. Default value is set
to 0.

NOTE: Keywords are case insensitive. Capitalizing as NumberOfLanes might improve

readability.
Intersection Modeling > All-way-stop-controlled intersections > Example

Exam ple

The following example describes an all-way-stop-controlled intersection between a one-

lane road and a two-lane road.
Junction Node = 9 Type = AllWayStop Approach1 = 8,
Approach = 6 NumberOfLanes = 1,
Approach = 7 NumberOfLanes = 2,
Approach = 8 NumberOfLanes = 1,
Approach = 5 NumberOfLanes = 2

References

• Transportation Research Board. Highway Capacity Manual 2000.

• Transportation Research Board. Highway Capacity Manual 2010.

Intersection Modeling > Roundabouts

Roundabouts
This section describes roundabouts. Topics include:
• Overview of roundabouts

• Empirical roundabouts: Keywords

• Empirical roundabouts: Example

• Gap acceptance roundabouts: Keywords

• Gap-acceptance roundabouts: Example

Intersection Modeling > Roundabouts > Overview of roundabouts

Overview of roundabouts
Roundabouts are a form of unsignalized intersection in which traffic circulates around a
one-way closed lane to travel from an approach to an exit. Traffic on an approach must
give way to traffic which is already on the circulating section. There are no constraints on
traffic leaving the roundabout.
The circulating flow past an entry is the only flow which influences the capacity of that
entry. The model builder, therefore, can always represent the circulating lane explicitly in
the network, without compromising the modeling of the intersection. Individual
roundabout models are placed at each entry. The approach characteristics of the actual
roundabout entries remain unchanged. One of the circulating legs is exit only and the
other circulating leg should be coded so that vehicles entering the roundabout from that
approach are not significantly constrained. This technique is particularly useful for
modeling roundabouts with five or more legs.

Cube Voyager offers two ways to model roundabouts:

• Gap-acceptance model — Each entry is characterized by a critical gap and a follow-up time.
Cube Voyager supports both HCM 2000 and HCM 2010 roundabout models. This setting is
controlled by the H CMV E R S ION keyword.

• Empirical model — Each entry is characterized by a capacity slope and a capacity intercept.
The methodology is implemented based on the TRRL report 940.

Both models can be used to analyze the capacity, delay, queue and LOS of roundabout
intersections. The low flow delay is the inverse of the capacity for roundabout
intersections.
You can calculate the slope and intercept outside of Cube Voyager, or you can supply
geometric data and let Cube Voyager calculate the slope and intercept using formulas
calibrated in the UK.
Worldwide experience with roundabouts and roundabout models leads to the following
conclusions:
• When a well calibrated empirical model exists, it should be used in preference to a gap
acceptance model
• However, the calibration of relationships between geometry, on one hand, and slope and
intercept, on the other, requires very large amounts of data

• The number of roundabouts in the US is not yet sufficiently great to allow calibration of a
US empirical model

• Even when general countrywide empirical relationships exist, it may be necessary to fine
tune the slope and intercept for local conditions

• When no general countrywide empirical relationships exist, it is better to use a gap

acceptance model

The Highway Capacity Manual (HCM 2000) indicates appropriate parameter ranges for
a single-lane roundabout entry in the US.
References

• Transportation Research Board. Highway Capacity Manual 2000.

• Transportation Research Board. Highway Capacity Manual 2010.

• Hollis, E. M., Semmens M. C. and Denniss S. L. (1980). ARCADY: A Computer Program to

Model Capacities, Queues and Delays at Roundabouts. Transport and Road Research
Laboratory Report RL 940.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords

Empirical roundabouts: Keywords

This section describes keywords to model empirical roundabouts:
• APPROACHWIDTH

• CAPACITYINTERCEPT

• CAPACITYSLOPE

• CROSSING2ENTRY

• CROSSING2EXIT

• CROSSINGLENGTH

• ENTRYANGLE

• ENTRYRADIUS

• ENTRYWIDTH

• FLARELENGTH

• INSCRIBEDDIAMETER
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > APPROACHWIDTH

APPROACHWIDT H
NOTE: Keywords are case-insensitive. Capitalizing as ApproachWidth might improve
readability.

This real-valued keyword allows the specification of the approach half width (in meters
or feet), one of the geometric parameters for the U.K.-calibrated empirical roundabout
model.
To measure the approach half width, measure from the road center line to the curb at a
point sufficiently far from the roundabout that the curb and center line are parallel. In the
diagram below, the double arrow marked “v” (below the arrow) and “AWID” (to the left of
the arrow) illustrates the measurement.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > CAPACITYINTERCEPT

CAPACIT YIN T ERCEPT

NOTE: Keywords are case insensitive. Capitalizing as CapacityIntercept might improve
readability.

At an empirically modeled roundabout, each approach is characterized by two real

numbers, the capacity slope and the capacity intercept. The capacity intercept is the
entry capacity when the circulating flow is zero. The CAPACITYINTERCEPT keyword may
be used to supply the capacity intercept directly.

If CAPACITYINTERCEPT is coded for a roundabout entry, CAPACITYSLOPE must also be

coded for that entry and none of the roundabout geometric parameters may be coded for
that entry.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > CAPACITYSLOPE

CAPACIT YSLOPE
NOTE: Keywords are case insensitive. Capitalizing as CapacitySlope might improve
readability.

At an empirically modeled roundabout, each approach is characterized by two real

numbers, the capacity slope and the capacity intercept. The capacity slope is the
marginal decrease in entry capacity when the circulating flow is increased by one PCU
per hour. The CAPACITYSLOPE keyword may be used to supply the capacity slope
directly.

If CAPACITYSLOPE is coded for a roundabout entry, CAPACITYINTERCEPT must also be

coded for that entry and none of the roundabout geometric parameters may be coded for
that entry.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > CROSSING2ENTRY

CROSSIN G2EN T RY
This keyword specifies the position of a zebra crossing on an approach to a roundabout
or a minor approach priority junction. Its value is the number of vehicles that may queue
at the junction without impeding pedestrians who wish to cross. At roundabouts and
single lane minor approaches to priority junctions, a single integer value should be
supplied. However, on two-lane minor approaches to priority junctions, separate values
should be supplied for each of the two lanes.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > CROSSING2EXIT

CROSSIN G2EX IT
This integer-valued keyword specifies the position of a zebra crossing on an exit from a
roundabout or priority junction. Its value is the number of vehicles that may queue at the
crossing without impeding vehicles using other exits from the junction.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > CROSSINGLENGTH

CROSSIN GLEN GT H
This real-valued keyword allows the specification of the length of a zebra crossing that
crosses an approach to a roundabout or priority junction. If it is absent then no crossing
will be modeled.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > ENTRYANGLE

EN T RYAN GLE
NOTE: Keywords are case insensitive. Capitalizing as EntryAngle might improve readability.

This real-valued keyword allows the entry angle, theta, of a roundabout to be coded.
There are three cases for the measurement of phi.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > ENTRYANGLE > Case 1: A roundabout with
straight weaving sections

Case 1: A ro undabo ut with straight weaving sectio ns

• Let A be the point where the entry line meets the inside edge of the lane

• Let D be the point on the median island (or line) of the following entry which is nearest to A

• EF is curve which is in the middle of the area of road for vehicles entering the junction

• BC is a tangent to EF at the point where EF intersects the stop line

• phi is the angle between BC and AD

Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > ENTRYANGLE > Case 2: A roundabout with
long curved weaving sections

Case 2: A ro undabo ut with lo ng curved weaving sectio ns

The construction for case 2 is nearly identical to that for case 1. However, the line AD is
replaced by a curve A’D’ which is always parallel to the weaving section.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > ENTRYANGLE > Case 3: A roundabout with
short weaving sections

Case 3: A ro undabo ut with sho rt weaving sectio ns

• EF and BC are constructed as in case 1

• JK is constructed in the same way as EF, but for the following exit

• GH is the tangent to JK where JK meets the edge of the circulating section

• L is the intersection of BC and GH

• phi is zero or (90 - ½(angle GLB)), whichever is greater

Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > ENTRYRADIUS

EN T RYRADIUS
NOTE: Keywords are case insensitive. Capitalizing as EntryRadius might improve
readability.

This real-valued keyword allows the specification of the entry radius (in meters or feet),
one of the geometric parameters for the U.K.-calibrated empirical roundabout model.
The entry radius is defined as the minimum radius of curvature of the curb line at the
entry.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > ENTRYWIDTH

EN T RYWIDT H
NOTE: Keywords are case insensitive. Capitalizing as EntryWidth might improve readability.

This real-valued keyword allows the specification of the entry width (in meters or feet),
one of the geometric parameters for the U.K.-calibrated empirical roundabout mode.
To measure the entry width:
• Let A be the point where the stop-line meets the inside edge of the lane

• Let B be a point on the curb-line such that the line A-B is normal to the curb at B

• The entry width is the length of the line A-B

In the diagram below, the double arrow marked “C” and “EWID” illustrates the
measurement.
Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > FLARELENGTH

FLARELEN GT H
NOTE: Keywords are case insensitive. Capitalizing as FlareLength might improve
readability.

This real-valued keyword allows the specification of the modified flare length (in meters
or feet) for the entry to an empirically modelled roundabout. This is measured using the
following procedure:

• Let A be the point where the stop line meets the inside edge of the lane.

• Let B be the point on the curb line such that the line A-B is normal to the curb line at B (A-B
is the entry width, e).

• Let v be the approach width. Let D be a point on A-b such that the length of A-D is v.

• Let D-G be a curve through D and parallel to the inside edge of the lane. (G is the point
where the curve meets the curb).

• Let C be the mid point of D-B.

• Let C-F’ be a curve parallel to the curb which intersects the curve D-G at F’.

• The modified flare length is the length of the curve C-F’.

Intersection Modeling > Roundabouts > Empirical roundabouts: Keywords > INSCRIBEDDIAMETER

IN SCRIBEDDIAMET ER
NOTE: Keywords are case insensitive. Capitalizing as InscribedDiameter might improve
readability.

This real-valued keyword allows the specification of the inscribed circle diameter of the
roundabout (in meters or feet). Usually this is the largest circle that can be inscribed
wholly within the outline of the junction (see figure below). However, when the
intersection is very asymmetrical, a local value in the region of the entry should be taken.
Intersection Modeling > Roundabouts > Empirical roundabouts: Example

Empirical roundabouts: Example

The following example uses geometrical data to calculate slopes and intercepts:
Junction,
Node = 213,
Type = Roundabout,
Approach1 = 223,
Approach = 223,
EntryWidth = 12.5,
ApproachWidth = 7.3,
FlareLength = 25.0,
InscribedDiameter = 25.0,
Approach = 224,
EntryWidth = 10.0,
ApproachWidth = 6.0,
FlareLength = 15.0,
InscribedDiameter = 25.0,
Approach = 321,
EntryWidth = 10.0,
ApproachWidth = 6.0,
FlareLength = 15.0,
InscribedDiameter = 25.0,

After comparing the model results to the performance of the intersection on the ground, it
was decided to recode approach 224 to give the slope and intercept directly:
Junction,
Node = 213,
Type = Roundabout,
Approach1 = 223,
Approach = 223,
CapacitySlope = 0.2,
CapacityIntercept = 3600,
Approach = 224,
EntryWidth = 10.0,
ApproachWidth = 6.0,
FlareLength = 15.0,
InscribedDiameter = 25.0,
Approach = 321,
EntryWidth = 10.0,
ApproachWidth = 6.0,
FlareLength = 15.0,
InscribedDiameter = 25.0,
Intersection Modeling > Roundabouts > Gap acceptance roundabouts: Keywords

Gap acceptance roundabouts: Keywords

This section describes the keywords to model gap-acceptance roundabouts:
• BYPASSTYPE

• CENTERLANEPERCE

• CIRCULATINGLANE

• CRITICALGAP

• FOLLOWUPTIME
Intersection Modeling > Roundabouts > Gap acceptance roundabouts: Keywords > BYPASSTYPE

BYPASST YPE
This keyword identifies how right-turn lanes yields at roundabout. This depends upon
the existence of exclusive right-turn lanes on the subject link. Below is a screenshot from
HCM 2010 Exhibit 21-8 that explains how this keyword is used. For the new calculators,
the following values are used:
• If RT=1, then B Y P A S S T Y P E is non-yielding. Value=2 in Junction.

• If RT, then B Y P A S S T Y P E is default. Value=0 in Junction.

• User needs to input the BYPASSTYPE for yielding lanes.

Intersection Modeling > Roundabouts > Gap acceptance roundabouts: Keywords > CENTERLANEPERCE

CEN T ERLAN EPERCE

This keyword specifies the lane utilization factor of the left-turn of the approaching linke.
Exhibit 21-21 (see below) is used for reference. For the new calculators, the following
values are used:
• If LT=1, then CE N T E R LA N E P E R CE is 53.

• Fore everything else, CE N T E R LA N E P E R CE is 47.

Intersection Modeling > Roundabouts > Gap acceptance roundabouts: Keywords > CIRCULATINGLANE

CIRCULAT IN GLAN E
CIRCULATINGLANE specifies the number of circulating lanes in the roundabout. This is
identified by comparing the cross street lanes. For each apporach, lanes at legs 2 and 4
(for a 4-link roundabout) or legs 2 and 3 (for a 3-link roundabout) will be obtained and
the maxt of the values will be used. By default, Cube Junction model will keep teh
default value as 1 unless specified by user.
Intersection Modeling > Roundabouts > Gap acceptance roundabouts: Keywords > CRITICALGAP

CRIT ICALGAP
Keywords are case-insensitive but the recommended capitalization CriticalGap may
improve readability.
The critical gap, in seconds, is one of the parameters of any gap-acceptance capacity
model. At roundabouts, it is applicable by arm. It is defined as the minimum time interval
in the circulating stream that allows intersection entry for one vehicle.
The U.S. Highway Capacity Manual 2000 suggests that, for a single-lane roundabout
entry in the US, the critical gap should be in the range 4.1 to 4.6 seconds.
Intersection Modeling > Roundabouts > Gap acceptance roundabouts: Keywords > FOLLOWUPTIME

FOLLOWUPT IME
NOTE: Keywords are case insensitive. Capitalizing as FollowUpTime might improve
readability.

The follow-up time, in seconds, is one of the parameters of any gap-acceptance

capacity model. At roundabouts, it is applicable by arm. It is defined as the time between
the departure of one vehicle from the entry and the departure of the next vehicle using
the same circulating flow gap, under a condition of continuous queuing on the entry.
The U.S. Highway Capacity Manual 2000 suggests that, for a single-lane roundabout
entry in the America, the follow-up time should be in the range 2.6 to 3.1 seconds.
Intersection Modeling > Roundabouts > Gap-acceptance roundabouts: Example

Gap-acceptance roundabouts: Example

The following illustrates a gap-acceptance roundabout model:
Junction,
Node = 253,
Type = Roundabout,
Approach1 = 32,
Approach = 32, 208,
CriticalGap = 4.6,
FollowUpTime = 3.1,
Approach = 256,
CriticalGap = 4.35,
FollowUpTime = 2.85,
Approach = 486,
CriticalGap = 4.1,
FollowUpTime = 2.6
Intersection Modeling > Priority junctions

Priority junctions
This section describes priority junctions (two-way yield-controlled intersections). Topics
include:
• Overview of priority junctions

• Keywords

• Geometric priority junctions: Keywords

• Geometric priority junctions: Example

• Saturation-flow priority junctions: Keywords

• Saturation-flow priority junctions: Example

Intersection Modeling > Priority junctions > Overview of priority junctions

Overview of priority junctions

A priority-junction control is an unsignalized intersection between a major road and a
minor road. It has different names in the U.K. (where “priority junctions” are common)
and the U.S. (where “two-way yield-controlled intersections” are rare). In the U.S., the
minor road approach (at a “T”), or approaches (at a crossroads) have “yield” signs. In
the U.K., the yield signs are optional. Traffic on the minor need not stop before entering
the intersection, but must give way to any major road traffic.
Cube Voyager offers two model variants, both of which are calibrated to U.K. traffic
conditions: a full empirical model based on junction geometry and a simplified models in
which the user provides saturation flows which have been estimated or measured
externally to Cube Voyager.
The geometric model is developed based on the TRRL report 941, and the saturation
model is developed based on a similar model utilized in the signal saturation flow model.
Both models can be used to analyze the capacity, delay, queue and LOS of roundabout
intersections. The low flow delays are the inverse of the capacity for both priority
intersections.
When a single-lane major road is being modeled, very large capacities may be reported.
This occurs when a movement, which is unconstrained, shares a lane. The capacity is
chosen to give the correct ratio of volume to capacity (as calculated for the constrained
movement).
References

• Kimber, R. M., Mcdonald, M., Hounsell, N. B. (1986). The prediction of saturation flows for
single road junctions controlled by traffic signals. Transport and Road Research
Laboratory Report RR 67.

• Semmens M. C. (1980). PICADY: a computer program to model capacities, queues and

delays at major/minor junctions. Transport and Road Research Laboratory Report RL 941.
Intersection Modeling > Priority junctions > Keywords

Keywords
This section describes keywords for priority junctions:
• GEOMETRIC

• SINGLELANE
Intersection Modeling > Priority junctions > Keywords > GEOMETRIC

GEOMET RIC
The keyword “ Geometric=y”, invokes modeling of layout geometry at a priority junction.
The default, “ GapAcceptance =n”, at a priority junction is for the user to supply saturation
flows directly.
Intersection Modeling > Priority junctions > Keywords > SINGLELANE

SIN GLELAN E
NOTE: Keywords are case insensitive. Capitalizing as SingleLane might improve readability.

The logical-valued keyword is used to indicate that an approach consists of a single

lane. It is applicable to many junction types:

J unc tio n ty p e Use

Signals Geometric Data SINGLELANE may be coded

Saturation Flows SINGLELANE may be coded

All-way stop-controlled SINGLELANE may not be

intersection coded;
code NUMBEROFLANES = 1

Two-way stop-controlled SINGLELANE may be coded for

intersection minor road
Use FOURLANEMAJOR to
describe major road

Priority intersection Geometric Data SINGLELANE may be coded

(two-way yield-controlled
intersection)

Saturation Flows SINGLELANE may be coded

Roundabout Empirical SINGLELANE may not be coded

Gap Acceptance SINGLELANE may not be coded

Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES,

CANSHARERIGHT, or CANSHARELEFT on that approach.

At two-way stop-controlled intersections and priority junctions, a minor arm, which does
not have SINGLELANE = Y explicitly coded, has two lanes.
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords

Geometric priority junctions: Keywords

This section describes the keywords for geometric priority junctions:
• CENTRALRESERVATIONWIDTH

• CROSSING2ENTRY

• CROSSING2EXIT

• CROSSINGLENGTH

• FREEFLOWCAP

• MAJORROADWIDTH

• VISIBILITY

• WIDTH
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > CENTRALRESERVATIONWIDTH

CEN T RALRESERVAT ION WIDT H

NOTE: Keywords are case insensitive. Capitalizing as CentralReservationWidth might improve
readability.

CENTRALRESERVATIONWIDTH is a real-valued keyword (only) applicable to geometrically

modeled priority junctions. Its value is the width, in meters or feet, of the curbed central
reservation in the major road. If there is no central reservation, or the central reservation
is composed of ghost islands (that is, road markings), then CENTRALRESERVATIONWIDTH
should be zero (the default). Otherwise its value should be in the range from 2.2 to 5.
In the diagram below, the CENTRALRESERVATIONWIDTH is given by ½(W5 + W6).
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > CROSSING2ENTRY

CROSSIN G2EN T RY
This keyword specifies the position of a zebra crossing on an approach to a roundabout
or a minor approach priority junction. Its value is the number of vehicles that may queue
at the junction without impeding pedestrians who wish to cross. At roundabouts and
single lane minor approaches to priority junctions, a single integer value should be
supplied. However, on two-lane minor approaches to priority junctions, separate values
should be supplied for each of the two lanes.
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > CROSSING2EXIT

CROSSIN G2EX IT
This integer-valued keyword specifies the position of a zebra crossing on an exit from a
roundabout or priority junction. Its value is the number of vehicles that may queue at the
crossing without impeding vehicles using other exits from the junction.
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > CROSSINGLENGTH

CROSSIN GLEN GT H
This real-valued keyword allows the specification of the length of a zebra crossing that
crosses an approach to a roundabout or priority junction. If it is absent then no crossing
will be modeled.
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > FREEFLOWCAP

FREEFLOWCAP
NOTE: Keywords are case insensitive. Capitalizing as FreeFlowCap might improve
readability.

By default, the unmodelled movements from the major approaches of a priority junction
have infinite capacity. However, this may result in too large a capacity for the approach
as a whole when it must share a lane with a modelled turn. You can supply a capacity
for these movements by coding FreeFlowCap=value and SingleLane=t.
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > MAJORROADWIDTH

MAJORROADWIDT H
NOTE: Keywords are case insensitive. Capitalizing as MajorRoadWidth might improve
readability.

MAJORROADWIDTH is only applicable to geometrically modeled priority junctions, where it

is required. The presence or absence of this keyword allows the two methodologies for
priority junction modeling to be distinguished.
MAJORROADWIDTH is a real valued keyword whose value is the width, in meters or feet, of
the major road lane (excluding any central reservation or ghost islands) near the
intersection. It is illustrated in the four diagrams below. In each case the major road width
is given by the expression ½(W1 + W2 + W3 + W4).
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > VISIBILITY

VISIBILIT Y
This real-valued keyword allows the visibilities, in meters or feet, at a geometrically
coded priority junction (two-way yield-controlled intersection) to be entered.
Visibilities may be coded for the minor road left and right movements and for the
opposed movement from the major road. Minor road visibilities should be measured from
a point ten meters before the give-way line and 1.05 meters above the road surface. The
major road visibility is measured from the mid-point of the turning lane (again at height
1.05m), along the major road, towards the road center line.
Intersection Modeling > Priority junctions > Geometric priority junctions: Keywords > WIDTH

WIDT H
This real-valued keyword is used to specify the lane widths (in meters or feet) for a
minor road at a priority junction (two-way yield-controlled intersection).
Code widths for left and right movements on minor roads and for the opposed
movement from the major road. The width for the major road’s opposed movement is the
width of the lane from which vehicles on the major road turn. Coding techniques for
minor roads vary with the number of lanes.
To describe a two-lane minor road:
• Do not code SINGLELANE = T.

• Code the width of the left lane in the left movement.

• Code the width of the right lane in the right movement.

To describe a one-lane minor road:

• Code SINGLELANE = T.

• Code the width of the single lane in the left movement, or the right movement, but not both.

The coded widths should be the lane’s average width during the final 25 meters of the
approach before the give-way line.
Intersection Modeling > Priority junctions > Geometric priority junctions: Example

Geometric priority junctions: Example

This example illustrates the coding of a three-arm priority junction, with input geometric
data.
Junction,
Node = 250,
Type = Priority,
Approach1 = 455,
MajorRoadWidth = 10.9,
CentralReservation = 1.2,
Approach = 455,
Movement = Right,
Width = 2.5,
Visibility = 170.0,
Approach = 249,
Movement = Left,
Width = 2.05,
Visibility = 130.0,
Movement = Right,
Width = 2.05,
Visibility = 125.0,
Approach = 251,
Movement = Right,
Width = 2.9,
Visibility = 150.0,
Approach = 255,
SingleLane = y,
Movement = Left,
Visibility = 100.0,
Movement = Right,
Width = 3.1,
Visibility = 127.0
Intersection Modeling > Priority junctions > Saturation-flow priority junctions: Keywords

Saturation-flow priority junctions: Keywords

This section describes the keywords for saturation-flow priority junctions:
• CANSHARELEFT

• CANSHARERIGHT

• EXCLUSIVELANES

• SATFLOWPERLANE
Intersection Modeling > Priority junctions > Saturation-flow priority junctions: Keywords > CANSHARELEFT

CAN SHARELEFT
NOTE: Keywords are case insensitive. Capitalizing as CanShareLeft might improve
readability.

This keyword specifies that there is a shared lane to the left of the exclusive lanes for
this movement (that is, the movement can share with the movement to its left). Note that
this keyword does not mean “can share with left turners” unless either the movement is
THROUGH or the movement is on the minor leg of a three-arm junction.
If a movement has CANSHARELEFT = T coded then there must be a movement to this
movement’s left and the movement to this movement’s left must have CANSHARERIGHT = T
coded.
If SINGLELANE = T then CANSHARELEFT should not be coded.
Intersection Modeling > Priority junctions > Saturation-flow priority junctions: Keywords > CANSHARERIGHT

CAN SHARERIGHT
NOTE: Keywords are case insensitive. Capitalizing as CanShareRight might improve
readability.

This keyword specifies that there is a shared lane to the right of the exclusive lanes for
this movement (that is, the movement can share with the movement to its right). Note
that this keyword does not mean “can share with right turners” unless either the
movement is THROUGH or the movement is on the minor leg of a three arm junction.
If a movement has CANSHARERIGHT = T coded, then there must be a movement to this
movement’s right, and the movement to this movement’s right must have CANSHARELEFT =
T coded.

If SINGLELANE = T then CANSHARERIGHT should not be coded.

Intersection Modeling > Priority junctions > Saturation-flow priority junctions: Keywords > EXCLUSIVELANES

EX CLUSIVELAN ES
NOTE: Keywords are case insensitive. Capitalizing as ExclusiveLanes might improve
readability.

This integer-valued keyword gives the number of lanes, on the specified approach,
which are reserved for the exclusive use of vehicles making the specified movement.
If SingleLane = t then ExclusiveLanes should not be coded.
Intersection Modeling > Priority junctions > Saturation-flow priority junctions: Keywords > SATFLOWPERLANE

SAT FLOWPERLAN E
NOTE: Keywords are case insensitive. Capitalizing as SatFlowPerLane might improve
readability.

This real-valued keyword allows the specification of saturation flows in pcu (vehicles)
per hour per lane.
Saturation flows at signals are the flows that would be observed if the movement had a
continuous green all other movements had no flow and no green.
Saturation flow at a priority junction (two-way yield-controlled intersection) is defined
similarly, except that no signal aspects are involved.
Intersection Modeling > Priority junctions > Saturation-flow priority junctions: Example

Saturation-flow priority junctions: Example

The example describes a priority junction using with a three-lane major and two-lane
minor using default saturation flows per lane.
Junction,
Node = 229,
Approach1 = 396,
Type = Priority,
Approach = 228,
Movement = Left,
ExclusiveLanes = 1,
CanShareRight = y,
Movement = Through,
ExclusiveLanes = 1,
CanShareLeft = y,
CanShareRight = y,
Movement = Right,
ExclusiveLanes = 1,
CanShareLeft = y,
Approach = 396,
Movement = Left,
ExclusiveLanes = 1,
CanShareRight = y,
Movement = Through,
ExclusiveLanes = 1,
CanShareLeft = y,
CanShareRight = y,
Movement = Right,
ExclusiveLanes = 1,
CanShareLeft = y,
Approach = 315,
Movement = Left,
ExclusiveLanes = 1,
CanShareRight = y,
Movement = Through,
CanShareLeft = y,
CanShareRight = y,
Movement = Right,
ExclusiveLanes = 1,
CanShareLeft = y,
Approach = 409,
Movement = Left,
ExclusiveLanes = 1,
CanShareRight = y,
Movement = Through,
CanShareLeft = y,
CanShareRight = y,
Movement = Right,
ExclusiveLanes = 1,
CanShareLeft = y
Network Program > Introduction to the Network program

Introduction to the Network program

Network is a utility program for processing highway networks. The program can process
up to ten input networks simultaneously, and can generate one output network. The
program can read input network files of various formats: ASCII records, standard
database in dBASE style (DBF), Cube geodatabase networks, or any Cube Voyager,
TP+, MINUTP, Tranplan, or TRIPS binary network format. The program generates a
data record for each unique node and each link found in any of the input files. For a valid
node record, the Network program requires a node variable, named N. For a valid link
record, the Network program requires an A-node, named A, and a B-node, named B.
Each A-node and B-node must exist on a node record. To open, view, and edit the
network in Cube Graphics, the node records must also have two additional variables,
named X and Y, that represent the X- and Y-coordinates of each node. The program
processes each of these records using logic that you can control. You can summarize
and report on the processed data.
Node and link records in a given data file need not be unique. Use the COM BINE
subkeyword with the LINKI and NODEI keywords under the FILEI statement to specify how
to combine values of fields with redundant data records. NETWORK also features the
GEOMI keyword to read link geometry sources from shapefiles and geodatabases.

Upon detecting a Tranplan network as input, the program immediately writes it in Cube
Voyager format to a temporary file, and then uses that file in place of the original file for
subsequent processing. (Note: Cube Voyager treats a FSUTMS network as a standard
Tranplan network. No auxiliary files will be open. Only Cube deals with FSUTMS
networks differently.)
If you specify an output network, the program writes a file in a proprietary (Cube Voyager
or MINUTP) binary format. It is a network database that contains speed/capacity
information, node records, and link records. In MINUTP networks, the node information
consists solely of coordinates for each node. In a Cube Voyager or TP+ network, there
may be any number of items for nodes. Optionally, a file of link records and/or a file of
node records may be written in either ASCII or DBF format. Beginning with version 5.0,
output networks may be a Cube Voyager custom network feature class, stored in an
ESRI custom geodatabase. See the description for the FORM AT subkeywords under
NETO keyword for the FILEO statement on page 445 for information on specifying output
networks to a Cube Voyager custom feature class network in a geodatabase file.
Subsequent topics discuss:
• Built-in variables

• Built-in functions
Network Program > Introduction to the Network program > Built-in variables

Built-in variables
V a ria b le D e s c rip tio n

A Node number of a link’s A node

B Node number of a link’s B node

GEOMETRYSOURCE Defines the input file index number that controls the
source of the geometry to be applied to the output
NETO or LINKO file when multiple input networks are
specified.
The Network program may take up to ten input
networks. These ten networks can be any of the
supported binary formats, Cube geodatabase
networks, GIS shapefiles (for GEOMI only), or
combinations of link and node files in ASCII, DBF, or
MDB formats. When specifying an output network to
a Cube geodatabase network or LINKO shape file,
GEOMETRYSOURCE specifies which # from the FILEI
LINKI[#]= or FILEI GEOMI[#]= specifications
provides the geometry to be applied to the output
geodatabase network.
Each input network coming from a geodatabase
network will have a field called GEOMETRYSOURCE.
This field’s value is the index of the input file (3 for
LINKI[3], for example). Other input formats could
also have a field called GEOMETRYSOURCE
defined by the user. The value of the
GEOMETRYSOURCE field in the output network
dictates the source of the link geometry. By default,
the value is taken from the first available value from
all the input networks. So if LINKI[1] is a binary
network without a GEOMETRYSOURCE field and
LINKI[2] is a geodatabase network, the output
GEOMETRYSOURCE field will have a value of 2
(unless there is no record in LINKI[2] for a certain
link). If MERGE RECORD=T, records that are merged
from other LINKIs retain their GEOMETRYSOURCE
value. Therefore, the output network could have a
mix of GEOMETRYSOURCE values.
In addition, you can specifically set the value in a
script based on other attributes in the various input
networks (for example, downtown use LINKI[3], and
other areas use LINKI[2]).
Please refer to GEOMI for additional usage
requirements specific to that keyword and its indices.

N Node number of the node

X X-coordinate value of a node

Y Y-coordinate value of a node

_COMPARE Stores a return code value resulting from the

COMPARE statement

_ZONES Holds the number of zones read from the input

network as set by the ZONES parameter
Network Program > Introduction to the Network program > Built-in functions

Built-in functions
Func tio n D e s c rip tio n

SPEEDFOR(lanes,spdclass) Returns the speed from the SPEED

table for the designated number of
lanes and spdclass.

CAPACITYFOR(lanes,capclass) Returns the capacity times the lanes for

the designated number of lanes and
capclass.

CHECKNAME(Name) Check if a link attribute exists. If it does

not exist, the function returns a zero. If it
exists, the return code is a 2 digit
number in the format of {t}{s}, defined
as follows:
{t} is type
0=single variable
1=vector
2=user function
3=work matrices
4=user function
5=user function
6=vector with constant index
and no default index
7=multidimension array, no
default index
{s} is storage size
1=numeric size
2=string
e.g. 1=numeric variable, 2=string
variable, 11=numeric array,
12=string array

GETVALUE(Name {, Get a numeric value from a link

DefaultValue}) attribute. This function is used along
with the ChechName function.
CheckName checks the existence of a
link attribute and GetValue extracts the
value from it. They are used to avoid
model run crash due to non-existence
or invalid value of a link attribute in the
input files. Users can specify a default
value in case of any invalid values. For
example:
IF(CHECKNAME(‘LI.1.LANES’)>0)
_Im=GETVALUE(‘LI.1.LANES’)
ENDIF
Network Program > Control statements

Control statements
This section describes the control words available in the Network program.

Co ntro l wo rd D e s c rip tio n

ABORT Abort current program and Cube Voyager

ARRAY Declare user arrays

BREAK Break out of stack processing for current

data record

COMP Compute variables from expressions

COMPARE Compare network records

CONTINUE Continue at end of loop statement

CROSSTAB Tabulate / cross tabulate variable values

DELETE Delete this record

EXIT Terminate current phase

FILEI Input files

FILEO Output files

IF ... ELSEIF ... ELSE ... Define IF ENDIF block

ENDIF

LOOKUP Define lookup tables (see Chapter 3,

“General Syntax”)

LOOP ... ENDLOOP Define user controlled loop

MERGE Set record and variable merging

specifications

PARAMETERS Set static parameters

PLOT Draw and post values on links and nodes

PLOTTER Set plotter driver specifications

PRINT Print variable values

PROCESS ... Set process (phase) blocks

ENDPROCESS

REPORT Select standard reports

SORT Sort user arrays

SPDCAP Set / revise network speed and capacity

table values
Network Program > Control statements > ABORT

ABORT
Aborts the Network program and Cube Voyager. Keywords include:
• MS G

Use ABORT to quit the Network program at with a “fatal” return code. Use this statement if
you can determine from the data that you desire no further processing.
A B OR T k e y wo rd

Ke y wo rd D e s c rip tio n

MSG |S| Optional message to be printed along with

the ABORT message. For readability,
Citilabs recommends 100 characters or
less.
Network Program > Control statements > ABORT > Example

Exam ple
IF (a > 1000) ABORT MSG='Must be the wrong Network'
Network Program > Control statements > ARRAY

ARRAY
Declares user single dimension arrays. Keywords include:
• VAR=size, VAR=size

Use ARRAY to allocate user arrays that are to be used in the process. An array is different
than a variable in that it represents vectored data. Values stored in arrays must be
numeric. Arrays cannot store string values. When an array is referenced, it should
include an index [], and if the index exceeds the size, the program may fatally terminate.
Arrays can be useful for different processes; the most common use may be to store
information for specific zones. ARRAY statements are not dynamic (stack oriented); they
are allocated prior to any stack operations.
A R R A Y v a ria b le

V a ria b le D e s c rip tio n

VAR |I| V A R is the name of the variable that is to

be allocated according to the specified
size. V A R must be a unique name. The
size following the keyword is the highest
index possible for V A R . Size may be either
a numeric constant, or a special name.
Special names are: ZONES, NODES, and
LINKS if there is a binary input network.
NODES and LINKS should not be used if
links are to be added to the network. Arrays
are cleared when they are allocated.
Network Program > Control statements > ARRAY > Example

Exam ple
ARRAY abc=100, xyz=100

ARRAY AN=LINKS, BN=LINKS, VMT=LINKS

; NETI must be a binary network
Network Program > Control statements > BREAK

BREAK
Breaks out of stack processing for current data record.
When a data record is being subjected to the operations in a phase block, and the
operation is BREAK, the remainder of the block operations are bypassed and the next
data record is processed. Most likely, BREAK would be used in conjunction with an IF
statement. However, if BREAK is encountered within a LOOP, stack processing jumps to
the statement after the associated ENDLOOP statement.
Network Program > Control statements > BREAK > Example 1

Exam ple 1
if (a=1-500 || b=1-500) BREAK ; do not process centroid links.
if (a.x > b.x) ; bypass the links that go from right to left
BREAK
endif
Network Program > Control statements > BREAK > Example 2

Exam ple 2
/* this example finds the index where subtotal of ARRAY1 exceeds 1000 */
loop index=1,_zones
_total = _total + array1[index]
if (_total>1000) BREAK
endloop
list=’INDEX =’,index ; BREAK jumps to here
Network Program > Control statements > COMP

COMP
Computes a value for a variable. Functions include:
• S P E E D FOR (la ne s ,s p d c la s s )

• CA P A CIT Y FOR (la ne s ,c a p c la s s )

Usage is:
Variable = Expression

COMP statements specify that new variables are to be created or that existing variables
are to have new values computed for them. During any phase other than the
SUMMARY, any name that appears on the left side of the equals sign will be placed into
the output network record, unless it is a working variable (begins with an underscore).
There may be more than one variable computed on a statement, but there must be
comma between an expression and the next variable=expression. The statement need
not begin with COMP.
The expression will be solved and the results stored in the named variable. The phase
for which this COMP statement is coded will establish which variables may be included
within the expression, and where the results can be stored. The maximum length of the
name is 15 characters. This limit includes the “_” prefix of temporary variables.
A normal numerical expression is required. If the expression results in a string, the mode
of the target (named) variable will be set to string instead of numeric. A variable’s mode
should be consistent throughout the application. The program tries to detect any
possible changes, or misuse of variable modes, but it might not detect all
inconsistencies. If a variable is misused as to mode, unpredictable results could occur. It
might be prudent to have a standard naming convention for string variables, such as
always beginning with the same letter.
The expression may contain function names with their arguments. To obtain speed
and/or capacity values from the SPDCAP tables, the SPEEDFOR and CAPACITYFOR
functions are utilized. They are coded as:

Func tio n D e s c rip tio n

SPEEDFOR Returns the speed from the SPEED table for

(lanes,spdclass) the designated number of lanes and
spdclass.

CAPACITYFOR Returns the capacity times the lanes for the

(lanes,capclass) designated number of lanes and capclass.
In the SPEEDFOR and CAPACITYFOR functions, the first argument is the number of lanes
and the second argument is the class. If the lanes value is less than 1, or greater than 9,
the function value of lanes will be reset accordingly. Thus, if CAPACITYFOR (88...) were
specified, lanes would be reset to 9, and the capacity extracted for that value would be
multiplied by 9. Similarly, if the second argument is less than 1, or greater than 99, the
internal value will be reset to the appropriate limit.
Network Program > Control statements > COMP > Example

Example
i = 0
j = a / i, k=j*2+3*i
newb = nodecode(b)
sumab = newb+newa
cdist = sqrt((a.x-b.x)^2 + (a.y-b.y)^2)
_LinkSpeed = SPEEDFOR(Lanes,Facility*10+Area)
Network Program > Control statements > COMPARE

COMPARE
Compares network records. Keywords and sub-keywords include:
• R E COR D
m LIST
m TITLE

COMPARE statements are dynamic and are used to compare the records of either the link
or node portion of two networks. At the end of the phase (NODEMERGE or
LINKMERGE), a summary of the comparison is reported. The LIST parameter controls
the listing of individual differences. To make this statement function properly, the MERGE
RECORD=T statement should be coded.

In addition to a summary report, COMPARE also returns a value indicating the result after
the comparison of each record. The value is stored in a temporary variable:
_COMPARE. The meaning of the returned value is as follows:

V a lue o f
_COMP A R E Me a ning

n n attributes are different between

two records.

0 No differences between two

records.

-1 Record not found in file one.

-2 Record not found in file two.

There may be multiple COMPARE statements in a single application.

COMP A R E k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

RECORD |IP| Indicates which LINKI or NODEI set of

records is to be compared. Two
numbers, separated by a dash, must
be coded. This keyword may occur
only one time on a COMPARE
statement.

RECORD LIST |I| Indicates how many of the links with

differences are to be listed to the print
file. The default is 0.
If LIST=100, then only the first 100 links
with differences will be listed. If a link
exists in one file but not in the other, a
single line is generated. But, if the
record keys match, each variable for
 which there is a difference will be listed
on a separate line with the values from
both files and the difference.

RECORD TITLE |S| Optional title to print with the summary

report. It is suggested that the value be
embedded within quotes.
Network Program > Control statements > COMPARE > Example 1

Exam ple 1
LINKI[1] = current.net
LINKI[2] = future.net
COMPARE RECORD=1-2

The following is a sample output in the print file:

COMPARE 1 vs. 2:
1=2 ------- 1 < 2 ------- ---- 1 > 2 ----
Variable Cnt Cnt Min Max Ave Cnt Min Max Ave Ave
-------- --- --- --- --- --- --- --- --- --- ---
A 321 -- -- -- -- 7 -- -- -- --
B 321 -- -- -- -- 7 -- -- -- --
LANES -- 321 1 1 -1 -- -- -- -- -1
DISTANCE -- 321 1 1 -1 -- -- -- -- -1
SPDCLASS -- 321 2 2 -2 -- -- -- -- -2
CAPCLASS -- 321 1.23 1.23 -1.23 -- -- -- -- -1.23
NAME -- 321 -- -- -- -- -- -- -- --

The 1=2 column lists the number of records where the records are the same. The 1<2 set
of columns lists the number of records where the values for the listed variables are lower
in file 1 than in file 2, and the 1 > 2 set lists the summary where file 1 values are greater
than file 2, The final AVE column lists the average difference for the variable, using only
records where there is a difference. The Min and Max differences show the range of
differences for the variable.
Network Program > Control statements > COMPARE > Example 2

Exam ple 2
RUN PGM=NETWORK
NETI=NET1.NET, NET2.NET
NETO=NET3.NET
MERGE RECORD=T
PHASE=LINKMERGE
COMPARE RECORD=1-2, LIST=20 ; compare link record 1 with 2
IF (_COMPARE=-2) CMPFLAG=1 ; link in NET1, not in NET2
IF (_COMPARE=-1) CMPFLAG=2 ; link in NET2, not in NET1
IF (_COMPARE>0) CMPFLAG=3 ; link in both but different
ENDRUN

Example 2 illustrates how to use _COMPARE to flag the links in the merged network. The
CMPFLAG attribute can be used in selection expressions in Viper to post the
comparison results.
Network Program > Control statements > CONTINUE

CONTINUE
Immediately jumps to the end of a loop, bypassing all stack statements until the
associated end of loop. If it is within a loop, control passes to the appropriate ENDLOOP
statement. Otherwise (not in a loop), stack processing for the record is terminated.
Network Program > Control statements > CONTINUE > Example

Exam ple
LOOP _L1=1,3
IF (!(condition)) CONTINUE
ENDLOOP
IF (condition) CONTINUE ; no more processing for this data record
LOOP _L2=_K1,_K2,_KINC
LOOP _L3=_L2,_L2+5
IF (condition) CONTINUE ; jump to ENDLOOP for _L3
ENDLOOP
ENDLOOP
Network Program > Control statements > CROSSTAB

CROSSTAB
Cross tabulates variables. Keywords and subkeywords include:
• COL
m RANGE

• COMP
m FORM

• R OW
m RANGE

• VAR
m FORM

Use the CROSSTAB control statement to accumulate a tabular summary from the network.
Use the VAR keyword to specify the variables you want tabulated. Use the ROW keyword
along with the RANGE subkeyword and the COL keyword along with the RANGE
subkeyword to specify the table’s dimensions. If you omit either ROW or COL, the report
collapses into only one column or one row. Although the CROSSTAB statement can
include several instances of the VAR keyword, the statement tabulates all the variables to
the same specifications. Use the COMP keyword to generate additional reports after
network generation using the values from the tabulated variables. For example; if the
statement includes VAR = VehDist, VehTime, then including COMP = VehDist / VehTime
would produce a table of average speeds.

NOTE: The program does not automatically produce totals because your ranges may
overlap. You can produce totals and subtotals with appropriate use of RANGE values.
See below for a description of the process used in placing values in the appropriate
range slots.

CR OS S T A B k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

COL |S| Name of the variable that will be

used for the column definition of the
report.

COL RANGE |RV50| Same as for ROW (RANGE), but

applies to the COL variable. Care
should be taken to not cause the
reported line to be too long (limit the
number of column ranges).

COMP |NV| Expression that can be used to

generate a report that is some
combination of the reports generated
by the VAR variables on this
 statement. The only variable names
that may appear in the COMP
expressions are the VAR variables
that are on this statement. There may
be up to ten COMP expressions on a
statement.

COMP FORM |S| Specifies the format for the COMP

reports. The standard Cube Voyager
FORM syntax is used. If FORM is not
coded for any COMP, the program
will supply “7cs.” The format applies
to the COMP that it is coded with, and
to all subsequent COMP variables
until a new value is encountered. The
first format will be backfilled to apply
to any prior COMP variables

ROW |S| Name of the variable that will be

used for the row definition of the
report.

ROW RANGE |RV50| Series of ranges (and increments) for

stratifying the row variable for use in
the report. A range as either one, two,
or three numbers. If more than one
number, the values are separated by
dashes. The three values are low,
high, and increment. The program
establishes ranges for stratifying the
ROW variable values. Each range
has a lower limit, an upper limit, and
an increment. If there is no upper limit,
the program makes the upper limit
equal to the lower limit. If there is no
increment, the program assumes
one row. If there is an increment, the
program generates a row for each
increment, starting at the lower limit,
and progressing until the upper limit
is reached. There are certain
problems associated with stratifying
non-integer data; they are discussed
below.

VAR |SV10| Name(s) of the variable(s) that are to

be tabulated. The value of each
variable will be accumulated into the
cells of the generated table(s). A
separate report will be generated for
each variable named. There may be
up to ten VAR keywords on a
statement.

VAR FORM |S| Format to use when printing the

accumulated values in the table. The
standard Cube Voyager FORM
syntax is used. If FORM is not coded
for any VAR, the program will supply
“7cs.” The format applies to the VAR
that it is coded with, and to all
subsequent VAR variables until a
new value is encountered. The first
format will be backfilled to apply to
any prior VAR variables.
Network Program > Control statements > CROSSTAB > Range classification strategy

Range classificatio n strategy

The ROW RANGE and COL RANGE values are stored as single-precision numbers, and the
actual variable values are computed and stored as double-precision floating-point
numbers. Single precision provides accuracy to about six, or seven, significant digits,
whereas double precision provides accuracy to up to fifteen, or sixteen, digits. Because
computers do arithmetic on a binary basis, numbers which seem to be easily described
in base 10 cannot always be represented exactly in the computer. For example: the
number 0.01 is a definite number in base 10, but it can only be approximated in base 2.
If the program compares a variable to a range limit, it might fail due to this limitation of the
computer. The comparison result may differ, depending upon the floating point
capabilities of the computer.
Another concern is the definition of limits. If RANGE is 1-10, should a value of
0.9999999999 be included in it? If RANGE is 1-10-1, should a value of 10.001 be
included, and which range should the value of 2.0001 fall into? To address all these
concerns, the program is designed to check for RANGE satisfaction based upon an
integer representation of both the RANGE limits and the data.
You can control the level of precision when specifying the RANGE values. The level of
precision is set by the maximum number of decimal places in any of the RANGE values
(low-high-increment). The RANGE values and the ROW and COL variable values are
factored and integerized (rounded) according to the decimal digits. If a single RANGE (no
increment) is used, the program checks the value against the limits as: if the value is
greater than, or equal to, the lower RANGE, and less than, or equal to, the higher value,
the value satisfies the range. If a RANGE with an increment is used, a similar initial check
is made to determine if the value fits within the outer RANGE limits. If the value fits with the
range, the increment index is computed (in integer) as: ((value-lo) / inc) + 1.
Examples may best illustrate this process.

Inte rna l Inte g e r

R A N GE R a ng e V a lue V a lue Ind e x

1-10 1-10 0.99 1 --

1-10-1 1-10-1 1.50 2 2

1-10-1 1-10-1 1.45 1 1

1-10-1.0 10-100-10 1.45 15 1

1-10-0.5 10-100-5 1.45 15 2

1-3-0.5 10-30-5 3.00 30 5

1-3-0.3 10-30-3 1.29 13 2

1-3-0.3 10-30-3 3.01 30 7

1-3-0.3 10-30-3 3.001 30 7

There is a caveat with this process. The maximum integer revised value for either RANGE
or ROW is 2,147,483,647. For this reason, the program may adjust the number of decimal
digits if either RANGE limit would exceed the maximum after revising.
Network Program > Control statements > CROSSTAB > Example

Exam ple
CrossTab VAR=DIST, _CNT,
ROW=VC, RANGE=0.5-1.2-0.1, 0.5-1.2, 1.2-2.5-0.5, 2.5-9999,
COL=LANES, RANGE=1-7-1, 1-3, 4-7, 1-7, 1-100-5,
CrossTab VAR=VMT FORM=6.1c, VAR=VHT, FORM = 6.2c,
ROW=CLASS, RANGE=1-50-1,
COL=LANE, RANGE=1-10,
COMP=sqrt(VMT)+10*(min(1000,VHT)),
COMP=VMT / VHT,
FORM=8.3 ; weird example & ave trip length
Network Program > Control statements > DELETE

DELETE
Deletes data record.
When a data record is being subjected to the operations in a phase block, and the
operation is DELETE, the remainder of the block operations are bypassed, and the record
is removed from the network. Most likely, DELETE would be used in conjunction with an IF
statement.
Network Program > Control statements > DELETE > Example

Exam ple
If (a=2150-2199 || b=2150-2199) DELETE
;remove all links connected to nodes 2150-2199
Network Program > Control statements > EXIT

EXIT
Exits current phase.
Use EXIT to exit the current phase. The remaining input records to the phase will not be
read.
Network Program > Control statements > EXIT > Example

Exam ple
IF (a > 1000) EXIT; no reason to process beyond this link.
Network Program > Control statements > FILEI

FILEI
NOTE: See “FILEI” on page 50 for general information about FILEI and for important
limitations when using Application Manager.

FILEI inputs data files. Keywords and subkeywords include:

• GE OMI

• LIN KI
m COMBINE
m DETAILS
m EXCLUDE
m RENAME
m REV
m SELECT
m START
m STOP
m TRIPSXY
m VAR

• LOOKU P I

• N E T I — Alias for LINKI, above

• N OD E I — Uses the same subkeywords as LINKI (above), except REV and TRIPSXY

The FILEI statement specifies the input files that contain the network data. You may
designate up to ten NODEI, ten LINKI and ten GEOMI files in a FILEI statement (GEOMI
support GIS inputs; see next page).
Upon recognizing a LINKI file as a binary file, the program automatically assumes a
corresponding NODEI file. To preclude the program from using the node data in the
automatic NODEI file (not recommended), provide a NODEI file with the same index as the
LINKI file. NODEI files that have the same index as a binary-network LINKI file must
precede the LINKI file.
On the other hand, you may list non-binary LINKI and NODEI files in any order. Cube
geodatabase networks have associated link and node stand-alone feature classes. If a
LINKI file is a Cube geodatabase network, the automatic corresponding NODEI file is the
network’s node stand-alone feature class.
Upon reading input files, the program truncates field names longer than 15 characters. If
truncation results in duplicate field names, the program automatically renames fields to
avoid duplicate names.
If you code value limits for a variable (with MIN=, MAX=), the program only checks those
limits during the INPUT phase. If the limits are exceeded, the program rejects the record
as an error and does not process the record. The program does not edit input record
keys before stack processing. You can decide how to handle records with invalid keys.
After stack processing, the program ensures that key values range from 1 to the number
of nodes. If a key is outside this range, the program lists the record as an error. If the
input file contains many extraneous records (invalid data records—possible if coming
from a GIS DBF with extra data), you can check the key (N, A, or B ) and DELETE the
record, or recode the key.
NETWORK also includes the GEOMI keyword to input Shape and Geodatabase
geometry sources. GEOMI has three advantages over using LINKI as geometry source:
1. It eliminates the need to read and merge a GDB network into the final network if it is
needed as a geometry source only.

2. It allows using shape files as geometry source since LINKI does not allow shape files as
input.

3. It will not merge the data fields or data records into the base network because it is not a
LINKI.

FILE I k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

GE OMI |KFV10| Input file(s) to NETWORK to act as link

geometry source for output GDB networks
and shape files. GEOMI may be indexed
with up to ten shapefile (*.shp) or
Geodatabase sources.
The GEOMI index can be 1, even when
there is already a LINKI[1] specified. If there
is a LINKI GDB network and a GEOMI
GDB/SHP specified with the same index,
the GEOMI data will be used as the
geometry source — thus it will override
LINKI if both are specified.
The source of the link geometry is
specified in the LINKMERGE phase by
setting the GEOMETRYSOURCE variable.
For an example of usage, see Example 2.
NOTE: You can force Network to search a
geometry source in both the forward and
reverse directions. This is useful for
matching 1-way links with their
corresponding geometries coded in the
reverse direction. Simply list the file twice
as the first two GEOMI inputs.
GEOMETRYSOURCE must be unspecified or
2. Network will search first in one direction,
and if the link match is not found, it will
check the opposite direction.

GEOMI AFIELD |S| A node field name. Default is 'A'.

GEOMI B FIE LD |S| B node field name. Default is 'B'.

GEOMI SEQFIELD |S| True shape sequence number field name.

Default is none.

LINKI |KFV10| Name of file or files that contains link-based

records (may be indexed up to ten files).
The file format can be:
• ASCII

• DBF
• MDB data table
• Cube geodatabase network
• Link stand-alone feature class in a
geodatabase network
• Recognized binary network.
The program will try to detect what type of
file it is. If it cannot identify the file as a DBF,
MDB, Cube geodatabase network, or a
binary network, it will assume ASCII. If it
detects that the file is a MINUTP binary
network, the variables DIST, SPDC, CAPC,
and LANE will automatically be renamed to
DISTANCE, SPDCLASS,CAPCLASS, and
LANES, respectively.
Since most applications will input binary
networks or Cube geodatabase networks,
you can use the keyword NETI as an alias
for LINKI. If the LINKI file and the NODEI file
are DBF or MDB format then at a minimum,
the LINKI file must have a field named A
and a field named B and the NODEI file
must have a field named N. If these fields in
the DBF or MDB do not use this naming
convention, then the RENAME keyword
below can be used to rename the variables
on input.
NOTE: A valid network in Cube
Voyager/TP+ need not have coordinate
variables on the node records. If the
network is to be viewed/edited in Cube then
it must have variables named X and Y on
the node records to hold the coordinate
data.

LINKI COMBINE |?| Flag that indicates whether multiple link or

node records exist on the input data file.
The following subkeywords can be used to
specify how to combine attributes values
across multiple link or node records.
FIRST, LAST, AVE, SUM, MAX, MIN, CNT,
AVEX0
The descriptions of these keywords are
identical to those described for the MERGE
statement.
The default for any variables not combined
will be consistent with the value of
PARAMETERS REPL_DUPL. If REPL_DUPL
is true, the unlisted vars will be set to LAST,
otherwise to FIRST.
 Example of usage:
FILEI LINKI=linki.dat, vars=
v1,v2,v3,v4,v5,v6,v7,v8
combine=t, ave=v1,v3,v4
ave=v6,v8

FILEI NODEI=node.dat,
vars=n,x,y, combine=t, first=x,
last=y

LINKI DETAILS |?| Flag that indicates if you would like to keep
the full iteration results from an input loaded
Tranplan network on the output file and
have the iteration specific attributes
available as li. variables during the run.

LINKI EXCLUDE |SV| Name(s) of variable(s) excluded from the

file. Only relevant if the file is a DBF or
binary network file and you do not want
certain variables from the file, or if the input
is defined as a series of variables (in
delimited format -- not with BEG/LEN), and
you do not want to extract certain variables
from the input records.

LINKI RENAME |SP| Use to rename a variable from the input file.
The format is RENAME=oldname-
newname; both names must be specified.
Names can be swapped on one statement;
to swap names for V1 and V2:
RENAME=V1-temp1,V2-V1,temp1-V2

LINKI REV [I| Parameter that can be used in conjunction

with files that are ASCII or DBF to specify if
an input record is to represent a single
directional link or if it is to be considered as
two links (A-B and B-A, with the B-A values
being the same as the A-B values). Under
normal conditions, an input record
represents a single directional link from A
to B. The REV parameter is used only if:
• There is no REV variable on the
record.
• There is a REV variable on the
record, but its value is neither 1 nor 2.
If there is a VAR=REV defined for the link
data records, the value of the REV should
be a 1 or a 2. If the value is not a 1 or a 2,
the reversibility of the link is determined by
the value assigned to this keyword. The
only valid values for this keyword are 1 and
2; the default is 1. The record variable
defined as REV will be treated as any other
link variable, but it will not be written to the
output network (the NETO will not contain a
variable named REV).

LINKI SELECT [s] Used only with ASCII input when it is

desired to select only certain records from
the file. The syntax is the same as for
START. SELECT is processed after any
STOP statement, and before any editing.
LINKI START [s] Used only with ASCII input where the first
valid data record follows some identifying
header record. The expression value must
be enclosed within parenthesis (), and the
only valid variable is RECORD, which is the
actual data record. The primary purpose is
to allow the user to specify that there is a
header, and how to identify it. The
expression should contain a SUBSTR
function to extract the header. START is
used to position the file before actual data
records are read.

LINKI STOP [s] Used in a manner similar to the START

keyword, but is associated with a trailer
record. STOP is processed immediately
after a record is read, and before any field
editing.

LINKI TRIPSXY [F] Name of a file that contains TRIPS X-Y

data. This keyword is only required for
TRIPS networks.

LINKI VAR |SV| Name of a variable to be extracted from the

file. Name lengths may not exceed 15
characters; case is ignored.
To read variables from fixed-format text
files, use the BEG and LEN subkeywords.
To read character-string variables from
free-format text files, use the subkeywords
TYP and LEN, or append (C) or (Cn) to
the variable name, where n specifies the
number of characters.
To read character-string variables from
fixed-format text files, use the TYP, BEG, and
LEN subkeywords.
If the file is ASCII, and the variable is to be
extracted from specific positions on each
file record, BEG and LEN will have to be
specified. The program assumes that
ASCII files are free format and all fields are
separated by white space, a comma, or
some combination of both. Examples of
free-form records:
1 2 3
1,2,3
1 , 2 3
1 ,2,3
All four of the above illustrated records
contain three fields: 1, 2, and 3.
Subkeywords of VAR include:
BEG |I|
Designates the beginning of the
field in the input records. The first
column of the record is designated
as 1.
LEN |I|
Designates the length of the field
that begins at position BEG.
TYP |S|
 May be used to specify that the
format of the variable is not
numeric. An “A” means that the
variable is alphanumeric. If TYP=A
is specified for free format input, the
LEN must also be specified, or it
will default to 1. TYP A variable
values on free format input must be
enclosed within quote or literal
marks ('...' or "..."), if they contain
special characters (other than
alphanumeric characters: a-z, 0-9).
MIN |R|
May be used to specify a minimum
allowable value for the field. If the
input value of the variable is less
than this value, the variable will be
rejected as an error.
(continued)

LINKI VAR VAR may also be specified with

(continued) parameters directly (without the above
subkeywords). If the field following the
variable name is a number, this format is
automatically triggered. The total format is
name,beg,len,min,max,typ. All these fields
must be numeric, or null. A null field is
specified by coding two commas with
nothing between them. The parameter list is
considered as exhausted when a non-
numeric field is encountered. Typ must be
coded as 1 to indicate that the variable is to
be an alphanumeric field.
Example: VAR=A,1,5,B,6,5 (A is in
columns 1-5 and B is in 6-10). If the first two
numbers that follow the name are
separated by a dash, the numbers indicate
the actual columns of the data record where
the field is located.
For example: VAR=A,1-5,B,6-10 (A is in
columns 1-5, and B is in columns 6-10). If
both forms may be used to specify variable
(numeric format, followed by any of the sub-
keywords); the keyword values will
override the positional numbers

LOOKUPI |FKV999| Name of file containing records for a

lookup function implemented with the
LOOKUP control statement.
Equivalent to the FILE keyword of the
LOOKUP control statement. You must index
LOOKUPI.

NET I |KFV10| Alias for LINKI.

NODEI |KFV10| Name of a file or an MDB and element that

contains node-based records.
NODEI may take a standalone node
shapefile as an input. The shapefile must
have an associated DBF file. NETWORK
will create a new DBF with all fields and
data as the original shapefile. It will also
add X&Y fields to contain the associated
point coordinates.
See “LINKI” on page 436 for comments
regarding file detection. NODEI uses the
same keywords as LINKI except REV and
TRIPSXY.
Example:
RUN PGM=NETWORK
FILEI LINKI[1]="LINKS.DBF"
FILEI NODEI[1]="NODES.SHP"
; shape file should include the
node number
; field 'N' must be specified
FILEO NETO="HIGHWAY.NET"
ENDRUN
Network Program > Control statements > FILEI > Example 1

Exam ple 1

This section contains some examples of FILEI LINKI and FILEI NODEI usage.
LINKI[1]=\demo\demo20.dat exclude=dist,tsin ; file is binary network
NODEI[1]=C:\DEMO\DEMOXY.DAT VAR=N,X,Y ; file is ASCII
NODEI[2]=\demo\demo21.dat,
LINKI[2]=\demo\?07.dat,
var=a,beg=1,len=5,
var=b,beg=6,len=5,
var=dist,beg=14,len=4,
var=rev,beg=35,len=1
LINKI[3]=freeform.fil, VAR=a,b,name,21,5,,,1,section,0,5
;section follows name in free form
nodei[4]=c:\citya\nets\linka.dbf, linki[4] = c:\citya\nets\nodea.dbf
LINKI[8]=Mixed_Node_and_Link.lxy, var=a,b,distance,
start=(substr(record,1,2)=='LD'),
stop=(substr(record,1,2)=='XY')
NODEI[8]=Mixed_Node_and_Link.lxy, var=n,x,y,
start=(substr(record,1,2)=='XY'),
stop=(substr(record,1,2)=='LD')
Network Program > Control statements > FILEI > Example 2

Exam ple 2

This example specifies a shapefile Geometry source, then link and node shape outputs
matching that geometry. The associated DBF file will be from the LINKO/NODEO
process. Note that the GEOMI index is 1, even with LINKI[1] specified. The GEOMI data
will be used as the geometry source.
RUN PGM=NETWORK
FILEI LINKI[1]="2005HWYLOAD.NET"
FILEI GEOMI[1]="SHAPES\LINK3.SHP"
FILEO LINKO="SHAPES\LINK4.SHP" FORMAT=SHP INCLUDE=A,B,DISTANCE,CAPACITY,SPEED,TIME
FILEO NODEO="SHAPES\NODE4.SHP" FORMAT=SHP
phase=linkmerge
GEOMETRYSOURCE=1
ENDRUN
Network Program > Control statements > FILEO

FILEO
Generates output files—a network file, link file, and node file. Keywords and subkeywords
include:
• LIN KO
m DELIMITER
m EXCLUDE
m FORM
m FORMAT
m INCLUDE
m VARFORM

• NET O
m EXCLUDE
m FORMAT
m INCLUDE
m LEFTDRIVE

• N OD E O
m Uses the same subkeywords as LINKO (above).

• P R IN T O
m APPEND

FILE O k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

LINKO |KF| Name of a non-Cube Voyager output file

in which the program writes link records.
May be any of the formats described by
the FORMAT subkeyword, or otherwise, a
geodatabase/element name. This is a
Cube geodatabase network, or table,
stored in an MDB file (personal
geodatabase) or GDB (file
geodatabase). Designate the file name
followed by a backslash and the Cube
geodatabase network/table name.
NOTE: Networks stored in personal (MDB)
geodatabases are limited to a maximum
of 255 fields, including the default
geodatabase network fields (OBJECTID,
SHAPE, SHAPE_LENGTH, A, B,
GEOMTERYSOURCE, etc).

LINKO DELIMITER |S| Character used as the delimiter in SDF

and TXT files. To specify special
characters (, - / + * = ;), enclose within
 quote marks or specify using its decimal
equivalent (for example, tab is code 9).
The default value is a comma; but there is
no default value for TXT files.

LINKO EXCLUDE |SV| Similar to EXCLUDE under NETO.

LINKO FORM |S| Sets the print format of all variables written
to the file. Usually specified as w.d to
indicate the maximum field width and
number of decimal places to preserve.
See “Defining a numeric print format” on
page 74 and “Defining a character print
format” on page 76. Optional format codes
are usually not appropriate for use on this
statement.

LINKO FORMAT |S| Sets the file format of the LINKO file.
Possible values are:
• TXT — File of ASCII records in which
all the data fields are written in a
fixed format
• SDF — File of ASCII records in which
the data fields are written in variable
length, and separated by a delimiter
• CS1 — File of comma separated
values with one header row. The
header row contains comma
separated field names.
• CS2 — File of comma separated
values with two header rows. The
first header row contains two comma
separated values [number of fields
and number of records] and the
second header row contains
comma separated field names.
• DBF — Industry-standard database
file
If there is a ? in the name, and there is
no filename extension to the LINKO
value, an extension of this value will
be appended to the filename. If a DBF
is written, and a designated FORM
does not provide adequate width and
decimal space for a field value, the
program will try to adjust the field form
within typical database rules to fit the
value into the field space.
• SHP — Industry-standard shapefile.
The file extension must be .shp.
NETWORK will write the shape file
with geometry from the geometry
source(s) but the associated DBF file
will be from the LINKO process. This
will allow using the INCLUDE and
EXCLUDE keywords to limit the fields
written to the shape file DBF.
When an associated node shapefile
is specified using LINKO NODEO
FORMAT=SHP, it must reside in the
 same folder as the link shapefile.
Otherwise, both files will be
consolidated to the LINKO folder.
For more on usage with the SHP
FORMAT, see Example 2.

LINKO INCLUDE |SV| See INCLUDE under NETO. INCLUDE

variables may have a format appended
to their names in a manner similar to
VARFORM. The same variable may be
included multiple times.
When used with INCLUDE, a script’s output
network file (LINKO) must be created after
linking its input network file (LINKI or NETI
).

LINKO VARFORM |SV| Sets the format for specific variables.

Specify a variable name with its desired
format appended in parenthesis. For
example, VARFORM=A(4.0), B(4.0)
sets A and B to be formatted as 4
characters wide with no decimal places. If
the file format is SDF, the program deletes
leading spaces. Only specify this
keyword for variables that require specific
formats.
When setting a variable’s format, the
program first determines a default format.
Then, the program applies the formats as
they appear on the statement. Therefore,
if the same variable appears with both a
VARFORM subkeyword and an INCLUDE
subkeyword, the latest appearance
prevails. Similarly, the latest FORM
prevails for any variables not explicitly
named in a VARFORM and/or INCLUDE
subkeyword.

NETO |KF| Name of the standard output network that

the program writes. The NETO can be a
binary Cube Voyager/TP+ network.
Alternatively, NETO can point to a Cube
geodatabase network stored in an MDB
file (personal geodatabase) or GDB (file
geodatabase) by designating the file
name followed by a backslash and the
Cube geodatabase network name.
NOTE: Networks stored in personal (MDB)
geodatabases are limited to a maximum
of 255 fields, including the default
geodatabase network fields (OBJECTID,
SHAPE, SHAPE_LENGTH, A, B,
GEOMTERYSOURCE).

NETO EXCLUDE |S| List of variables excluded from the output

network. Listed variables that exist in both
node and link records are excluded from
both records. To exclude a variable from
only the link records, add the LO. prefix to
the variable name. To exclude a variable
from only the node records, add the NO.
prefix to the variable name. Cube
Voyager ignores listed variables that do
 not exist in any of the input files, and does
not issue a warning.
Do not use with the INCLUDE subkeyword.

NETO FORMAT |S| Specifies the file format for writing the
output network. Normally, this is not
specified; the program will write the file as
a standard Cube Voyager binary network.
If the NETO keyword specifies an
MDB/element name, the program writes
the output as a Cube geodatabase
network in the MDB file under the element
name. The program also creates two
stand-alone feature classes in the MDB
file, element_Node and element_Link, and a
table, element_SPDCAP, that contains the
indices and values from the internal
speed and capacity table. The output
Cube geodatabase network will contain
the additional link and node attribute,
GEOMETRYSOURCE, which contains the
input file number from which the geometry
will be applied (for more information on
GEOMETRYSOURCE see “Built-in
variables” on page 417).
Specify FORMAT=MINUTP to write a
MINUTP network. MINUTP string
variables are truncated to 80 characters.
Specify FORMAT=TRIPS
TRIPSXY=fname to write a TRIPS
network and its associated XY file.

NETO INCLUDE |S| List of variables included in the output

network. If you use this subkeyword, the
output network only includes the listed
variables.
When INCLUDE is used, the FILEO NETO
statement should be declared below the
FILEI LINKI statement.
Example 1
FILEI
LINKI[1]="C:\MYMODEL\INPUT.NET"
FILEO
NETO="C:\MYMODEL\OUTPUT.NET",
INCLUDE=LANES
In the case of Application Manager,
create the NETO file reference before
creating the LINKI/NETI reference. This
will make the NETI/LINKI and NETO
statements appear in the order discussed
above.
Do not use with EXCLUDE subkeyword.

NETO LEFTDRIVE |?| Flag that indicates whether the program

writes a flag in the output network file to
indicate whether vehicles drive on the left
in the network. This is primarily for use in
JUNCTION modeling in the Network
program; it does not have any affect on
any PLOT statements in Network. This
keyword is not necessary if the lowest
numbered LINKI file had the LEFTDRIVE
 parameter set, or if PARAMETERS
LEFTDRIVE is specified. The setting of the
NETO value follows the rules:
• If PARAMETERS LEFTDRIVE is
specified, use that value
• Else if NETO LEFTDRIVE is
specified, use that value
• Else if lowest LINKI contains a
LEFTDRIVE value, use that value

• Else do not set this value

NODEO |KF| Name of a non-Cube Voyager output file

in which program writes node records. Its
subkeywords are the same as those for
LINKO.
May be any of the formats described by
the FORMAT subkeyword under the
LINKO keyword, or may be an
MDB/element name.
NOTE: Networks stored in personal (MDB)
geodatabases are limited to a maximum
of 255 fields, including the default
geodatabase network fields (OBJECTID,
SHAPE, N, GEOMTERYSOURCE, etc).

PRINTO |KF| Name of the file where the program

directs output from a PRINT statement
using PRINT PRINTO=#.

PRINTO APPEND |?| See APPEND under “PRINT” on page 69.

The program produces output files by combining data from the input files. Use the
MERGE statement to specify how to process duplicate records. Unless you specifically
exclude fields with the EXCLUDE subkeyword, the output files will contain the fields from
all the input files, even if you do not merge the files and the output file contains no data
from a particular input file.
When writing output files, the program generates an output network first even if NETO is
not specified. The program derives both LINKO and NODEO from the output network; the
link and node files are subsets of the output network. Consequently, if you specify NETO
and exclude a link variable, then that link variable will not be available for LINKO.
Network Program > Control statements > FILEO > Example 1

Exam ple 1
FILEO NETO=MY.NET
NETO=DEMOMINU.DAT, FORMAT=MINUTP, EXCLUDE=TEMP1, TEMP2
NODEO=TEXTNODE FORMAT=TXT, FORM=8.0 INCLUDE=A,B,DIST,SPEED,SPDCAP(2)
LINKO=LINK FORMAT=DBF VARFORM=VC(6.3)
Network Program > Control statements > FILEO > Example 2

Exam ple 2

This example specifies a shapefile Geometry source, then link and node shape outputs
matching that geometry. The associated DBF file will be from the LINKO/NODEO
process.
RUN PGM=NETWORK
FILEI LINKI[1]="2005HWYLOAD.NET"
FILEI GEOMI[2]="SHAPES\LINK3.SHP"
FILEO LINKO="SHAPES\LINK4.SHP" FORMAT=SHP INCLUDE=A,B,DISTANCE,CAPACITY,SPEED,TIME
FILEO NODEO="SHAPES\NODE4.SHP" FORMAT=SHP
phase=linkmerge
GEOMETRYSOURCE=2
ENDRUN
Network Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF

IF ... ELSEIF ... ELSE ... ENDIF

Performs certain operations based on conditions.
Code IF condition blocks like standard Cube Voyager specifications. Enclose the IF and
ELSEIF selections within parenthesis; the selections can reference any variables that are
valid for the current phase. See “IF ... ELSEIF ... ELSE ... ENDIF” on page 54 for more
details.
Network Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF > Example

Exam ple
PHASE=INPUT, FILE=NI.1
IF (N==5)
.
ELSEIF (N=1,3, 8-42 && X<3000 || Y=1-500,800-900)
.
ELSE
.
ENDIF
ENDPROCESS
IF (I < (K*3/6 +J) ) DELETE
Network Program > Control statements > LOOP ... ENDLOOP

LOOP ... ENDLOOP

Controls a general variable loop.
LOOP LVAR=Lbeg,Lend,Linc ;
...
ENDLOOP

where:
• LVAR is the name of the loop control variable. LVAR is not protected during the loop;
computational, program, and other LOOP statements can alter its value. LVAR must be
followed by Lbeg, and optionally, by Lend and Linc.

• Lbeg is a numeric expression that initializes LVAR.

• Lend is a numeric expression that is computed and stored when the LOOP statement is first
processed. LVAR is incremented by Linc, and compared with Lend when the ENDLOOP
statement is processed. If Lend is not specified, it is assumed no comparison is to be made
(rather meaningless loop).

• Linc is a numeric expression that is computed and stored when the LOOP statement is first
processed. The value is added to LVAR before the ENDLOOP comparison is made. If Linc is
not specified, it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend; a
backwards loop).

NOTE: All variables

in a LOOP statement expression (Lbeg, Lend, Linc) must begin with
the underscore character ‘_’ to prevent confusion with record variables.

Use LOOP…ENDLOOP blocks to repeat of a series of statements. LOOP initializes a

variable(LVAR); ENDLOOP compares the contents of the variable to another value
(Lend), and branches back to the statement following the LOOP statement if the
comparison fails. LOOP blocks may be nested; they may not overlap IF blocks. The logic
is as follows:
• At LOOP:
m
Initialize LVAR to Lbeg.
m
Compute the value for Lend.
m
Compute the value for Linc (default to 1 if missing).
m
Proceed to next statement.

• At ENDLOOP:
m
If Lend not specified, jump to next statement.
m
Add Linc to LVAR.
 m
Compare LVAR to Lend.
m
Either jump back to statement following associated LOOP, or drop through.

The Lend and Linc variables are processed somewhat differently than in the other
programs; they are computed at the LOOP statement and can not be modified by other
statements. This helps to protect against possible endless loops. The loop will be
processed at least one time regardless of Lend and Linc values. Most uses will involve
constants. Because LVAR values can be expressions, Lbeg, Lend, and Linc must be
separated by commas (standard white-space delimiting cannot be interpreted properly).
If an expression is used, it is suggested that it be enclosed in either parentheses or
quote marks.
Network Program > Control statements > LOOP ... ENDLOOP > Example

Exam ple
LOOP _pass=1,10 ; perform 10 passes
...
ENDLOOP

LOOP _xyz=_abc*_def,_ghi+_jkl,_mno/_pqr
LOOP _abc=_xyz,_xyz+2,2 ; nested LOOP
...
ENDLOOP
ENDLOOP

LOOP _jj=10,3,-2.5 ; perform 3 passes -- 10, 7.5, 5.0

...
ENDLOOP
Network Program > Control statements > MERGE

MERGE
Specifies record and variable merging. Keywords include:
• R E COR D

• AVE

• A V E X0

• CN T

• FIR S T

• LA S T

• MA X

• MIN

• SUM

Use MERGE to specify how to merge records from different files, and how to combine
variables in a merged record. Note that merging records and combining variables are
independent processes.
Use the RECORD keyword to indicate whether to merge data in duplicate records when
encountering identical keys during the NODEMERGE or LINKMERGE phases.
Use the other keywords to specify the method for determining data values for specific
variables when merging data in duplicate records from different input files. (Duplicate
records from the same file may not occur in the MERGE phase.) Each resulting record
will have a cell for every variable specified in any input file or any COMP statement.
ME R GE k e y wo rd — s e le c ting re c o rd s

Ke y wo rd D e s c rip tio n

RECORD |?| Flag that indicates whether to merge

duplicate records:
• False — Include only the records that
exist in the FILEI with the lowest index
[].
• True — Default value. Include any
unique record included.
If you input two networks (NETI[1] and
NETI[2]) and RECORD=FALSE, the program
only processes the links that are in NETI[1].

Use the following keywords to indicate how to obtain the value of variables when
merging records. The program only obtains variable values from file records that contain
the variable. Only list a variable with one keyword; the program uses the FIRST keyword
for variables not listed with any keyword.
 ME R GE k e y wo rd s — te c hniq ue

Ke y wo rd D e s c rip tio n

AVE |SV| Average of all records.

AVEX0 |SV| Average of all records, where the value

from the file records is not 0.

CNT |SV| Count of the records that contain the

variable.

FIRST |SV| Directly from the record from the FILEI with
the lowest index[].

LAST |SV| Directly from the record from the FILEI with
the highest index [].

MAX |SV| Maximum value of all the records.

MIN |SV| Minimum value from all the records.

SUM |SV| Sum of all the records.

Network Program > Control statements > MERGE > Example

Exam ple
MERGE RECORD=TRUE FIRST=CAPCLASS,SPDCLASS, LAST=LANES, AVE=DISTANCE,
SUM=COUNT

Illustration for sample input files (-- indicates variable not defined for file):
FILEI LINKI[1]=FILE1,VAR=A,B,DISTANCE,SPDCLASS,CAPCLASS,LANES
FILEI LINKI[2]=FILE2,VAR=A,B,COUNT
FILEI LINKI[3]=FILE3,VAR=A,B,DISTANCE,LANES

LINKI[] A B DISTANCE SPDCLASS CAPCLASS LANES COUNT

1 101 102 10.1 11 11 1 --
1 105 106 12.5 12 12 3 --
2 101 102 -- -- -- -- 1000
2 102 103 -- -- -- -- 1000
3 101 102 11.5 -- -- 2 --
3 102 103 12.6 -- -- 2 --
3 104 105 1.0 -- -- 3 --

Order as seen in LINKMERGE, after being processed in the INPUT phase.

LINKI[] A B DISTANCE SPDCLASS CAPCLASS LANES COUNT

1 101 102 10.1 11 11 1 --
2 101 102 -- -- -- -- 1000
3 101 103 11.5 -- -- 2 --
2 102 103 -- -- -- -- 2000
3 102 103 12.6 -- -- 2 --
3 104 105 1.0 -- -- 3 --
2 105 106 12.5 12 12 3 --
MERGE RECORD=FALSE ; Resulting file:

A B DISTANCE SPDCLASS CAPCLASS LANES COUNT

101 102 10.1 11 11 1 1000
105 106 12.5 12 12 3 0
MERGE RECORD=TRUE FIRST=COUNT, AVEX0=DISTANCE
; Resulting file:

A B DISTANCE SPDCLASS CAPCLASS LANES COUNT

101 102 10.8 11 11 1 1000
102 103 12.6 0 0 2 2000
104 105 1.0 0 0 3 0
105 106 12.5 12 12 3 0
Network Program > Control statements > PARAMETERS

PARAMETERS
Specifies basic parameter values. Keywords include:
• LE FT D R IV E

• LIS T _E R R S

• MA X_IP _E R R S

• N OD E S

• R E P L_D U P

• S H A P E A N GLE

• S OR T A N GLE

• ZON E S

P A R A ME T E R S k e y wo rd s

Ke y wo rd D e s c rip tio n

LEFTDRIVE |?| Used to force a LeftDrive switch into

the NETO. By default, this value is not
set. See FILEO NETO LEFTDRIVE in
“FILEO” on page 442 for more
details.

LIST_ERRS |KI| Specifies how many records with

data errors will be listed before
turning off the error listing. Default
value is 20.

MAX_IP_ERRS |KI| Specifies how many records with

data errors are allowed. If this value
is exceeded, the program will
terminate with a fatal condition.
Default value is 20.
Records with errors are not skipped,
unless the error is in the key (for
example, node number). The bad
fields will be set to 0, unless the error
is a limits error.

NODES |KI| Specifies the highest node number

to be allowed in the network. This
need not be specified (by default,
the program detects the highest
number); but if it is specified, any
node numbers that exceed this
value are considered errors.
The value specified must be greater
than 0; values up to the license node
limit are allowed.

REPL_DUP |K?| Switch that indicates how to process

records from an input file with
matching node numbers. If this
switch is true, the later record will
 replace any previously read
records. Default value is false.
This keyword applies to each
NODEI or LINKI file as it is read
within any PHASE=INPUT. (Any
nonbinary file will automatically be
processed within an input phase;
binary files should not have
duplicate records.) The MERGE
control statement is used to
determine how duplicate links from
different inputs are to be processed
during the MERGE phases. To
obtain a listing of duplicate links,
specify REPORT DUPLICATES=T.

S H A P E A N GLE |K?| Use shape to determine link angles.

Default is False. By default, link
angles are calculated using straight
lines. If a shape file is specified as a
GEOMI input, which has the A and B
node fields, then setting this
parameter will enable the calculation
of link angles using the shapes in the
GEOMI input.

S OR T A N GLE |K?| Option to allow sorting the relative

angle of the legs with respect to the
current leg, to make it easier to
process the list of inbound/outbound
links. Default is False. For N and A,
the legs are sorted based on the
inbound relative angles. For B, the
legs are sorted based on the
outbound relative angles. Inbound
sorting is used for A node, since it
will be useful to look at the turns into
the A node and similarly outbound
sorting is used for B node, since it
will be useful to look at the turns out
of the B node.

ZONES |KI| Specifies the number of zones in the

network. This is required only if the
number of zones cannot be
determined from the LINKI and
NODEI files, or it is desired to alter
the number of zones. By default, the
program detects the value.
The value must be greater than 0
and less than 20000. A temporary
variable _ZONES is initially set equal
to this value, and can be used in
COMP and IF expressions. If ZONES
is used in a COMP statement, it will
become a variable in the output
network. If this parameter value is not
supplied (or is not available from an
input binary network), the program
will set it to the highest node number
in a monotonic string beginning at 1.

All the values on this statement are trigger keys; the PARAMETERS control word need not
be specified. Each keyword could begin a new statement.
Network Program > Control statements > PARAMETERS > Example

Exam ple
PARAMETERS repl_dup=n
MAX_IP_ERRS=10
nodes=35000 zones=2203
Network Program > Control statements > PLOT

PLOT
Selects links/nodes for plotting.
• DRAW A

• D R A W LIN K

• LIN KP OS T

• N OD E P OS T

PLOT statements in the LINKMERGE phase control plotting. After the program completes
the LINKMERGE stack for a link, it processes the final values for the PLOT keywords that
may have been applied to the link. If there are no DRAWLINK values present, the link is
not processed for plotting. If there are DRAWA and/or NODEPOST values, they are saved
until all the links from the current A-node are completed. When the A-node is completed,
the node values are saved for post processing, so that node symbols will be prominent
on the display.
If there is a LINKPOST value, but there is no DRAWLINK value, the LINKPOST value is
ignored. The situation for nodes is different; a node can be posted without a symbol.
A PLOT statement may be specified on a short IF statement, but it must begin with one of
the keywords.
P LOT k e y wo rd s

Ke y wo rd D e s c rip tio n

DRAWA |S4| Specifies the characteristics for

drawing a symbol for the A-node of
the link. Possible values are:
• Color — A value as described
in “PLOTTER” on page 458.
• Size — Size of the symbol.
• Symbol — Centered on the
node, can be Circle,
Rectangle, or Triangle.
• Fill

DRAWLINK |KS4| Specifies the characteristics for

drawing this link: color, size, and
style. Color is a value as shown in
the PLOTTER description, below.
Size is the width of the line; current
Windows drivers do not allow both
size and style at the same time
(style is changed to solid if a width is
specified). Possible styles are:
Solid, Dash, Dot, DashDot,
DashDotDot. If PLOTTER
BANDWIDTH is specified and the
 bandwidth variable has a value,
Size and Style are ignored. It is
recommended that Size usually be
left null.

LINKPOST |S| Specifies the color that this link is to

be posted with.

NODEPOST |S2| Specifies the color and size of the

variables that are to be posted for
this Anode. (See NODEPOSTVARS
under “PLOTTER” on page 458 for
information about which variables
are to be posted.)
Network Program > Control statements > PLOT > Example

Exam ple

See “Examples and FAQ” on page 496.

Network Program > Control statements > PLOTTER

PLOTTER
Specifies plotting parameters
• B A N D W ID T H
m FILL
m TAPER

• D E V ICE

• FILE

• FOOT E R
m ALIGN
m FONT

• HEADER
m ALIGN
m FONT

• LE GE N D
m FONT
m LINE
m SYMBOL

• LIN KOFFS E T

• MA P S CA LE

• MA P W IN D OW

• MA R GIN S

• P LA T E S IZE

• P OS T LIN KV A R
m FONT
m POST

• P OS T N OD E V A R
m FONT

The PLOTTER statement specifies the configuration for plotting link and/or node
information. See “Plotting” on page 492 for some information about getting your printer
device installed and its basic configuration established. The printer driver properties are
established by left-clicking the desired printer and then modifying the properties as
desired. The orientation (portrait or landscape) determines how the plot will be
generated, and the size determines the plate size of the drawing.
P LOT T E R k e y wo rd s
Ke y wo rd S ub k e y wo rd D e s c rip tio n

BANDWIDTH |S| Specifies the variable that is to be used

to control the drawing of bandwidths
along drawn links. Usually, a temporary
variable should be designated. The
variable must be scaled appropriately,
or the plot will be unreadable.

BANDWIDTH FILL |S| Specifies if the band is to be filled in or

left empty. On raster plotters, this value
should be specified as solid, but on pen
plotters, solid could require excessive
time for generating and actually drawing
the plot. The possible values are: Solid
and None. The default is None.

BANDWIDTH TAPER |I| Specifies that the ends of the bands are
to be tapered towards the nodes rather
than being perpendicular to the link. In
grid plots where Fill is not used, a taper
of 45 might be more presentable. Any
integer value from 0 to 45 (degrees)
may be specified.

DEVICE |S| Name of the printer driver that is to be

selected and written to. The name must
match the name of the printer as it
appears in the Printers dialog box.
Case is not essential. If the name has
spaces in it, the value must be
enclosed within quotes so that the
spaces can be considered as part of
the name. There must be a DEVICE
specified; otherwise the program will not
know anything about the printer

FILE |F| Used if it is desired to write the printer

information to a file, rather than directly
to the printer. This is recommended for
devices that are normally not
connected directly to the processing
computer. If FILE is not specified, the
output will be written directly to the
printer device. If FILE is specified, actual
printing (or plotting) is performed by
copying the file directly to the port that is
connected to the device.

FOOTER |S16| Specifies lines of text that are to be

printed at the bottom of the plot page.
There may be up to 16 footers. The
program will add one additional footer
to identify the software and the licensee
after the user footers are printed. If none
of the footers has specified a date, the
date and time will be added included in
the identification line. Tokens may be
specified in the footers; when they are
present the token is replaced by a
value. The tokens and their
replacements are:
Token
Replacement
 [date]
MM/DD/YY
[idate]
MMM DD YYYY
[time]
HH.MM
[times]
HH.MM.SS
[window]
X=xxxxx-xxxxx Y=yyyyy-
yyyyy
[scale]
Scale=xxxxx

FOOTER ALIGN Specifies how the footers should be

aligned on the plot. The value can be:
Left, Right, or Center. ALIGN must be
placed after a FOOTER or FONT value;
if more headers are to be specified
after ALIGN, the FOOTER[]= must be
specified.

FOOTER FONT Specifies the font characteristics of the

footers. There may be up to nine values
following FONT, but currently, only the
first three are used. The values are
(position), name, size, color.

HEADER |S16| Specifies lines of text that are to be

printed at the top of the plot page. There
may be up to 16 headers. Since
headers most likely have special
characters in them, it is recommended
that each header be enclosed within
quote marks ("..."). The highest index for
a header sets the number of header
lines that will be printed. Example: if only
one header is specified, say
HEADER[6]="...", 6 lines will be printed,
with the first 5 being blank.

HEADER ALIGN |S| Specifies how the headers should be

aligned on the plot. The value can be:
Left, Right, or Center. ALIGN must be
placed after a HEADER or FONT value; if
more headers are to be specified after
ALIGN, the HEADER[]= must be
specified.

HEADER FONT |S4| Specifies the font characteristics of the

headers. There may be up to nine
values following FONT, but currently,
only the first three are used. The values
are (position), name, size, color.

LEGEND |S| Specifies the position for additional

user text is to be printed on the plot
page. There are four possible legend
positions:
• TopLeft
• TopRight
 • BottomLeft

• BottomRight
NOTE: The four positions can also be
designated as TL, TR, BL, and BR, or 1,
2, 3, and 4. See “Examples and FAQ” on
page 496.
The legends are placed within the plot
window area, and their areas are not
written into by network drawing. The
coding rules are similar to those for
HEADER and FOOTER, but you can also
enter symbols on each line. Legends
are primarily for identifying the
characteristics of the network drawing.
Each LEGEND may have its own font
characteristics; they will be used for the
text for all lines in the legend. Each LINE
can have its own symbol.

LEGEND FONT |S9| Specifies the font characteristics for the

text in this legend. See HEADER FONT
on page 462 for details.

LEGEND LINE |S16| Text to be printed at the specified line of

the legend.

LEGEND SYMBOL |S4| Specifies the symbol that is to precede

the LINE text. There should be four
values specified for the symbol: name,
size, color, and fill color.
Name
See DRAWA under “PLOT” on
page 457 for valid symbol
names. If a sample line style is
to be drawn, see DRAWLINK
under “PLOT” on page 457 for
valid names.
Size
The size of the symbol, or the
length of the line.
Color
Standard color designation.
Fill
Standard color designation if
the symbol is to be filled with a
color.

LINKOFFSET |R| Specifies the distance (in inches) that

the links are to be drawn from the
normal centerline. This allows two-way
links to be more visually presented. If
this keyword is not used, or the value is
0, the high-to-low node link will overwrite
the low-to-high link.

MAPSCALE |R| Specifies a scale factor to be used to

convert coordinate units to inches. The
value is expressed as coordinate
units/inch. If the value is not specified, a
scale factor will be computed from
known information. Note that when a
 factor is specified, the MAPWINDOW
will be used mainly to orient the center
of the plot.

MAPWINDOW |R4| Specifies two opposite corners of the

map window to be selected. The map
window is specified in map coordinate
units. If no window is specified, the
program uses the minimum and
maximum coordinates from the network.
The plot will be scaled to fit within the
map window. The 4 required values are
specified as X1,Y1, X2,Y2. Any part of
the network that exceeds the limits of the
window will not be drawn. If MAPSCALE
is not specified, the scale factor will be
calculated to fit the window within the
page. The center of the map window will
be placed in the center of the plotting
window. MAPWINDOW will most likely
not directly correlate with the plotting
window; the program may adjust one of
the dimensions if it is necessary.

MARGINS |R4| Specifies the margins that surround the

plot window on the printed page. If the
selected device is a printer that is
selected with Letter size (8.5 x 11
inches), a normal margins would be
0.25 inches. If it were desired to leave
more space around the plotted window
(say 1 inch on the left and 1.5 inches on
the right), MARGINS=0.75,1.25 would
be used. To make the top margin 1.5
inches and the bottom margin 2 inches,
MARGINS[3]=1.25, 1.75 would be
used. You can do this with one keyword:
MARGINS = 0.75,1.25,1.25,1.75.
By judicial use, the plot window can be
placed anywhere on the page that is
desired.

PLATESIZE |R2| Specifies the maximum plot plate

(page) size. It should not be greater
than the dimensions specified in the
device properties; if it is, the output
might be cropped. This keyword is
used primarily to make a plate that is
smaller than the basic dimensions of
the device. The plate will be oriented at
the upper left corner of the printed page.
Nothing will be printed outside the
rectangle defined by this The
MARGINS values can be used to
position the printed window within the
plate. In general, this need not be
specified; the MARGINS values can be
used to establish the dimensions of the
plot window. Two values must be
entered: the width (x dimension), and the
height (y dimension). They are
expressed in inches. PLATESIZE is not
normally used.
POSTLINKVAR |S4| Specifies the variables that are to be
posted along links that are drawn and
designated for posting by a PLOT
LINKPOST value. Up to four variables
can be selected. The same variables
will be posted for all links; it is not
possible to vary the variables. It is not
recommended that different variables
be posted on different links, but it is
possible for the user to cause this to
happen by specifying variables that are
modified as desired in the stack
statements. The number of desired
decimal places for the posting of the
variable can be appended to the
variable name in parentheses, for
example, POSTLINKVAR=VC(3) to
post VC ratio with 3 decimal places.

POSTLINKVAR FONT |S4| Specifies the font characteristics for link

posting. The standard font designations
are specified, but the color is ignored;
the PLOT DRAWLINK statements set
color.

POSTLINKVAR POST |S| Specifies how link post text is to be

printed when it is too long for the link.
The possible selections are:
Fit
Omit the text; it doesn’t fit.
All
Print it, regardless if it
overruns the link.
AutoSize
Decrease the font size until
it fits, or is too small.
AutoSize(ss)
Same as AutoSize, but the
optional (ss) indicates the
minimum size to allow.

POSTNODEVAR |S4| Specifies the variables that are to

printed to the upper left of a node that is
designated for posting by a PLOT
NODEPOST value.

POSTNODEVAR FONT |S4| Specifies the font characteristics for

node posting. The standard font
designations are specified, but the
color is ignored; the PLOT NODEPOST
statements set color. The font size can
be overwritten on a node-by-node
basis.
Network Program > Control statements > PLOTTER > Font specifications

Fo nt specificatio ns

You can control all text that is to be printed on the plot. In general, you can specify the
name of the font, the size, and the color. The font name must be recognized (and
available), or the printer driver will substitute a font of its choosing. If no font is specified,
the program will supply the name “ARIAL.” The size is always specified as absolute, in
inches; changing to a different size printer will not alter the size the text. If no size is
specified, the program will supply a value of 0.01. The color can be specified in various
ways: by a standard name, or a numeric value to index color mix. Colors are processed
in Windows by using a number that is a combination of the three colors (red green and
blue). You can create the internal number by specifying an integer number (not too
likely), a hexadecimal value (very common process), or by a string of digits preceded by
a color indicator. Three bytes are used to store the intensity of each of the colors; the
values can range from 0 to 255. To use the mixing string, the string must begin with one
of the letters (RGB) followed by a number in the range of 0-255, and more color strings, if
desired. The order of the strings is irrelevant. To enter the hexadecimal value, the string
must begin with 0x and be followed by a string of hexadecimal values (0-f). The table
below indicates the standard colors and their various representations. If there is no color
for the font, a color will be chosen by the printer driver. For pen plotters, the driver will
translate the color number to a pen number. The pen color correlation is determined by
the properties of the driver. You may have to experiment to obtain which pen is selected
for each color used.

Co lo r D e c ima l H e xV a lue R #G#B #

black 0 0x000000 --

red 255 0x0000ff r255

green 49152 0x008000 g128

blue 16711680 0xff0000 b255

yellow 65535 0x00ffff r255g255

purple 8388736 0x800080 r128b128

aqua 16776960 0xffff00 g255b255

gray 8421504 0x808080 r128g128b128

silver 12632256 0xc0c0c0 r192g192b192

lime 65280 0x00ff00 g255

white 16777215 0xffffff r255g255b255

none -1 -- --
Network Program > Control statements > PLOTTER > Example

Exam ple

See “Examples and FAQ” on page 496.

Network Program > Control statements > PRINT

PRINT
Formats and prints a line of information. Please see “PRINT” on page 69 for more
details.
Network Program > Control statements > PRINT > Example

Exam ple
PRINT LIST=A(4),B(5),DISTANCE(6.2) ABCDE(6.3), FORM=LRCD,
LIST=SPEED, TIME1 ;Note: this line is a continuation

LIST= N(5), X, Y
PRINT FORM=6.0CDLR LIST=A,B,DISTANCE, T0, SPDCLASS FILE=PRINTFIL.002
Network Program > Control statements > PROCESS ... ENDPROCESS

PROCESS ... ENDPROCESS

Specifies a PROCESS and ENDPROCESS block. Keywords and sub-keywords include:
• PHASE
m FILEI (comp)

P R OCE S S k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

PHASE |KS| Indicates the phase to which the

statements which follow it are to be
applied. The end of the phase block is
established when an ENDPROCESS or
another PROCESS statement is
encountered. The value for PHASE
must be either INPUT, NODEMERGE,
LINKMERGE, or SUMMARY.

PHASE FILEI |F| Used only with PHASE=INPUT, and

indicates that the block statements are
to be applied only when the specified
FILEI file is being processed. Normally,
only DBF and ASCII files are
processed in the INPUT phase, but if a
FILEI with a different mode is specified,
the file will be processed in the INPUT
phase. The value must be NI.# or LI.#,
to indicate a file from NODEI[#], or
LINKI[#] that was previously specified
on a FILEI statement.

Normally, a PROCESS statement contains only the above keywords and values, and the
operations to be performed on the designated file during the phase follow on additional
control statements. The ENDPROCESS statement can alternatively be specified as
ENDPHASE; that is more consistent if the PROCESS control is triggered by PHASE=.

Citilabs recommends using PROCESS/ENDPROCESS blocks be used to contain all

operational (stack) statements. That way there is no confusion about what is intended. If
there is no specific PHASE=LINKMERGE statement, any stack statements that are not
explicitly within a PROCESS block, will be executed in the LINKMERGE phase. Even if
there are PROCESS blocks surrounded by stack statements, all the stack statements will
be executed during the LINKMERGE phase. The program will skip over the PROCESS
block.
There are some rules about PROCESS blocks:
• There may be only one PHASE=NODEMERGE

• There may be only one PHASE=LINKMERGE

• If there is a PHASE=LINKMERGE statement, there may not be stack statements that are not
explicitly within a PROCESS block. In other words, once a LINKMERGE phase has been
designated, all stack statements must be with an explicitly stated PHASE.
Network Program > Control statements > PROCESS ... ENDPROCESS > Example 1

Exam ple 1
; Re-code node numbers for LINKI[1] and NODEI[1] using a
; lookup function. The 2nd PROCESS statement also acts as
; an ENDPROCESS statement, but an ENDPROCESS is required
; after the 2nd PROCESS.

PHASE=INPUT FILEI=NI.1
N = NODECODE(N);
PHASE=INPUT FILEI=LI.1;
A = NODECODE(A), B = NODECODE(B)
ENDPROCESS
Network Program > Control statements > PROCESS ... ENDPROCESS > Example 2

Exam ple 2
PHASE=LINKMERGE
IF (LI.1.DIST != LI.2.DIST) LIST='Distances Differ for link:',
LIST=A(5) B(6), FORM=6.2, LI.1.DIST, LI.2.DIST
ENDPHASE
Network Program > Control statements > REPORT

REPORT
Defines report specifications. Keywords include:
• A LL

• CA P A CIT Y

• D E A D LIN KS

• D U P LICA T E S

• FILE I

• FILE O

• IN P U T

• ME R GE

• SPEED

• U N CON N E CT E D
REP
R E P OR T k e y wo rd s

Ke y wo rd D e s c rip tio n

ALL |?| Set all the following reports to this

value (not usually recommended).
Default value is F.

CAPACITY |?| Capacity tables. Default value is F.

DEADLINKS |?| Links that are missing either an entry

or exit link. Such links cannot be
used by any path processing.
Additional file processing may be
required. Default value is F.

DUPLICATES |?| Duplicate links that are detected

during PHASE=INPUT. Default
value is F.

FILEI |?| Internal specifications for the input

files (use for debugging only).
Default value is F.

FILEO |?| Internal specifications for the

allocation of output variables use for
debugging only). Default value is F.

INPUT |?| Summary statistics following input

phases. Default value is F.

MERGE |?| Summary statistics following every

phase. Default value is T.

SPEED |?| Speed tables. Default value is F.

UNCONNECTED |?| List of zones that do not have links

into and out of them. Default value is
T.
All reports must be specified with a logical value of true or false. The default value is
true.
Network Program > Control statements > REPORT > Example

Exam ple
REPORT FILEI=Y, FILEO=Y; normally not specified.
REPORT SPEED=Y, UNCONNECTED=N
REPORT ALL=true, fileo=false, filei=false
Network Program > Control statements > SORT

SORT
Sorts user-defined arrays. Keywords include:
• ARRAY

• N U MR E CS

See “SORT” on page 81 for more information about this standard Cube Voyager
statement.
Network Program > Control statements > SORT > Example

Exam ple
ARRAY AN=LINKS, BN=LINKS, VMT=LINKS ; NETI must be a binary network
PHASE=LINKMERGE
_L = _L + 1
AN[_L] = A
BN[_L] = B
VMT[_L] = V_1 * DISTANCE
ENDPHASE
/* note:
The User has to keep count of the records entered into the arrays
If links are deleted, the number of entries will be less than the
original number of links.
*/
PHASE=SUMMARY
SORT ARRAY=-VMT, AN,BN, NUMRECS=_L
LOOP _K=1,30 ; only want to see the highest 30
LIST=AN[_K](6),BN[_K](6),VMT[_K](10.2c)
ENDLOOP
ENDPHASE
Network Program > Control statements > SPDCAP

SPDCAP
Revises speed and capacity tables. Keywords include:
• CA P A CIT Y

• LA N E S

• SPEED

S P D CA P k e y wo rd s

Ke y wo rd D e s c rip tio n

CAPACITY |RV*99| Capacity in vehicles per lane per hour. Actual link
capacity is obtained by multiplying the link capacity
based upon its capacity classification (CAPCLASS)
value by the number of LANES. All values must be 0-
9999, inclusive. The capacity array is initialized to 20
times the index number, for all lane stratification
(CAPACITY[1]=20, CAPACITY[2]=40...).

LANES |IV| Lane stratification that any following CAPACITY and/or

SPEED values are to apply to. LANES may be
interspersed with other keywords and values on the
statement. All values must be 1-9, inclusive.

SPEED |RV*99| Speed to be applied to the link. All values must be 0-

3276.7, inclusive. The speed array is initialized to the
index number, for all lane stratification
(SPEED[1...99]=1,2,...99). Speed is maintained with
one decimal place.

A network contains an array of capacity and speed data. Each array is dimensioned with
ninety-nine values for each of nine lane stratification, and contains 891 values. When an
array is accessed, the program uses the number of lanes (LANES) as the row index, and
the capacity and/or speed classification (CAPCLASS, SPDCLASS) as the column index to
obtain a value for a link. If CAPACITY or SPEED is encountered prior to a LANES keyword on
the statement, LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector
data, and may be indexed to set a specific loading place, and may have null fields to
skip the revision of certain columns. The SPEEDFOR and CAPACITYFOR functions can be
used to obtain values for these tables.
Network Program > Control statements > SPDCAP > Example

Exam ple
;Set entire table to 50,
; then revise the values for 20,21, and 24 for lanes 1,3,8
SPDCAP CAPACITY=99*50, LANES=1,3,8, CAPACITY[20]=300,400,,,700
SPDCAP LANES=2,4-9, SPEED=20.5,30.3,50.6,,,88.2, LANES=5,SPEED[15]=15
SPDCAP SPEED=30, LANES=2-8; Inappropriate; the LANES will not be used.
Network Program > Theory

Theory
This section describes the theory used by the Network program. Topics include:
• Phase descriptions

• Network Topology Functions

• Variable referencing

• Output variables

• Plotting
Network Program > Theory > Phase descriptions

Phase descriptions
The program processes the input files in separate phases, which are listed below. For
most applications, the user need not be concerned with process phases; they are used
only when special processing is to be undertaken. In general, the user must code
operational statements within a PROCESS PHASE block defined for each phase. There
may be only one block for each phase, and the order of the blocks in the input is not
crucial. It is suggested that for readability and ease of editing, the phase blocks be
defined in the normal process order. Only statements that specifically apply to the phase
should be coded within the block. However, statements that are not dynamic operations,
but that appear within a phase block will be recognized as such and will be processed
properly. A block should be terminated with an ENDPROCESS statement. If another
PROCESS PHASE statement is encountered before an ENDPROCESS statement, the
previous block is terminated, and the new block is begun.
The basic phases are:
• INPUT phase — Read ASCII, Network, GIS and DBF files, re-code values from any input
files specifically designated.

• NODEMERGE phase — Read all node data and organize it

• LINKMERGE phase — Read all link data and process it (main phase)

• SUMMARY phase — Report results of LINKMERGE phase

There need not be a specific PROCESS PHASE for LINKMERGE, because it is

anticipated that most applications will be functioning in only this phase. If an operational
statement is encountered, and it is not within a PROCESS block, it is tagged as being in
the LINKMERGE phase. A PROCESS PHASE=LINKMERGE statement may be coded,
but it is not mandatory.
Internally, the program processes the phases in the order in which they are described
below. As it processes each phase, it determines the files that must be processed in that
phase, and processes them. If there are no relevant files for an INPUT phase, the phase
is bypassed. As the program processes each file record, it applies any phase operations
that the user has designated for the phase.
Network Program > Theory > Phase descriptions > INPUT phase

IN PUT phase
All ASCII, Network, GIS and DBF files must pass through this phase. The records are
processed and edited for errors and duplication. The user may specify selections and
computations to be applied to each record as it is processed. It is possible to re-code
node numbers in this phase. Binary input files are processed in this phase only if the
user has specifically designated the file through the use of a PROCESS
PHASE=INPUT block. Any file (or file segment) that passes through this phase, is no
longer used in its original format after this phase is completed; but its data are used in
subsequent phases in a revised internal format. The file segment records are sorted in
appropriate order (node or link) before being stored in the revised format.
Network Program > Theory > Phase descriptions > NODEMERGE phase

N ODEMERGE phase
The node based records from all the NODEI files must pass this phase. As in the INPUT
phase, the user may specify computations and/or selections to be applied to each node
record as it is processed. It is not permissible to re-code node numbers in this phase.
The resulting record for each unique node is written to the output network, and saved for
subsequent referencing in the LINKMERGE phase.
NODEMERGE Phase Keywords - network topology.

Ke y wo rd D e s c rip tio n

_N.MaxConnect Get maximum number of connections for

the whole network

_N.Connections Get number of connecting nodes to N

_N.Legs Get number of legs at N

_N.Inbounds Get number of inbound links to N

_N.Outbounds Get number of outbound links to N

_NI.{name}[#] Get inbound link attribute's value, {name}

is the attribute name, [#] is the leg number

_NO.{name}[#] Get outbound link attribute's value,

{name} is the attribute name, [#] is the leg
number

_NI._Angle[#] Get inbound link angle in degrees, # is

the leg number

_N I._R _A N GLE [ #] Get inbound link angle relative to the

current leg, in degrees. [#] is the leg
number. In the node merge phase, the
current leg is always the first leg in the A/B
sort sequence

_NO._Angle[#] Get outbound link angle in degrees, # is

the leg number

_N O._R _A N GLE [ #] Get outbound link angle relative to the

current leg, in degrees. [#] is the leg
number. In the node merge phase, the
current leg is always the first leg in the A/B
sort sequence.

See Network Topology Functions for more information.

Network Program > Theory > Phase descriptions > LINKMERGE phase

LIN KMERGE phase

The link based records from all the LINKI files must pass through this phase. As in the
above phases. the user may specify selections and computations to each link record as
it is processed. This is the phase that most users are mostly interested in. Records can
be deleted, summarized, tabulated, and extracted to an external device or file. Node
based data can be accessed during the link processing. Tabulated and summarized
data is reported at the end of the phase, and, in most cases, passed onto the final
phase.
LINKMERGE Phase Keywords - network topology.

Ke y wo rd D e s c rip tio n

_N.MaxConnect Get maximum number of

connections for the whole
network

_A .MA XMOV E LE GS / Variable which contains the

_B .MA XMOV E LE GS highest number of legs per
movement, in both inbound
and outbound direction at
the A/B node. If this value is
greater than 1, it means that
more than one leg at the A/B
node location has the same
movement.

_A.Connections/_B.Connections Get number of connecting

nodes to A/B

_A.Legs/_B.Legs Get number of legs at A/B

_A.Inbounds/_B.Inbounds Get number of inbound links

at A/B

_A.Outbounds/_B.Outbounds Get number of outbound

links at A/B

_A.CurrentLeg/_B.CurrentLeg Get the leg number of the

current link at A/B

_AI.{name}[#]/_BI.{name}[#] Get inbound link attribute's

value, {name} is the attribute
name, [#] is the leg number
at A/B

_AO.{name}[#]/_BO.{name}[#] Get outbound link attribute's

value, {name} is the attribute
name, [#] is the leg number
at A/B

_L.S_Angle Get link angle for the current

link, at the start of the link.
The angle is calculated in
degrees. Zero is north and
 counted counter-clockwise.
For straight line links, the
_L.S_Angle and _L.E_Angle
both have the same values.
Only if a GEOMI shape file is
input and the parameter
SHAPEANGLE set to true,
_L.S_Angle and _L.E_Angle
will give different values for
links with shapes.

_L.E _A ng le Get link angle for the current

link, at the end of the link.
The angle is calculated in
degrees. Zero is north and
counted counter-clockwise.
For straight line links, the
_L.S_Angle and _L.E_Angle
both have the same values.
Only if a GEOMI shape file is
input and the parameter
SHAPEANGLE set to true,
_L.S_Angle and _L.E_Angle
will give different values for
links with shapes.

_A I._A ng le [ #] / _B I._A ng le [ #] Get inbound link angle in

degrees, [#] is the leg
number at A/B.

_A I._R _A N GLE [ #] / Get inbound link angle

_B I._R _A N GLE [ #] relative to the current link, in
degrees. [#] is the leg
number. The inbound
relative angles are
calculated to be the relative
angles of the inbound legs
with the OUTBOUND leg of
the subject link.

_A I._MOV E [ #] / _B I._MOV E [ #] Get the movement number

of an inbound leg relative to
the current leg. [#] is the leg
number. The movements
are determined based on
the relative angle. For
inbound legs, it is the
direction it is turning FROM,
meaning if it is FROM the
right, it is a LEFT turn from
that leg into the current leg.
The movement numbers
are defined as:
0 - Current leg
1 - Right (45 to 135 degrees)
2 - Through (135 to 225
degrees)
3 - Left (225 to 315 degrees)
4 - U-turn (0-45 and 315-360
degrees)

_A O._MOV E [ #] / _B O._MOV E [ #] Get the movement number

of an out bound leg relative
to the current leg. [#] is the
 leg number. The
movements are determined
based on the relative angle.
For outbound legs, it is the
direction it is turning to,
meaning if it is TO the right, it
is a RIGHT turn from the
current leg to that leg. The
movement numbers are
defined as:
0 - Current leg
1 - Right (45 to 135 degrees)
2 - Through (135 to 225
degrees)
3 - Left (225 to 315 degrees)
4 - U-turn (0-45 and 315-360
degrees)

_A O._A ng le [ #] / _B O._A ng le [ #] Get outbound link angle in

degrees, [#] is the leg
number at A/B.

_A O._R _A N GLE [ #] / Get outbound link angle

_B O._R _A N GLE [ #] relative to the current link, in
degrees. [#] is the leg
number. The outbound
relative angles are
calculated to be the relative
angles of the outbound legs
with the INBOUND leg of the
subject link.

See Network Topology Functions for more information.

Network Program > Theory > Phase descriptions > SUMMARY phase

SUMMARY phase
In this phase, certain post-processing operations can be performed. This is generally
restricted to computations on working variables, usually to obtain averages, etc.
Every record is processed according to the purpose of the current phase. If there are
operations to be performed in the phase, the record is processed against the operation
statements designated by the user. Operation statements are generally expressed in the
standard IF/ELSEIF/ELSE block and COMP statements. These and other operations
available to the user are described in “Control statements” on page 420. In the
NODEMERGE phase, a node record is processed for each unique node from the
NODEI files. If a node is re-coded in the INPUT phase, the re-coded node number is
included. In the LINKMERGE phase, a link record is processed for each unique link
found from the LINKI files. If a link is recoded in the INPUT phase, the recoded link is
included.
Network Program > Theory > Network Topology Functions

Network Topology Functions

This section describes in detail the network topology functions available in NETWORK
Program.
• _N .Ma xCo nne c t - Maximum number of connections for any node in the entire network.

• _N .Co nne c tio ns - Get number of connecting nodes to N.

• _N .Le g s - Get number of legs at N.

• _N .Inb o und s - Get number of inbound links to N.

• _N .Outb o und s - Get number of outbound links to N.

• _N I._A ng le [ #] - Get inbound link angle in degrees, # is the leg number.

• _N O._A ng le [ #] - Get outbound link angle in degrees, # is the leg number.

• _N I._R _A N GLE [ #] - Get inbound link angle relative to the current leg, in degrees.
• _N O._R _A N GLE [ #] - Get outbound link angle relative to the current leg, in degrees.

• _L.S _A ng le - Get link angle for the current link, at the start of the link.

• _L.E _A ng le - Get link angle for the current link, at the end of the link.

• _A .Co nne c tio ns / _B .Co nne c tio ns - Get number of connecting nodes to A/B. Refer to
_N .Co nne c tio ns .

• _A .Le g s / _B .Le g s - Get number of legs at A/B. Refer to _N.Legs.

• _A .Inb o und s / _B .Inb o und s - Get number of inbound links at A/B. Refer to _N .Inb o und s .

• _A .Outb o und s / _B .Outb o und s - Get number of outbound links at A/B. Refer to _N .Outb o und s .

• _A .Curre ntLe g / _B .Curre ntLe g - Get the leg number of the current link at A/B.
• _A I._A ng le [ #] / _B I._A ng le [ #] - Get inbound link angle in degrees, [#] is the leg number at A/B.
Refer to _N I._A ng le [ #] .

• - Get outbound link angle in degrees, [#] is the leg number at

_A O._A ng le [ #] / _B O._A ng le [ #]
A/B. Refer to _N O._A ng le [ #] .

• _A I._R _A N GLE [ #] / _B I._R _A N GLE [ #] - Get inbound link angle relative to the current link. Refer to
_N I._R _A ng le [ #] .

• - Get outbound link angle relative to the current link, in

_A O._R _A N GLE [ #] / _B O._R _A N GLE [ #]
degrees. Refer to _N O._R _A ng le [ #] .

• - Get the movement number of an inbound leg relative to the

_A I._MOV E [ #] / _B I._MOV E [ #]
current leg. The movement number is the direction from which a leg is approaching the
current leg. The direction angles are calculated as relative angles from the current leg. The
below table shows the movement number, the angles for the movement number, the
direction from which the leg is approaching from and the corresponding turn movement.

D ire c tio n (le g is

Mo v e me nt a p p ro a c hing
N umb e r A ng le fro m) T urn Mo v e me nt

1 45 to135 RIGHT LEFT

degrees

2 135 degree to STRAIGHT THROUGH

225 degress

3 225 degree to LEFT RIGHT

315 degrees

4 0-45 and 315- REVERSE U-TURN

360degree

A movement number of 0 means the leg being considered is the current leg.
• - Get the movement number of an outbound leg relative to the
_A O._MOV E [ #] / _B O._MOV E [ #]
current leg. The movement number is the direction to which, a leg is departing the current
leg. The direction angles are calculated as relative angles from the current leg. The below
table shows the movement number, the angles for the movement number, the direction
from which the leg is approaching from and the corresponding turn movement.

D ire c tio n (le g is

Mo v e me nt a p p ro a c hing
N umb e r A ng le fro m) T urn Mo v e me nt

1 45 to135 RIGHT RIGHT

degrees

2 135 degree to STRAIGHT THROUGH

225 degress

3 225 degree to LEFT LEFT

315 degrees

4 0-45 and 315- REVERSE U-TURN

360degree

A movement number of 0 means the leg being considered is the current leg.

• - Variable which contains the highest number of legs

_A .MA XMOV E LE GS / _B .MA XMOV E LE GS
per movement, in both inbound and outbound direction at the A/B node.
Network Program > Theory > Variable referencing

Variable referencing
The main logic of the program involves processing variables. A variable name may be
up to 15 characters in length, and may consist of only letters, digits, and the underscore
character. The first character of the name may not be a digit. If the first character of a
name is an underscore (_), the variable is only a local working variable, and will not be
included in the network. Variables are usually classified as either node or link based.
Classification depends upon the process phase in which the variable is referenced. If a
new variable is computed (NEWVAR=...), it will be attached as either a node or link
variable. During any INPUT phases, the variables will be associated with the type of file
being processed. During the NODEMERGE phase, the variables are node based.
During the LINKMERGE phase, variables are link based, but node variables can be
referenced. A node variable is referenced during LINKMERGE as either A.name or
B.name.
If a variable from an input file is to be referenced during NODEMERGE or LINKMERGE,
the associated NODEI or LINKI file number must precede the variable name. For
NODEMERGE the prefix is NI.#., and for LINKMERGE the prefix is LI.#. For example:
LI.3.ABC references the variable ABC from the LINKI[3] file. The program establishes a
buffer for a record from each input file for every record in the phase, and the prefix allows
access to each of those buffers. If there is no input record for the current working record,
the values are all zero. The formal designation for the prefix is LI.#., but the program
allows the following variations:

For NI.#.name* NI#.name N.#.name N#.name

node
records:

For link LI.#.name* LI#.name L.#.name L#.name

records:

*The preferred method of designation.

Another type of variable is the working variable. Working variables are variables that are
to be used for intermediate storage, and will not be part of an output network. They are
distinguished by their first letter, which must be an underscore. Working variables are set
to zero at the beginning of the application, and are changed only by user statements. If
there is a user SUMMARY phase, every variable referenced within the SUMMARY
block is a working variable, unless it is the same as a link variable. If it matches a link
variable, the variable from the last link will be processed. Working variables allow the
user to accumulate statistics during link processing, and to then compute and print
summaries at the end of processing.

NOTE: Insome situations, a PRINT LIST variable may not be recognized if it is cross-
referenced. For example: LIST=A,B,A.X,B.X may not be accepted. To be sure, node
based variables to be listed should be set into temporary variables and then listed with
that name. (See “Examples and FAQ” on page 496 for an illustration.)
Network Program > Theory > Variable referencing > Example

Exam ple
_vdiff = L1.vol - L2.vol; get assignment differences
_vcnt = _vcnt + 1
if (_vdiff != 0) _sumsqdiff = _sumsqdiff + _vdiff*_vdiff
.
.
Phase=SUMMARY
if (_vcnt > 1)
RMSV = sqrt(_sumsqdiff / _vcnt); possibly (_vcnt-1)
list = 'RMSV =', RMSV
endif
Phase=LINKMERGE
_ax = a.x ; get the Node variable named X for Node A
_ay = a.y
LIST=a,b,_ax,_ay
EndPhase
Network Program > Theory > Output variables

Output variables
During the merge phases, a work record is generated for each unique record that
appears in all the input files (depending upon the value of the MERGE RECORD keyword).
Each work record will contain all the unique variables that are defined in/for all the input
files and any COMP statements for the phase. The value that is stored for each variable is
controlled by the MERGE control statement. If all the variables are not to be included in
the output network, the variable list can be modified on the FILEO statement.
Network Program > Theory > Plotting

Plotting
The network that is formed during the LINKMERGE phase can be plotted by sending
information to a standard Windows printer device. There must be an appropriate printer
device driver for the media where the network is to be plotted. Typical types of drivers
are available for printers, faxes, raster plotters, and pen plotters. The Network program
uses the Windows driver to perform the actual formatting of the network information.
Many default drivers come with Windows and provide considerable capabilities. This
process provides for current and future flexibility. It is possible to directly fax a network
plot to a facsimile machine. Windows operating systems are geared towards more
recent technology, so pen plotters are being left somewhat behind. They do cause some
problems.
Pen plotter problems: The standard Windows drivers for pen plotters do not seem to
function properly; in particular, they do not always write text at the proper location and
angle. There are third-party software drivers available that correct this problem, but
deficiencies have been reported in these systems, as well. With one driver (WinPlus), if
legends are used, the link posting will be oriented properly, but mis-positioned. This
release of the program does not address these driver deficiencies; perhaps later
versions will internally rectify them. Plotting pens are selected by RGB (RedGreenBlue)
standards, so it becomes the responsibility of the user to ensure that the colors that are
selected correspond with the pens on the plotter. If standard colors are used (red, green,
blue, yellow, etc.), there should be no problems. If esoteric colors are requested, color
correspondence is not guaranteed. If roll size is selected in the device driver, the
program may not be able to properly scale the plot. In those cases, the user must
specify the desired plate size.
It is recommended that if pen plotters are to be used that the WinPlus driver be obtained
and installed as a printer driver and that the PLOTTER statement contains no LEGEND
keywords.
A PLOTTER control statement is used to define the plotting system and the parameters for
performing the plot. PLOT statements processed during LINKMERGE determine what will
be plotted from the network. If there are PLOT statements, but no PLOTTER statement, the
program will fatally terminate; the opposite is not an error. The PLOTTER statement
contains information about:
• The plotting device name, and whether the output is to be sent directly to the plotting
device, or to a file.

• The logical layout of the plot plate on a sheet of the plotter device: the desired size, if
different than the driver provided size, and the margins to place the plate within the driver
provided dimensions.
• The optional network window for selection, and optional scaling.

• The headers and footers to be printed on the plot.

• Legends that can be displayed in the corners of the plotting window.

• The link variables that are to be posted when a link is selected for posting.

• The node variables that are to be posted, when a node is selected for posting.

• Bandwidths and type of fill and end tapers.

In general, all text that is to be plotted can have its font, color and size specified by the
user. The default values for each of these are: ARIAL, black, 0.10. All sizes are
specified in inches, so that if a different driver is used, the text would still be readable.
Link posting (writing text along a link) can not be varied by link; if a link is posted, its
posting will contain the same type of information at the same size and font as any other
link that is posted. The user controls the color of link posts; individual variables can not
be colored differently. Node posting (writing text near a node) will always post the same
variables, but the size and color is controlled by PLOT statements.
Before performing a plot, the device driver must be properly installed. This is done by left
clicking the Windows Start button and choosing Printers and Faxes . In the Printers and Faxes
window, click Add a printer and follow standard installation processes. The orientation of
the plot, (portrait, landscape) is set in the device. If a device is not attached directly to the
computer, the driver should have the file option specified, and the PLOTTER DEVICE FILE
value (filename) should be specified. Files are generally processed by copying them
directly to the plotter port.
PLOT statements control actual plotting. If a PLOT statement is processed in
LINKMERGE, the current link is flagged for processing by the plotting process. The
following processes are considered:

P ro c e s s D e s c rip tio n

DrawLink Draw the link as specified.

LinkPost Post variables for the link.

DrawA Draw a specified symbol for the Anode of the

link

NodePost Post variables at the A node.

These values can be specified multiple times for each link; the values that are current at
the end of the link are used for plotting. For node processing, the values that are current
following the last link outbound from a node are used. If the PLOT statement is invoked by
the use of one of these trigger keywords, it may be placed on a short IF statement.
Example: IF (...) DrawLink=red, LinkPost=red.
If a keyword specifies plotting, but then later conditions determine that it should not really
be plotted, the keyword can be nullified by setting its value to -1. Example: NodePost=-1.
Many times a link posting may be too long for the link. You can deal with these situations
by specifying the fourth value for PLOTTER POSTLINKVAR FONT.
Network Program > Examples and FAQ

Examples and FAQ

This section contains examples of the Network program and a link to the FAQ chapter.
• Example 1: Listing links to the print file

• Example 2: Merging link records from multiple ASCII files

• Example 3: Dumping link and node records to DBF files excluding select fields

• Example 4: Building network from inline data records

• Example 5: Simple link plot

• Example 6: Complex plot

• Frequently asked questions

Network Program > Examples and FAQ > Example 1: Listing links to the print file

Example 1: Listing links to the print file

run pgm=NETWORK ; List the links in a network
neti=demo20.net
list=a,b
endrun
Network Program > Examples and FAQ > Example 2: Merging link records from multiple ASCII files

Example 2: Merging link records from multiple ASCII

files
run pgm=NETWORK ; merge two ASCII files with different links
linki[1]=demo07.dat,var=a,2,4, b,7,4, dist,14,4, v1,2,4, v2,2,4
linki[3]=demo07m.dat,rev=2,
var=a,2,4, b,7,4, dist2,14,4, rev,35,1, v1,2,4, v2,2,4
nodei[1]=c:\demo\demoxy.dat,var=n,x,y
merge record=true, AVE=dist
report all=no
zones=19
phase=LINKMERGE
if (li.1.a == 0) list=' LI[1] missing link:', a,b
if (li.3.a == 0) list=' LI[3] missing link:' a,b
endphase
endrun
Network Program > Examples and FAQ > Example 3: Dumping link and node records to DBF files excluding select fields

Example 3: Dumping link and node records to DBF files

excluding select fields
run pgm=NETWORK ; write DBFs for nodes and links,
; but exclude many variables from input
neti=test.Hnt
neto=test.tpn,
EXCLUDE= SCENARIO STATUS NAME TPCAP1 TPCAP2 TIPRTP CNT,
EXCLUDE= FIELDOPT TCNUMBER COUNTY USER DATE OCOUNTA OCOUNTP,
EXCLUDE= OCOUNTD OSPEEDA OSPEEDP OSPEEDD,
EXCLUDE= OSPEEDX OSPEEDY ECOUNTA ECOUNTP ECOUNTD ECOUNTY,
EXCLUDE= ESPEEDA ESPEEDP ESPEEDD ESPEEDY COMMENT6 COMMENT1,
EXCLUDE= ATYPE
nodeo=testxy
linko=testld
if (STATUS=='D' || ft==15) delete
endrun
run pgm=NETWORK ;now look at the results from the link DBF
linki=testld.dbf
nodei=testxy.dbf,exclude=xcoor,ycoor
If (a>b && lanes > 4) list=a,b,lanes
endrun
Network Program > Examples and FAQ > Example 4: Building network from inline data records

Example 4: Building network from inline data records

copy file=3pth.lxy ; copy data from inline to a file
LD
1 1 10 1000 60 60 4 1 S23456
2 1 11 2000 60 60 8 1
3 1 12 2500 60 60 6 1
4 10 2 0 0 60 4 1
5 11 2 0 0 60 8 1
6 12 2 0 0 60 6 1
XY
1 1 100 200
2 10 200 300
3 11 200 200
4 12 200 100
5 2 300 200
endcopy
id=this is my ID...
pagewidth=80
RUN PGM=NETWORK ; now build a network from the inline data
merge record=y
nodes=20 zones=2
nodei[3]=3pth.lxy,var=n1,n,x,y,
start=(substr(record,1,2)=='XY'),
stop=(substr(record,1,2)=='LD')
linki[2]=3pth.lxy,var=n3,a,b,dist,tsva1,spdc1,capc1,lane1,string1,typ=a,
start=(substr(record,1,2)=='LD') ,
stop=(substr(record,1,2)=='XY')
list=a,b,dist
endrun
Network Program > Examples and FAQ > Example 5: Simple link plot

Example 5: Simple link plot

; Sample Quickie plot with no parameters: draw links only
RUN PGM=NETWORK ; sample quick link plot
NETI = C:\DEMO\DEMO20.DAT
PLOTTER DEVICE = "HP 7475A", FILE=f:\sample.plt
DRAWLINK=0xffff
ENDRUN
Network Program > Examples and FAQ > Example 6: Complex plot

Example 6: Complex plot

;This sample illustrates various capabilities of plotting.
RUN PGM=NETWORK
NETI = C:\DEMO\DEMO20.DAT
PLOTTER { ; SETUP Plotter
DEVICE="HP LASERJET 4"
POSTLINKVAR=A,B,_AB,_STR
FONT='COURIER',0.10,YELLOW,BOLD
POST=AUTOSIZE(.05)
POSTNODEVAR=A, FONT='COURIER',.10
LINKOFFSET=0.01
BANDWIDTH=_BANDWIDTH FILL=SOLID TAPER=45
HEADER= "This is header 1",
"This is header 2",
align=center, font='courier' ,0.1,green
FOOTER="Footer 1"
FOOTER[3]="Footer 3"
FOOTER[5]='Shows various date tokens: [date] [idate]'
FOOTER[7]='Shows various time tokens: [time] [times]',
FOOTER[7]='Shows window and scale tokens: [window] [scale]'
align=right font='Courier',0.15,green
LEGEND=TopLeft, font='courier',.10,blue,italics,
LINE[1]=TL.LINE1,symbol=triangle,.15,red
LINE[5]=tl.line5,symbol=Dash,.15,red
LEGEND=TR, font='courier',.20,blue,italics,
LINE[1]=TR.LINE1,symbol=triangle,.5,red
LINE[3]=tr.TRne3,symbol=rectangle,.08,red
LEGEND=3, font='courier',.10,red,italics,
LINE[1]=BL.LINE1,symbol=circle,.10,red
LINE[5]=BL.line5,symbol=dashdot,.15,red
LEGEND=BottomRight font='courier',.15,purple,italics,
LINE[2]=BR.LINE2,symbol=triangle,.15,red
}
; Plotting Controls
if (a<=19 || b<=19) _BANDWIDTH = lane/10
_AB = A*100 + B
_STR = str(_ab/100,5,2)
DRAWLINK=RED,,SOLID, LINKPOST=GREEN
IF (A.X == B.X || A.Y == B.Y) LINKPOST=BLUE; FLAT|VERTICAL LINES
DRAWA=BLUE,0.20,CIRCLE,YELLOW
NODEPOST=r123b220g100,.1
IF (A>=30 && A <40) LINK=GREEN,,DASH ; reset the color of these links
; set node postings and symbols
IF (A<=5) DRAWA=RED,0.10,CIRCLE,WHITE NODEPOST=0XFF00FF
IF (A>5 && A<=10) DRAWA=RED ,0.40 CIRCLE NODEPOST=G255
IF (A>10 && A<20) DRAWA=R255,0.15,RECTANGLE,BLACK NODEPOST=R255
ENDRUN
Network Program > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see Network in Chapter 17, “Frequently Asked Questions.”
Matrix Program > Using the Matrix program

Using the Matrix program

This section provides information for using the Matrix program. Topics include:
• Introduction to the Matrix program

• Control statement types in Matrix program

• Working with intrazonal cells of a matrix

• Working with lists of zones

• Working with logit choice models

Matrix Program > Using the Matrix program > Introduction to the Matrix program

Introduction to the Matrix program

The Matrix program processes zonal data and matrices according to specified
expressions. Zonal data and matrices can be input, and matrices and reports can be
output. Various file formats for both input and output are supported. There are no default
processes; you must specify what is to be accomplished. This program is also used
when invoked as a special function via RUN PGM= FRATAR, GENERATION, or
DISTRIBUTION. It is used for the following purposes:
• Computation of new matrix values

• Trip distribution (called by Distribution program)

• Trip generation (called by Generation program)

• Converting and merging matrices between various formats

• Reporting values from matrices and zonal data:

m
Selected rows
m
Marginal summaries (trip ends, etc.)
m
Frequency distributions
m
User formatted files

• Transposing matrices

• Generating matrices

• Renumbering, aggregating, and disaggregrating matrices

Almost any and all of the above processes can be performed in a single application.
There are some restrictions when used as a special function (Fratar, Distribution, and
Generation programs).
The program processes within an overall origin zone loop controlled by the variable
named I. The remainder of this document refers to this loop as the I-loop. The I-loop
begins with I set to one and continues monotonically until the highest zone number is
processed. When the Distribution program calls the Matrix program, I-loops are nested
within iteration loops. (See Chapter 10, “Distribution Program” for details.)
The standard input is comprised of definition, computational, reporting, and flow control
statements (illustrated below). Definition statements are those that define the input and
out files, and are, in most cases, processed outside of the I-loop. Computational
statements are those that cause data to be revised. Flow control statements provide the
capability to iterate through portions and conditionally or unconditionally branch to a
different place, within the I-loop.
When all control statements have been checked for basic syntax, and have been stored
in the control stack, the program builds a list of required variables. The input files are
opened; zonal data files are read and stored, and other housekeeping is performed. If
any input matrices need to be transposed, they are transformed to a single file and made
ready for subsequent retrieval. It then starts the I-loop, reads the matrices for I, and
processes the control stack from the beginning. When the end of the stack is reached,
the program performs some end-of-zone summaries, and writes any matrices
requested. When the I-loop completes (or is terminated), any requested reports are
printed, and the program exits.
All variables are initialized to zero (or blank) before the I-loop, and are thereafter altered
only by computational statements or internal processing. In addition to any variables
explicitly specified by the users, there are certain built-in variables that can be
referenced. The built-in variable are usually protected; the user is not allowed to alter
their values.
Subsequent topics discuss:
• Built-in variables

• Built-in functions

• Transposed matrices
Matrix Program > Using the Matrix program > Introduction to the Matrix program > Built-in variables

Built-in variables
Ma trix p ro g ra m b uilt-in v a ria b le s

V a ria b le D e s c rip tio n

FIRSTZONE Stores the zone number of the first zone

being processed. In a normal run this is 1.
Under intrastep distributed processing with
Cube Cluster, this is the first zone number of
the zones to be processed on the current
Cube Cluster node.

I The current row zone.

ITERATION The iteration number; usually 1.

J A column index, usually 1, and varies (1-

Zones) for MW[] and LOOPs.

LASTZONE Stores the last zone number to be

processed. In a normal run this would be
the same as ZONES. Under intrastep
distributed processing with Cube Cluster,
this is the highest zone number to be
processed on the current Cube Cluster
node.

LOWCNT Result of LOWEST();

MW[] A work matrix; see “COMP” on page 576 for

more details.

RECI.NUMFIELDS Holds the number of fields on the input

record file.

RECI.NUMRECORDS Holds the number of records in the input

record file.

RECI.RECERR Holds the current error status of the input

record file.
0 indicates that there is no data error in the
records read.
1 indicates that there is data error in the
records read.

RECI.RECNO Holds the record number of the current

record being processed from the input
record file.

THISPROCESS Contains the process number of the current

process when using intrastep distributed
processing under Cube Cluster.

Z A copy of I.

ZONES Number of zones.

Matrix Program > Using the Matrix program > Introduction to the Matrix program > Built-in functions

Built-in functions
Described in more detail in “COMP” on page 576.
Ma trix p ro g ra m b uilt-in func tio ns

Func tio n D e s c rip tio n

ARRAYSUM() Returns the value of the sum of an array’s

values.

LOWEST() Sum lowest valued cells in a row.

MATVAL() Allow random access to values from

MATIs

ROWADD() Add matrices.

ROWAVE() Average cell value where value!=0

ROWCNT() Number of cells whose values != 0

ROWDIV() Divide one matrix by another.

ROWFAC() Factors the row by fac.

ROWFIX() Integerize mw (start at column intrazonal +

1)

ROWMAX() Maximum value in the row.

ROWMIN() Minimum value in the row.

ROWMPY() Multiply one matrix by another.

ROWSUM() Row total

CHECKNAME(NAME) Check if a matrix table/ zonal file field

exists. If it does not exist, the function
returns a zero. If it exists, the return code is
a 2 digit number in the format of {t}{s},
defined as follows:
{t} is type
0=single variable
1=vector
2=user function
3=work matrices
4=user function
5=user function
6=vector with constant index and
no default index
7=multidimensional array, no
default index
{s} is storage size
1=numeric
2=string
e.g. 1=numeric variable, 2=string
variable, 11=numeric array, 12=string
 array

GETVALUE(NAME {(, Get a numeric value from a matrix

DEFAULTVALUE}) table/zonal file field. This function is used
along with the CheckName function.
CheckName checks the existence of a
matrix table/ zonal file field and GetValue
extracts the value from the matrix table/
zonal file field. They are used to avoid
model run crash due to non-existence or
invalid value of a matrix table/ zonal file
field in the input flies. Users can specify a
default value in case of any invalid
values.
Note: MI.x.x must be used with an
explicit JLOOP block where the default
index of I and J wil be set to correct origin
and destination by the Matrix Program.
JLOOP
IF CHECKNAME(‘MI.1HBW’) hbw
= GETVALUE(“MI.1.HBW’)
ENDJLOOP

GETMATRIXROW(NAME Load a MI matrix row into a MW. Name

,MW# {(, must be a MI.x.x name. The return
DEFAULTVALUE}) code can be the following:
0=matrix row loaded successfully
1=invalid name or other errors, the
default value is used
2=invalid name or other errors and no
default value is supplied, program
terminating
nn=GetMatrixRow(‘MI.1.NHB’,2,1)
Matrix Program > Using the Matrix program > Introduction to the Matrix program > Transposed matrices

T ransposed matrices
A copy of a transposed input is obtained by referencing a variable with a name of
MI.n.name.T. In Matrix program terminology, a transposed matrix is one that has had its
rows and columns switched. See “COMP” on page 576 for details.
Matrix Program > Using the Matrix program > Control statement types in Matrix program

Control statement types in Matrix program

There are several types of control statements used in the Matrix program:
• Definition statements — Define static processes.
m
ARRAY
m
FILEI and FILEO (which define the input and output data.)
m
LOOKUP
m
PARAMETERS
m
RENUMBER

• Computational statements — Cause variable values to be updated.

m
BSEARCH
m
CALL
m
CHOICE
m
COMP
m
FREQUENCY
m
SET
m
XCHOICE

• Reporting statements — Cause values to be accumulated and/or displayed dynamically.

m
FREQUENCY
m
PRINT
m
PRINTROW
m
REPORT

• Flow control statements — Set which statement is to be performed next.

m
GOTO
m
:label
m
BREAK CONTINUE LOOP ENDLOOP JLOOP ENDJLOOP
m
IF ELSEIF ELSE ENDIF
m
EXIT

For more details about control statements, see “Control statements” on page 545.
Matrix Program > Using the Matrix program > Working with intrazonal cells of a matrix

Working with intrazonal cells of a matrix

During the processing of demand data it is often necessary to access the intrazonal
element of a matrix or to set its value. Special keywords INTRAZONAL or INTRA are
provided to assist in this.
To set the intrazonal element of a matrix row, amend the normal COMP command to take
one of the following forms:
• INTRAZONAL MW[x] = expression

• COMP MW[x][INTRAZONAL] = expression

• COMP MW[x][INTRA] = expression

where x indicates the appropriate working matrix number. When such commands are
executed, all elements of the matrix which lie off the diagonal are left unchanged.
Note that it is invalid to use the above forms of calculation with a JLOOP (as JLOOP implies
varying the J, or column, whereas INTRAZONAL or INTRA fixes it to I, or the row index).
Neither can it be used with the INCLUDE or EXCLUDE subkeywords of the M[] statement,
which are used to select destination zones.
Such commands may be used in conjunction with the LOWEST function set an intrazonal
cost based on the cost to the nearest zone(s). As an example:
INTRAZONAL mw[10] = 0
INTRAZONAL mw[10] = LOWEST(10, 1, 0.01, 99999)

sets the intrazonal cost to the cost from the origin to the nearest destination, but ignoring
destinations with costs less than 0.01 or more than 99999. The preceding setting of
MW[10]’s intrazonal cell to zero ensures that any starting value in that cell does not
become the result of the LOWEST function.
The INTRAZONAL or INTRA keywords may be used to access the diagonal element of a
matrix during calculations. This keyword is coded in a similar manner to the j (or column)
position when a matrix is referenced in an arithmetic expression. Examples are:
MW[1] = MW[1][INTRA]

which copies the intrazonal (or diagonal) element of the first working matrix into all
column positions, and:
var1 = MW[10][INTRAZONAL]

which sets a scalar variable var1 to the intrazonal element of working matrix ten, taken
from the current row of the matrix.
Matrix Program > Using the Matrix program > Working with lists of zones

Working with lists of zones

When modeling travel demand, it is often necessary to apply different treatments to
various types of zones, and similarly to movement types within matrices. Examples of
such zone groupings are the CBD (central business district), industrial zones, the
suburbs, or zones corresponding to external cordon points. Any of these areas
comprises a list of zone numbers; lists which are lengthy and used on many occasions
in processing could easily be a source of errors in typing or updating. To avoid such
difficulties, such lists of zones may be set up once, given a suitable descriptive name to
identify them, and then used wherever appropriate in the modeling.
This section outlines two methods:
• Working with lists of zones using the INLIST function — Uses the INLIST function to select
required zones; it is simple to define lists, but their use is restricted to arithmetic
computations.

• Working with list of zones using the substitution method — Defines lists in the Pilot program,
then uses the substitution facility to work with them; it is less easy to define the required
lists, but they may be used in a wider range of contexts.
Matrix Program > Using the Matrix program > Working with lists of zones > Working with lists of zones using the INLIST
function

Working w ith lists of zones using the IN LIST function

As an example, zones 1 to 12 and 15 to 20 form the CBD of a study area. A list called
CBD may be defined, using the COMP or computation control statement. The list of
zones is specified as text data which is enclosed in quotes ('). The INLIST function is
then used to construct a condition which determines whether its origin and/or destination
are in the specified list. The INLIST function gives a value of 1 when the particular zone
(first parameter) is found in the specified list (the second parameter). The particular zone
under consideration is often i (the origin zone) or j (the destination zone). The following
example illustrates the use of this facility:
CBD='1-12,15-20'
suburbs='23-30,34-41,43,47,50-57'
...
IF (INLIST(i,CBD) = 1)
; commands here will be processed for origins in the CBD
....
ENDIF
....
JLOOP
IF (INLIST (j,suburbs) = 1)
; commands here processed for destinations in the suburbs
....
ENDIF
ENDJLOOP
IF (INLIST(i,suburbs) = 1)
JLOOP
IF(INLIST(j,CBD)=1)
; commands are processed for flows which have both
; origins in suburbs and destinations in CBD
....
ENDIF
ENDJLOOP
ENDIF
Matrix Program > Using the Matrix program > Working with lists of zones > Working with list of zones using the substitution
method

Working w ith list of zones using the substitution method

As an example, zones 1 to 12 and 15 to 20 form the CBD of a study area. A list called
CBD may be defined, using the COMP or computation control statement. The list of
zones is specified as text data which is enclosed in quotes ('). This is done in the script
before any RUN PGM statements for programs, and forms part of the script of the Pilot
program. Wherever this list of zones is required by a program, its script contains the
name of the list, which is enclosed by @ symbols (denoting substitution of the list of
zone numbers, in place of the list’s name). The example:
CBD='1-12,15-20'
...
RUN PGM = MATRIX
...
MX[10]=mi.1.LOSmatrix
...
JLOOP INCLUDE = @CBD@
MX[10] = MX[10] + 10
ENDJLOOP
...
...
ENDRUN

defines the list of zones in the CBD, then adds a parking cost of 10 units into the skim
(or level of service) matrix for destination zones in that area.
The defined list may contain individual zone numbers and / or ranges of zone numbers;
the latter are specified in the form 1-10 with neither space or ',' (comma) between the
start and end values. To ensure that the list is generally acceptable, it should be written
with commas between items. (Although Cube Voyager scripting allows spaces to be
used as delimiters between items of a list, this form is not accepted by the conditional or
IF statement which requires commas, and so use of commas is recommended.)
A further example changes that part of a matrix which corresponds to origins in the
suburbs and destinations in the CBD, dividing these matrix cells by 1.05:
...
suburbs = '100-145,148-191,194-224,227-341'
CBD = '1-12,15-20'
...
RUN PGM = MATRIX
...
if(i = @suburbs@)
jloop
if(j = @CBD@)
mw[1]=mw[1]/1.05
endif
endjloop
endif
...
 ...
ENDRUN

The calculation may be expressed more concisely as:

if(i = @suburbs@)
jloop include = @CBD@
mw[1]=mw[1]/1.05
endjloop
endif

or even:

if(i = @suburbs@) mw[1]=mw[1]/1.05 include=@CBD@

The following illustrates the case where the calculation applies to all destination zones
for selected origins:
...
CordonZones = '540-578'
...
RUN PGM = MATRIX
...
if(i = @CordonZones@)mw[5]=mw[5] * 1.27
...
ENDRUN
Matrix Program > Using the Matrix program > Working with logit choice models

Working with logit choice models

This section discusses logit choice models. Topics include:
• Introduction to choice modeling

• Absolute logit model

• Incremental logit model

• Hierarchical logit model

• Destination choice

• Mode and destination choice

• General notes
Matrix Program > Using the Matrix program > Working with logit choice models > Introduction to choice modeling

Introduction to choice modeling

The XCHOICE command in Cube Voyager scripting provides powerful extensions to
the core language designed to allow complex logit choice models to be specified easily.
XCHOICE was introduced in version 4.1 of Cube Voyager to replace the CHOICE
control statement. XCHOICE implements the same logit model structures as the original
CHOICE statement but improves choice-model run times. A choice model implemented
with XCHOICE should run significantly faster than the same model implemented with
CHOICE.

Existing choice models that use the CHOICE statement will continue to run as scripted.
However, Citilabs recommends modifying existing models to use the XCHOICE
command statement and take advantage of the improvements in run time. Note that
some of the keywords are different with the XCHOICE command statement. When
converting a logit model that uses CHOICE to use XCHOICE, you must make additional
changes at the keyword level. For more information please refer to “XCHOICE” on
page 565.
Logit choice models have a number of distinct possible outcomes (for example mode of
travel), and the model estimates the probability of choosing each particular outcome.
The alternatives are evaluated using either their costs or their utility values. Costs and
utilities are related. As the utility of an alternative increases the alternative becomes
more attractive, but an increase in cost makes the alternative less attractive. Apart from
sign, the other difference is that a utility directly measures the users benefit, whereas the
cost has to be multiplied by an appropriate coefficient (or scale parameter) before use in
choice models.
The simplest choice model splits total travel demand between two alternatives (or
modes); it is known as the binary choice model. This may be extended by adding further
alternatives, so forming a multinomial model.
In practice when several alternatives exist, the alternatives are not always independent
of each other. To overcome this hierarchic choice models are used which sub-divide the
choice process into a sequence of decisions. Alternatives which are similar are grouped
together to form sub-nests. Typical examples of sub-nests are public transport (which
brings together various transit modes), or car use (which includes through-trip by car
and park-and-ride). These sub-nests are then brought together in the main (or top-level)
choice process. The choice process may be viewed as initially choosing between sub-
nests (representing types of travel), and then choice at the sub-nest level which decides
the mode used.
The simple choice and hierarchic models described above are forms of the “absolute”
logit choice model.
An alternative form is the Incremental model (also known as the Pivot Point model)
which has a different methodology. It uses data for demand (by alternative) in the base
situation together with changes in costs (or utilities) between the base and forecast
scenario, in order to re-allocate the demand between the alternatives in response to
those cost changes.
The destination choice model is an extension to the logit choice concept where the
alternatives are not modes of travel, but destination zones which the traveler chooses
between. It may be combined with mode choice to form complex models, and may be
used in absolute or incremental form.
The section uses a number of examples to illustrate use of the CHOICE command and to
explain the underlying theory. The examples start at the simplest level and increase in
complexity. They are:
• Absolute logit model

• Incremental logit model

• Hierarchical logit model

• Destination choice

• Mode and destination choice

Each model is described in the context of a typical problem, supported with the relevant
theory. Then the method for implementing a solution in the Matrix program is shown,
with example scripts. For some models, alternative strategies or more complex
variations are also illustrated. Finally, any practical issues related to setting up such a
model are discussed.
At the end of the section there are some general notes concerning coding of demand
models.
For a detailed description of the demand modeling function syntax see “XCHOICE” on
page 565.
Matrix Program > Using the Matrix program > Working with logit choice models > Absolute logit model

Absolute logit model

This section discusses the absolute logit model. Topics include:
• Introduction

• Logit Choice model

• Scale parameter (cost-based models)

• Matrix script for cost-based model

• Matrix script for utility-based model

Matrix Program > Using the Matrix program > Working with logit choice models > Absolute logit model > Introduction

Intro ductio n

This section introduces a straightforward example of an aggregate demand model.

Suppose that in a transport system there are just two discrete competing modes—car and
public transport (PT)— between a given set of origins and destinations. A user of such a
system is said to have a binary choice, because there are just two alternatives (car and
PT).
The following paragraphs explain how the absolute logit model can be
applied to the problem of estimating the probability of choosing each
mode, and in particular how this is implemented in Cube Voyager.
Matrix Program > Using the Matrix program > Working with logit choice models > Absolute logit model > Logit Choice model

Lo git Cho ice m o del

The process begins by calculating the generalized cost of travel between each origin
and destination by either mode. Usually, this cost is a linear combination of the monetary
cost (fare, fuel, etc.) and time (walk, wait, interchange, in-vehicle-time, etc.). There may
also be an additive constant to approximate those elements of the cost that cannot be
readily quantified, for example the convenience of bus services, or the quality of railway
rolling stock. Let’s call the cost of travel by car, Ccar, and by PT, Cpt. Suppose that
there is a total demand, D, that make such a journey in a given period.
For the sake of clarity, subscripts relating to the origin and destination zone have been
omitted.
The Absolute Logit Model states that the probabilities of choosing car, Pcar, and PT,
Ppt, are given by the equations below.

Where λ is the scale parameter, of which more later.

The forecast demand for car is given by Dcar and for PT, Dpt.

The model also calculates a composite cost (C) that represents the cost of
the combined choice (in this case, car and public transport), where:
Where utilities are used instead of costs, this simple choice model does
not require a distinct scale parameter, as its effects have already been incorporated into
the utility values. Using utilities, the probabilities of choosing car, Pcar, and Ppt, are:

the composite utility (or logsum) is:

and the equations for demand by alternative (Dcar, etc.) are as given
above.
Matrix Program > Using the Matrix program > Working with logit choice models > Absolute logit model > Scale parameter
(cost-based models)

Scale param eter (co st-based m o dels)

The behavior of the model is determined by a positive constant known as the scale
parameter, called λ in the equations above. The graph below illustrates the model
sensitivity with different values of λ.
If λ=0 the model is completely insensitive to cost, and demand is shared equally
between each of the available choices. Notice that Pcar=½ and Ppt=½ when λ=0.

As λ increases, the sensitivity of the logit model increases, progressively allocating more
demand to the choice with the lower cost. The figure “Logit model sensitivity” on
page 521 shows how the model becomes more responsive to the difference in cost for
λ =0.01, 0.02 and 0.04.

Finally, as λ approaches infinity, the model will allocate all the demand to the alternative
with the lowest cost.
The value of the scale parameter will depend on the nature of the choice, characteristics
of the demand and the units of cost. The examples used here are for illustrative
purposes and should not be adopted as default values.
Lo git m o del sensitivity

Where choice models are based on utilities, there is no cost coefficient

as it has already been combined with the actual cost to form the utility
values. Thus for simple choice models, the scale parameter is not
required. Scale parameters are used in more complex (or hierarchic) models, but their
specification and values are different from the style of use in cost-base models.
Matrix Program > Using the Matrix program > Working with logit choice models > Absolute logit model > Matrix script for
cost-based model

M atrix script fo r co st-based m o del

This section describes how this example can be implemented using the XCHOICE
command. The fragment of script below will run this model. Variable names have been
chosen to match those used in the preceding equations.
; Absolute logit model
XCHOICE,
; List choices
ALTERNATIVES = car, pt,
; Input total demand
DEMANDMW = 10,
; Input costs
COSTSMW = 3, 4,
; Forecast demand
ODEMANDMW = 15,16,
; Model structure
SPLIT = TOTAL 0.02 car pt,
; Forecast composite cost
SPLITCOMP = 19,
; Working matrices
STARTMW = 30

The XCHOICE command comprises a number of clauses of the form keyword = value(s)
each of which defines some aspect of the logit choice model. These specify what
alternatives may be chosen, the inputs to the calculations, the resulting outputs, and the
structure of the logit choice model.
The block begins with the ALTERNATIVES clause listing of the names of the alternatives. In
this case the choices are car and PT. These names will be used later to define the
model structure.
The model inputs are specified, starting with the total demand which is coded in the
DEMANDMW clause. The specified input may represent a matrix of true demand (in trips),
as shown here using MW[10], or it may be set to 1, in which case the output “demand”
will be the probabilities associated with each alternative. Next, the generalized costs are
specified for car, as matrix MW[3], and PT, as matrix MW[4]. These should be listed in
the same order as the modes in the ALTERNATIVES clause.
Now the output variables are specified. These are forecast demand for each alternative,
again specified in the same order as the ALTERNATIVES clause, so MW[15] will contain
car trips and MW[16] PT trips.
Finally the structure of the choice model is defined. In this example the choice is
between two modes, car and PT, but this may be extended to three or more alternatives.
The SPLIT clause defines the model’s structure in terms of the scale parameter (or
coefficient of generalized costs) and the choices given in the ALTERNATIVES clause. The
word TOTAL indicates that the entire input demand is to be split between the alternatives
listed in this specification. The scale parameter has a value of 0.02 (or λ=0.02 in the
above equations) and the choice is between the car and PT alternatives. In this script,
the scale parameter is given as a numerical value but it is equally valid to use a variable
instead. The forecast composite cost is output as MW[19] with the SPLITCOMP
keyword. Both the forecast demand and composite cost are optional outputs, and either
clause may be omitted from the script.
The calculations performed by the logit choice model require a number of working
matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW
clause specifies a working matrix number which is higher than that of any other working
matrix referenced in the script. Working matrices from the STARTMW value upwards are
used by the XCHOICE command, and should not be used elsewhere in the script. Where
a Matrix program script contains several XCHOICE commands, the same STARTMW value
may be used in all instances.
Matrix Program > Using the Matrix program > Working with logit choice models > Absolute logit model > Matrix script for
utility-based model

M atrix script fo r utility-based m o del

This section describes how this example can be implemented using the XCHOICE
command. The fragment of script below will run this model. Variable names match those
used in the preceding equations.
; Absolute logit model
XCHOICE,
; List choices
ALTERNATIVES = car, pt,
; Input total demand
DEMANDMW = 10,
; Input utilities
UTILITIESMW = 5, 6,
; Forecast demand
ODEMANDMW = 15,16,
; Model structure
SPLIT = TOTAL car pt,
; Forecast composite utility
SPLITCOMP = 18,
; Working matrices
STARTMW = 40

The XCHOICE command comprises a number of clauses of the form keyword = value(s),
each of which defines some aspect of the logit choice model. These specify what
alternatives may be chosen, the inputs to the calculations, the resulting outputs, and the
structure of the logit choice model.
The block begins with the ALTERNATIVES clause listing of the names of the alternatives. In
this case the choices are car and PT. These names will be used later to define the
model structure.
The model inputs are specified, starting with the total demand which is coded in the
DEMANDMW clause. The specified input may represent a matrix of true demand (in trips),
as shown here using MW[10], or it may be set to 1, in which case the output “demand”
will be the probabilities associated with each alternative. Next, the utilities for car, as
matrix MW[5], and PT, as matrix MW[6]. These should be listed in the same order as
the modes in the ALTERNATIVES clause.
Now the output variables are specified, as working matrix (MW) numbers. These are
forecast demand for each alternative (MW[15] for car trips and MW[16] for PT, again
specified in the same order as the ALTERNATIVES clause).
Finally the structure of the choice model is defined. In this example the choice is
between two modes, car and PT, but this may be extended to three or more alternatives.
The SPLIT clause defines the model’s structure in terms of the choices given in the
ALTERNATIVES clause; here the choice is between the car and PT alternatives. The word
TOTAL indicates that this split divides the entire input demand between the specified
alternatives. The forecast composite utility is output as MW[18] with the SPLITCOMP
keyword. Both the forecast demand and composite utility are optional outputs, and either
clause may be omitted from the script.
The calculations performed by the logit choice model require a number of working
matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW
clause specifies a working matrix number which is higher than that of any other working
matrix referenced in the script. Working matrices from the STARTMW value upwards are
used by the XCHOICE command, and should not be used elsewhere in the script. Where
a Matrix script contains several XCHOICE commands, the same STARTMW value may be
used in all instances.
Matrix Program > Using the Matrix program > Working with logit choice models > Incremental logit model

Incremental logit model

This section discusses the incremental logit model. Topics include:
• Introduction

• Incremental logit choice model

• Matrix script for cost-based model

• Alternative script using cost differences

• Matrix script for utility-based models

• Alternative script using differences in utilities

Matrix Program > Using the Matrix program > Working with logit choice models > Incremental logit model > Introduction

Intro ductio n

This example returns to the structure of the absolute choice example, but now forecasts
the change in demand based on the change in cost from a known base situation. This is
known as the incremental form of the logit model. The structure of the model shown
below in Figure 1.
This model is developed, both using costs and utilities below.
Matrix Program > Using the Matrix program > Working with logit choice models > Incremental logit model > Incremental logit
choice model

Increm ental lo git cho ice m o del

The model inputs are base demand by mode (Dcar, Dpt), base costs by mode (Ccar,
Cpt) and forecast costs by mode (C’car, C’pt). The change in cost is denoted by DCcar
and DCpt where:

Base probabilities are denoted by Pcar and Ppt where:

The choice model now takes the form of the equation below where P’
denotes the forecast choice probability and λ is the scale parameter.
So that the forecast demand by mode (D’car, D’pt) is:

The incremental composite cost (DC) is given by:

When working with utilities, the above equations are adapted to reflect
the absence of any scale parameter (as this is combined into the utility
values). The utility differences are calculated as:
and the probabilities of using each alternative are:
The equations for base and forecast demand by mode are the same as
for cost-based models. The utility-based form of the composite costs is
given by:
Matrix Program > Using the Matrix program > Working with logit choice models > Incremental logit model > Matrix script for
cost-based model

M atrix script fo r co st-based m o del

Comparing the example code below with the first example (same structure, but an
absolute logit model), one can see that only the model inputs change to construct an
incremental model. The model requires base demand, base costs and forecast costs for
both modes as input. The output composite cost is the incremental change in composite
cost.
; Incremental logit model
XCHOICE,
; List choices
ALTERNATIVES = car, pt,
; Input base demand by mode
BASEDEMANDMW = 10, 11,
; Input base costs by mode
BASECOSTSMW = 20, 21,
; Input forecast costs by mode
COSTSMW = 30, 31,
; Forecast demand
ODEMANDMW = 2,3,
; Model Structure
SPLIT = TOTAL 0.02 car pt,
; Forecast incremental composite cost
SPLITCOMP = 7,
; Working matrices
STARTMW = 40
Matrix Program > Using the Matrix program > Working with logit choice models > Incremental logit model > Alternative script
using cost differences

Alternative script using co st differences

The XCHOICE command allows cost changes to be given instead of base and forecast
costs. This variant is particularly useful when the costs do not change for all modes. For
example, suppose that the car cost is constant and that a series of tests are to be
conducted for different PT scenarios. In this case, there is no need to calculate the car
cost for each test. Instead, the change in car cost, DCcar, can be set to zero. Where the
cost difference is zero, the numeric value may be specified as the cost difference for the
alternative (rather than needing to construct a matrix of zero values).
The example excludes the calculation of incremental composite costs.
; Incremental logit model (specifying cost differences)
; Specify scale parameter (or cost coefficient)
lambda = 0.02
XCHOICE
; List choices
ALTERNATIVES = car, pt,
; Input base demand by mode
BASEDEMANDMW = 10, 11,
; Input CHANGE in cost (= ForecastCost - BaseCost)
DCOSTSMW = 24, 25,
; Forecast demand
ODEMANDMW = 2,3,
; Model Structure
SPLIT = TOTAL lambda car pt,
; Working matrices
STARTMW = 30
Matrix Program > Using the Matrix program > Working with logit choice models > Incremental logit model > Matrix script for
utility-based models

M atrix script fo r utility-based m o dels

Comparing the example code below with the first example (same structure, but an
absolute logit model), one can see that only the model inputs change to construct an
incremental model. The model requires base demand, base costs and forecast costs for
both modes as input. The output composite cost is the incremental change in composite
cost.
; Incremental logit model
XCHOICE,
; List choices
ALTERNATIVES = car, pt,
; Input base demand by mode
BASEDEMANDMW = 10, 11,
; Input base costs by mode
BASEUTILSMW = 20, 21,
; Input forecast costs by mode
UTILITIESMW = 30, 31,
; Forecast demand
ODEMANDMW = 2,3,
; Model Structure
SPLIT = TOTAL car pt,
; Forecast incremental composite utilities
SPLITCOMP = 7,
; Working matrices
STARTMW = 50
Matrix Program > Using the Matrix program > Working with logit choice models > Incremental logit model > Alternative script
using differences in utilities

Alternative script using differences in utilities

The XCHOICE command allows changes in utility to be given instead of base and
forecast utilities. This variant is particularly useful when the costs do not change for all
modes. For example, suppose that the car cost is constant and that a series of tests are
to be conducted for different PT scenarios. In this case, there is no need to calculate the
car utility for each test. Instead, the change in car utility, DCcar, can be set to zero.

The example excludes the calculation of incremental composite costs.

; Incremental logit model (specifying cost differences)
XCHOICE
; List choices
ALTERNATIVES = car, pt,
; Input base demand by mode
BASEDEMANDMW = 10, 11,
; Input CHANGE in cost (= ForecastCost - BaseCost)
; Car Utilities are unchanged, so are specified as '0'
DUTILSMW = 24, 25,
; Forecast demand
ODEMANDMW = 2,3,
; Model Structure
SPLIT = TOTAL car pt,
; Working matrices
STARTMW = 100
Matrix Program > Using the Matrix program > Working with logit choice models > Hierarchical logit model

Hierarchical logit model

This section describes the hierarchical logit model. Topics include:
• Introduction

• Cost-based examples of hierarchic logit models

• Utility-based examples of hierarchic logit models

Matrix Program > Using the Matrix program > Working with logit choice models > Hierarchical logit model > Introduction

Intro ductio n

The second example splits the PT mode of the first example into two distinct sub-
modes; bus and train. This is an example of a Hierarchical Logit Model, which can be
implemented in Absolute or Incremental form.
Structure o f hierarchical lo git m o del

Hierarchic models group related choices together in nests (or

hierarchies). In this example, bus and train are members of the public
transport nest that is considered to be distinct from the (private) car mode.
In an absolute model, the choice probabilities are calculated by starting at the bottom of
the tree and moving up the hierarchy, calculating the choice probabilities and the
composite costs in each nest. In this model the process begins in the PT nest.
Firstly, conditional probabilities for each of the two PT modes (Pbus|pt and Ptrain|pt) and
the composite PT cost are calculated within the lower nest with equations similar to
those in the previous section. The composite PT cost will be used next to represent the
cost associated with the combined PT choice.
The choice probabilities for car (Pcar) and all PT (Ppt) can now be calculated using the
technique described in the first example.
It is now possible to move back down the hierarchy forecasting demand for each mode
with the information derived above, so that:
For incremental models, the calculations are again performed in two
stages, using the equations of the Incremental Logit Choice Model. The
first pass calculates conditional probabilities and composite costs
working up the tree structure; then in the second pass working down
the tree, the resulting probabilities are calculated.
Matrix Program > Using the Matrix program > Working with logit choice models > Hierarchical logit model > Cost-based
examples of hierarchic logit models

Co st-based exam ples o f hierarchic lo git m o dels

As before the total demand is specified together with generalized costs for each choice
(car, bus and train).
A scale parameter must be associated each nest. In this example, the scale parameters
are λ=0.02 in the upper nest (consistent with the previous example) and μ=0.03 in the
lower nest. It is a result of the model theory that the value of the parameters must
increase (or at least not decrease) as one moves down the hierarchy. That is to say, the
model’s sensitivity to cost increases down the hierarchy.
M atrix script

The example below shows how the earlier absolute-choice example can be extended to
include the lower nest in the hierarchy:
; Absolute hierarchical logit model
; Specify scale parameters
lambda = 0.02
mu = 0.03
XCHOICE,
; List choices
ALTERNATIVES = car bus train,
; Input demand
DEMANDMW = 1,
; Input costs
COSTSMW = 4, 5, 6,
; Forecast demand
ODEMANDMW = 14,15,16,
; Model Structure
; Top level nest
SPLIT = TOTAL lambda car pt,
; Forecast composite cost top level
SPLITCOMP = 19,
; PT nest
SPLIT = PT mu bus train
; Forecast composite cost PT level
SPLITCOMP = 20,
; Working matrices
STARTMW =70

First the modes (car, bus and train) are declared with the ALTERNATIVES clause. Notice
that PT is not declared as an alternative; this is the name given to the combined choice
of bus and train.
Then the model inputs and outputs are specified. The input total demand and costs for
the three distinct modes are given first, followed by the output forecast demand by mode.
The hierarchical structure is specified by moving down the tree describing each nest.
Beginning at the top of the tree, the first split command divides TOTAL (the total
demand) into car and (all) PT with scale parameter λ=0.02. Notice that a scalar variable
called lambda has been used to represent the scale parameter in this case. PT is not
considered as an individual mode now, but as a link with the lower nest. The SPLITCOMP
keyword computes the composite costs for the nest associated with this SPLIT, in this
case the top level.
The second split command sub-divides PT trips between the bus and train alternatives
using a scale parameter μ=0.03. The name pt is used as the first value in the SPLIT
clause, and this acts as a link to the next level up the tree (where total demand was
divided between car and PT). Another SPLITCOMP keyword for this SPLIT keyword
computes the composite costs specific to the PT nest.
M o re co m plex abso lute hierarchical m o dels

The hierarchy can be extended with additional nests on either side of the tree. For
example, a large absolute hierarchical logit model structure might have six choices: car,
park and ride, bus, heavy rail, light rapid transit (LRT), and metro.
Structure o f a large abso lute hierarchical lo git m o del

M atrix script illustrating the co m plex exam ple

This example may be codes as an absolute model as below, with park and ride
abbreviated as pandr, and heavy rail as hrail:
; Extract from a large absolute logit model
XCHOICE,
; List choices
ALTERNATIVES = car pandr bus hrail lrt metro,
; Input demand
DEMANDMW = 1,
; Input costs
COSTSMW = 11, 12, 13, 14, 15, 16,
; Forecast demand
ODEMANDMW = 21,22,23,24,25,26,
; Model Structure
; Top level nest
SPLIT = TOTAL 0.02 allcar allpt,
; All car nest
SPLIT = allcar 0.05 car pandr,
; All PT nest
SPLIT = allpt 0.03 bus train,
; Train nest
SPLIT = train 0.04 hrail lrt metro,
; Working matrices
STARTMW = 45
Matrix Program > Using the Matrix program > Working with logit choice models > Hierarchical logit model > Utility-based
examples of hierarchic logit models

Utility-based exam ples o f hierarchic lo git m o dels

Scale param eter in utility-based m o dels

The hierarchic choice model comprises a main choice nests, and a number of sub-
nests. As with cost-based models, there is a requirement that higher level nests are less
sensitive to cost differences than any sub-nests which lie below them.
In the estimation of the utility equations used in the choice model coefficients are
estimated for individual cost-terms (such as travel time, and fare) and for scale
parameters. The scale parameter is a factor which is applied to the composite utility of a
sub-nest before it is used in the choice process of the parent choice nest. To meet the
sensitivity requirements noted above, the scale parameter must be greater than 0, and
must not exceed 1.0.
Thus, the scale parameters of utility-based models are viewed as part of the
specification of the output of a split process, and different values may apply to each sub-
nest in a choice nest. Where the scale parameter for a sub-nest is 1.0 there is no need
to specify its value as this the assumed default. Where a scale parameter applies to two
or more sub-nests, it may be specified once and brackets used to group the relevant
sub-nests, so avoiding repetition of the parameter.
M atrix script illustrating two -level hierarchy

Using the tree structure shown in “Structure of hierarchical logit model” on page 531 as
the basis of an absolute choice model, the total demand is specified together with the
utility of each choice (car, bus and train).
A scale parameter of 0.6 is applied to the PT sub-nest when its composite (or logsum)
utility is used in the calculations of the higher-level nest.
; Absolute hierarchical logit model
XCHOICE,
; List choices
ALTERNATIVES = car bus train,
; Input demand
DEMANDMW = 1,
; Input costs
UTILITIESMW = 4, 5, 6,
; Forecast demand
ODEMANDMW = 14,15,16,
; Model Structure
; Top level nest. PT sub-nest has scale parameter 0.6
SPLIT = TOTAL 1.0 car 0.6 pt,
; Forecast composite cost for the top level
SPLITCOMP = 19,
; PT nest
SPLIT = PT bus train
; Forecast composite cost for the PT nest
SPLITCOMP = 20,
; Working matrices
STARTMW =70

First the modes (car, bus and train) are declared with the ALTERNATIVES clause. Notice
that PT is not declared as an alternative; this is the name given to the combined choice
of bus and train.
Then the model inputs and outputs are specified. The input total demand and utilities for
the three distinct modes are given first, followed by the output forecast demand by mode.
The hierarchical structure is specified by moving down the tree describing each nest.
Beginning at the top of the tree, the first split command divides TOTAL (the total
demand) into car and (all) PT, and specifies a scale parameter of 0.6 which applies to
the PT sub-nest. PT is not considered as an individual mode now, but as a link with the
lower nest. The composite costs for this SPLIT are output with SLITCOMP.
The second split command sub-divides PT trips between the bus and train alternatives,
but no scaling parameters are used. The name pt is used as the first value in the SPLIT
clause, and this acts as a link to the next level up the tree (where total demand was
divided between car and PT). The composite cost for this SLIT are output with another
SPLITCOMP keyword.
M atrix script illustrating the co m plex exam ple

A more complex utility-based example uses the model structure illustrated in “Structure
of a large absolute hierarchical logit model” on page 534. The example below is coded
below in incremental form using utility differences:
; Extract from a large absolute logit model
XCHOICE,
; List choices
ALTERNATIVES = car pandr bus hrail lrt metro,
; Base demand
BASEDEMANDMW = 1, 2, 3, 4, 5, 6,
; Utility differences
DUTILSMW = 11, 12, 13, 14, 15, 16,
; Forecast demand
ODEMANDMW = 21,22,23,24,25,26,
; Model Structure
; Top level nest
SPLIT = TOTAL 0.4 allcar 0.667 allpt,
; All car nest
SPLIT = allcar car pandr,
; All PT nest
SPLIT = allpt 1.0 bus 0.75 train,
; Train nest
SPLIT = train hrail lrt metro,
; Working matrices
STARTMW = 45

In this example a scale parameter of 0.4 is applied to the all-car sub-nest; also 0.667 to
the all-PT sub-nest and 0.75 to the train sub-nest.
Matrix Program > Using the Matrix program > Working with logit choice models > Destination choice

Destination choice
This section describes the destination-choice model. Topics include:
• Introduction

• Matrix script
Matrix Program > Using the Matrix program > Working with logit choice models > Destination choice > Introduction

Intro ductio n

This section shows how a logit model can be used to forecast destination choice.
Suppose that an aggregate demand model has 100 zones. Associated with each origin
zone (denoted i) there is a total demand of Di that is to be distributed between the 100
possible destinations (denoted j) according to the cost of the trip Cij. The figure
“Structure of destination choice model” illustrates the structure, where d1, d2,... denote
the choice of destination 1, destination 2 and so on.
Structure o f destinatio n cho ice m o del

For the absolute choice model, the probability of choosing destination zone j from origin
zone i is given by Pij:

Where λ is the scale parameter. This equation is no more than a

generalized case of the equation in the absolute logit model that
forecasts the demand for car and PT. In this case, the choices are
destination zones.
The incremental logit model is also supported. Its underlying theory is similar to the
equations in the incremental logit model, but with alternative modes replaced by
destination zones. In this model, the base situation matrices of demand and cost (or cost
differences) are also input rather than total travel demand. The incremental model is
more widely used in studies than the absolute formulation.
For absolute utility-based models, the destination choice model takes the form:
The incremental forms of logit choice model is also supported, and uses
the incremental choice equations with alternative modes replaced by
different destination zones. The clauses defining data input reflect the
data required by the model, for examples UTILITIESMW (utilities) and DUTILSMW
(differences in utilities).
Matrix Program > Using the Matrix program > Working with logit choice models > Destination choice > Matrix script

M atrix script

The destination choice model described above is coded in the script below.
;Simple destination choice model
;Specify choice parameter
lambda = 0.01
XCHOICE,
; Alternatives (only one, as doing destination choice)
ALTERNATIVES = all
; Input demand from each origin
DEMAND = TripsFromI[i],
; Input cost matrix
COSTSMW = 3,
; Forecast demand from each origin to each destination
ODEMANDMW = 7
; Model Structure
DESTSPLIT = TOTAL lambda all,
; Working matrices
STARTMW = 20

The extract begins with the specification of alternatives, which comprises just one
alternative as we have no choice between modes. This is followed by the model inputs,
in this case the demand is an array of trips from each zone and the generalized cost is
matrix MW[3]. The outputs are a forecast demand matrix, MW[7].
The structure of this model is defined by the DESTSPLIT clause which defines a
destination choice process. A scale parameter of λ=0.01 has been chosen for this
example. The output from the split clause is the alternative “all,” as listed on the
ALTERNATIVES keyword.
The main differences for utility-based scripts are use of utility keywords (UTILITIESMW
being used in place of COSTSMW), and no use of lambda, the scale parameter, so that the
DESTSPLIT clause now becomes DESTSPLIT = TOTAL all.
Matrix Program > Using the Matrix program > Working with logit choice models > Mode and destination choice

Mode and destination choice

This section discusses the mode-and-destination-choice model. Topics include:
• Introduction

• Mode followed by destination choice

Matrix Program > Using the Matrix program > Working with logit choice models > Mode and destination choice > Introduction

Intro ductio n

The XCHOICE command supports mode followed by destination choice, which is

considered in this section.
The values of scale parameter for the various choice nests, which reflect sensitivity to
cost differences, influence the effectiveness of the model.
Matrix Program > Using the Matrix program > Working with logit choice models > Mode and destination choice > Mode
followed by destination choice

M o de fo llo wed by destinatio n cho ice

Consider this example of mode followed by destination choice. The figure illustrates a
system with two modes, car and PT, and 100 destination zones (labelled d1, d2,...,
d100).
Here the total demand is split first by mode (into two vectors
representing car and PT demand for each origin) then by destination
(giving car and PT matrices).
M atrix script

The script extract below is similar to previous examples shown in “Incremental logit
model” on page 525 and “Destination choice” on page 537.
The model structure specification splits the total demand by mode first with scale
parameter λ=0.01, then across destinations for each mode individually. The parameters
for destination choice are μ=0.02 and θ=0.03 for car and PT respectively.
; Mode choice above destination choice model
; Specify choice parameters
lambda = 0.01
mu = 0.02
theta = 0.03
XCHOICE,
; List choices
ALTERNATIVES = car pt,
; Base Demand
BASEDEMANDMW = 1,2,
; Base Costs
BASECOSTSMW = 11,12,
; Forecast costs
COSTSMW = 21,22,
; Forecast demand matrices by mode
ODEMANDMW = 31,32,
; Model Structure
; Mode choice
SPLIT = TOTAL lambda destcar destpt
; Car destination choice
DESTSPLIT = destcar mu car,
; PT destination choice
DESTSPLIT = destpt theta pt,
; Working matrices
STARTMW=110
Matrix Program > Using the Matrix program > Working with logit choice models > General notes

General notes
This section provides general notes about logit choice models:
• Availability of choices

• Applying choice models to selected parts of matrices

• Practical considerations: Incremental models

• Practical considerations: Scale parameters

Matrix Program > Using the Matrix program > Working with logit choice models > General notes > Availability of choices

Availability o f cho ices

Within a demand model, it is often useful to make certain choices unavailable. For
example, a rail mode might not be a practical alternative for travel between all zones in
the study area. To make a choice unavailable you should give that choice a large
positive generalized cost (or large negative utility). Large in this context is 100 times
greater than typical costs. For example, if costs are up to 400 generalized minutes, try
using a cost of 40000 minutes to make a particular choice unavailable.
Matrix Program > Using the Matrix program > Working with logit choice models > General notes > Applying choice models to
selected parts of matrices

Applying cho ice m o dels to selected parts o f m atrices

There are instances when it is desirable to apply choice models to selected parts of a
matrix, rather than the entire matrix. These typically arise when matrices can be broken
down into distinct segments (such as trips entirely within study area, through trips etc.),
and different choice models apply to these different segments. In some instances the
model structure is common to all segments, but the sensitivity (and so cost-coefficient)
varies between segments. Under these conditions, the cost coefficient may be specified
as a matrix (such as MW[5], or mi.1.coefficient) rather than a scalar value. Where the
model structure varies between segments, or the user wishes to apply the choice model
separately for each segment, the following provides guidance on techniques used.
When a XCHOICE control statement occurs in the Matrix program it will typically be
applied to all cells (or origin-destination pairs). The XCHOICE control statement may be
coded inside a conditional test which selects the origin zones it is applied to:
; test to see if model applies to this origin zone
if (i < 45)
; if so, then apply the model
XCHOICE,
; subsequent clauses of XCHOICE statement, as needed
; ...
endif

For simple choices between alternative modes, this may be extended, by use of the
JLOOP command, to select particular rows and columns of the matrix where the choice
model is applied:
;apply the model to trips from zones 1-45 to zones 46-53
if (i < 45)
JLOOP INCLUDE = 46-53
XCHOICE,
; subsequent clauses of XCHOICE statement, as needed
; ...
ENDJLOOP
endif

Where the choice model applies to a segment which is not a regular set of rows and
columns, but is determined by some other matrix attribute (such as distance from origin
to destination), a script may be coded as follows:
;start a JLOOP to process each origin-destination pair in turn
JLOOP
; test to see if O-D meets selection criteria for the segment
if (mi.1.distance > 50)
; if so, then apply the model
XCHOICE,
; subsequent clauses of XCHOICE statement, as needed
; ...
endif
ENDJLOOP

Where a model seeks to use destination choice, this cannot be coded inside a JLOOP
construct. If only selected destinations are valid for the destination choice, then the
INCLUDE or EXCLUDE sub-keyword should be specified immediately after the DESTSPLIT
keyword in order to include or exclude the required zones.
Matrix Program > Using the Matrix program > Working with logit choice models > General notes > Practical considerations:
Incremental models

Practical co nsideratio ns: Increm ental m o dels

In an incremental model, if the base demand for a choice is zero, the forecast demand
for that choice will always be zero.
This is made clear if one examines the equation in the “Incremental logit model” on
page 525, where, if Pcar=0 then P’car=0 whatever costs are given. If this effect is a
problem, then the modelling approach should be reviewed.
Matrix Program > Using the Matrix program > Working with logit choice models > General notes > Practical considerations:
Scale parameters

Practical co nsideratio ns: Scale param eters

For models calibrated in terms of generalized costs to give sensible results, it is

important to ensure for cost-based models that the size of the parameters increase (or at
least not decrease) as one moves down the hierarchy. That is to say, the model’s
sensitivity to cost increases down the hierarchy. Where these conditions are not met, an
error message will be output.
Matrix Program > Control statements

Control statements
The following control words are available in the Matrix program.

Co ntro l
wo rd D e s c rip tio n

ABORT Abort current program

ARRAY Set arrays and values

BREAK Break out of current process

BSEARCH Finds a key or set of keys in a sorted array, or

series of sorted arrays using a binary search.

CALL Call user’s dll (external process)

CHOICE Implement logit choice models (legacy

command; Citilabs recommends XCHOICE)

COMP Compute variables from expressions

CONTINUE Continue at end of loop statement

EXIT Terminate current program

FILEI Input files

FILEO Output files

FILET Set path for temporary files

FILLMW Fill work matrices

FREQUENCY Accumulate distributions of one matrix versus

another

GOTO Immediate jump to :label

IF ... ELSEIF ... Define IF ENDIF block

ELSE ... ENDIF

JLOOP ... Define a loop for destination zones (J)

ENDJLOOP

LOOKUP Define lookup tables (see Chapter 3, “General

Syntax”)

LOOP ... Define user controlled loop

ENDLOOP

PARAMETERS Set static parameters

PRINT Print variable values

PRINTROW Print a row of a matrix (see Chapter 3, “General

Syntax” for details)
RENUMBER Set zone renumber specifications

REPORT Select standard reports

SET Set multiple variables/arrays to same value

SORT Sort user arrays

WRITE Writes records to a DBF file defined by RECO

XCHOICE Implement logit choice models

Matrix Program > Control statements > ABORT

ABORT
Programs : Distribution, Fratar, Generation, Matrix
Aborts the entire run. Keywords include:
• MS G

Use ABORT to terminate the program and return a fatal code to Cube Voyager. Though
not normally used, you can use this statement to terminate processing due to some
detectable conditions. For example, suppose that during a mode-split process, the
program detects walk access and drive access between the same zone pair, but you
know that this should not occur. You can create a test to find this and abort if it occurs.

Ke y wo rd D e s c rip tio n

MSG |S| Optional message that can be printed

when the program terminates. For
readability, Citilabs recommends 100
characters or less.
Matrix Program > Control statements > ABORT > Example

Exam ple
IF (MW[1][I] != 0) ABORT ; Intrazonal present in MW[1]
INTRA = MW[1][I]
IF (! INTRA)
LIST='No intrazonal value for MW[1] at Zone ', I
ABORT
ENDIF
Matrix Program > Control statements > ARRAY

ARRAY
Programs : Distribution, Fratar, Generation, Matrix
Declares user single and multi-dimension arrays. Keywords include:
• A R R A Y N A ME =n (or =n1[,n2[,n3]...]]])

• T YPE= t

Beginning in version 5.1, multi-dimension arrays can be specified. This has caused the
standard ARRAY statement to take on a new format. The previous format for specifying
string arrays (StringArray=arraysize-stringsize) is no longer valid and must be modified
to the new format. The keyword TYPE is used to specify the size and mode of the array
elements for the arrays that follow it. Multi-dimension arrays provide considerably more
capability – the user can specify up to 9 dimensions for a single array. However, multi-
dimension arrays can take up a significant amount of memory so their usage must be
carefully planned. For example, a double precision array of 1000x1000x100 will take up
800 MB of memory.
Use ARRAY to allocate user arrays. An array is different from a variable in that it
represents vectored data. Values stored to arrays in this program can be numeric or
string. When an array is referenced in an expression, it must include all the indices [ ],
and if any index exceeds its corresponding size, the program will fatally terminate.
Arrays can be useful for different processes; a common use may be to store information
for specific zones. ARRAY statements are not dynamic (stack oriented); they are
allocated prior to any stack operations. When a single dimensioned array appears in a
SET statement, all the cells in the array are set to the same value. Multi-dimensioned
arrays can also be specified with the AUTOMDARRAY keyword on the FILEI MATI|DBI
statements, but the use of those arrays is somewhat different.
A R R A Y k e y wo rd s

Ke y wo rd D e s c rip tio n

ARRAYNAME |I,...| Name of the array that is to be

allocated according to the specified
size: n. ARRAYNAME must be a unique
name. The values following the
keyword represent the highest indexes
possible for the array. The values must
be either a numeric constant, or
ZONES. Arrays are cleared when they
are allocated. The preceding TYPE=
keyword sets the size of the individual
cells of the array, and the mode
(numeric or string) for the cells.

TYPE S TYPE specifies the size of each array

cell. If the array is to be numeric, the
 value may be the number 1, 2 or 4 to
indicate 1-byte (range -128 to +127), 2-
byte (range -32768 to +32767) or 4-byte
(range -2147483648 to +2147483647)
integer data, or the letter F or D, to
indicate single (+- 1.5 x 10^-45 to 3.4 x
10^38 with 7-8 significant digits) or
double precision (+- 5.0 x 10^-324 to 1.7
x 10^308 with 15-16 significant digits)
real data. If the array is to contain string
data, the value should be preceded by
the letter C followed by the maximum
string size; however, any numeric value
other than 1, 2 or 4 will automatically be
cast as string. Strings are limited to 999
characters.
The default TYPE is D (double). The
user must choose the correct data type
for the array that are big enough to hold
the anticipated data but minimize
memory usage. Storing bigger values
in smaller size arrays will not cause
errors or warnings. The values are
simply truncated or modulated to fit the
array element size.

Additional system variables are available so the properties of an array can be accessed
in the script:
• a rra y na me .ty p e — a string that is the same as in the TYPE keyword

• a rra y na me .d ime ns io n — the number of dimensions

• a rra y na me .s ize [ ] — an array of integers for the size of each dimension

When multi-dimension arrays are referenced in COMP statements, several deviations

from the standard COMP syntax rules are available to the user. For example:
COMP MDARRAY=value; no indices supplied indicate that the entire array (all cells) is to
be populated with value.
COMP MDARRAY1=MDARRAY2; no indices for both arraynames, and the right side
value is only a multi-dimension array that has the same dimensions and mode as the left
side multi-dimension array. Such a statement will cause all the elements from
MDARRAY2 to be copied to MDARRAY1. If the element sizes of the arrays are different,
the elements will be converted during the copy.
COMP MDARRAY[#n][#n]... = expression will cause an automatic internal loop for the
indexes that have #n specified. The loop will begin at 1 and continue until to the number
of cells declared for that index is reached. However, if the same #n is specified for more
than one index, the smallest dimension will be used as the upper limit. The n in #n may
be 1 - the number of indexes for the array. (array[#3][2][#3] would be valid for a 3
dimensioned array.) If the expression does not contain any reference to any of the #n's
in the result array, the statement is executed in a very efficient manner – it can be literally
thousands of times faster than through the use of LOOP/ENDLOOP controls for the
statement. The #n can be #1 up to #9, these variables are actually place holders, so the
first subscript could actually be [#9]. Any #n subscript for the result can be used as a
subscript or as a variable in the expression. But, a #n in the expression that does not
appear as a subscript in the result will cause a fatal error.
By default, any #n index in the result will cause an internal loop from 1 to the upper limit
of that index. However, the user can cause a filter to be invoked within the loop. This is
done by using #n keywords with ranges following the expression. Eg; ARRAY
array1=15,50; COMP array1[#1][#2] = expression, #1=1,3,8-10, #2=20-max.... In this
COMP statement (without the added sub keywords), #1 would normally loop from 1 to 15
and #2 would loop from 1-50. But, with the added keywords, #1 would loop from 1-10,
and would be applied only for values of 1, 3, and 8-10, and #2 would loop from 20 to 50.
The values for #n sub-keys can be integers, simple variable names, or the word MAX,
which may be used to specify the upper limit for that dimension. If a pair of values is
specified, a test will be done to see if the loop values for #n fall between the limits of the
pair – the first value need not be the lower value, but it is recommended to code any pair
as low-high. Filter values outside of the valid range for the dimension will not cause an
error, they will simply be ignored.
Although all the above computations could be completed with standard scripts using
loops, the short-cut methods shown above can reduce user coded script, and can
drastically improve execution times.
Matrix Program > Control statements > ARRAY > Example

Exam ple
ARRAY sum_mat=10, cbd2ext=500
IF (M <= 10) sum_mat[M] = sum_mat[M] + rowsum(M)
IF (I=1-10,51-58,63,96) cbd2ext[I] = cbd2ext[i] + MW[1] include=501-535
ARRAY row_total=zones
; example of defining a string array
ARRAY TYPE=C5 StrArray=1000; defines a string array with size of 1000 and a
character width of 5.
ARRAY array1=zones,50; Array1 is a double precision (8 byte) array dimensioned
[zones][50]
COMP array1[#1][#2] = expression, #1=1,3,8-10, #2=20-max....
Matrix Program > Control statements > BREAK

BREAK
Programs : Distribution, Fratar, Generation, Matrix
Use BREAK to break out of a loop. When encountered, control immediately passes to the
stack statement after the associated end of loop. If BREAK is within a LOOP or JLOOP
block, control passes to the statement following the associated ENDLOOP (loop variable
remains intact) or ENDJLOOP (J will be reset to 1). Otherwise, stack processing for the I
zone is terminated but output and zonal reporting statistics will not be bypassed.
Matrix Program > Control statements > BREAK > Example

Exam ple
LOOP L1=1,3
IF (condition)
statements
ELSE
BREAK ; jump to IF statement
ENDIF
ENDLOOP
IF (condition) BREAK ; no more processing for this origin zone
LOOP L2=K1,K2,KINC
JLOOP EXCLUDE=25-50,88
IF (condition) BREAK ; jump to LOOP L3=
ENDJLOOP
LOOP L3=L2,L2+5
IF (condition) BREAK; ; jump to ABC=
ENDLOOP
ABC=...
ENDLOOP
Matrix Program > Control statements > BSEARCH

BSEARCH
Program: Matrix
Performs a binary search to find a key or set of keys in a sorted array or series of sorted
arrays. The format is:
BSEARCH ARRAY=value, ARRAY=value, ...

ARRAY |N| is the name of a user array that is in ascending sort. The routine will do a
binary search to expedite the search for the key. If there are multiple arrays specified,
the search will begin at the first array and then proceed through the remaining arrays for
matching keys (at the same record level as the first array). All arrays must be in
ascending sort.
If the array is a string (C) array, any constant value must be placed within quotes. If the
value is an expression, the result of the expression must be a string.
BSEARCH stores results in the variable _BSEARCH. Possible values in _BSEARCH are:
• +n — Indicates an exact match was found at the nth location in the array

• -n — Indicates that no match was found, but the nth location is where one would insert the
key (that is, the nth location is higher than the key, and the n-1 location is lower than the
key).

• 0 — Indicates that the key is greater than the value in the highest location in the array.
Matrix Program > Control statements > BSEARCH > Example

Exam ple
ARRAY MYARRAY=100, YOURARRAY=100
some code to populate the arrays

SORT ARRAY=MYARRAY,YOURARRAY
BSEARCH MYARRAY=32, YOURARRAY=(MYARRAY[j]*3)
Matrix Program > Control statements > BSEARCH > Example

Exam ple
FILEI DBI[1]=MYDBF, AUTOARRAY=FIELD1 SORT=FIELD1
ARRAY MYARRAY=100, YOURARRAY=100

BSEARCH DBA.1.FIELD1='875'
Matrix Program > Control statements > CALL

CALL
Programs : Distribution, Fratar, Generation, Matrix
Executes an external routine. Keywords include:
• D LL

Use CALL to execute an external process. To use this statement, there must be an
external file that is a dynamic link library (DLL), which contains the entry point that is
desired to be used at this location. The DLL file may have multiple entry points, and they
can all be accessed by this run of the Matrix program.

Ke y wo rd D e s c rip tio n

DLL |S| Single string that contains the DLL file

name, without extension, followed by the
name of the routine entry point enclosed
within parentheses. The “DLL” extension
is appended by the program. In some
operating systems, the file name may be
case sensitive. The routine name is
usually case sensitive; this depends
upon the compiler/linker system used to
develop the DLL.
NOTE: The compiler/linker system that
was used to develop the DLL might
have added some characters to the
entry name: Borland C/C++ compilers
prefix the entry name with an underscore.

The routine is called with one argument: the address of a structure that contains: I, J,
Zones, Iteration, address of MW, address of a routine to obtain address of any variables,
and address of a routine to print messages. The calling process adheres to standard
“C” notation. The C structure is illustrated in the sample code section below. I, J, Zones,
and Iteration are passed as integers. The addresses of these variables could be found
by using the pfFindVar routine, but because these variables must be protected,
pfFindVar will return NULL if the routine tries to obtain their addresses.
MW is the address of an array of pointers to the individual MW arrays. MW[1] is the
address of the first cell for MW[1]. Note that this is the cell for column 0, NOT column 1.
MW[1][1] would be the correct notation to address the cell for zone 1 in MW[1]. MWs
are allocated individually, rather than as a single block. In Fortran (without pointers), the
access to MW[1][1] would NOT be the typical MW(1,1). Instead, the address of each
MW would have to be obtained individually, and passed through an interface to a
separate routine for actual use of the MW. The routine would probably declare the array
as: DOUBLE PRECISION MW1(0:*).
The MW array can be accessed in several ways:
• — the suggested way if MWs need not be
S a v ing the MW v a lue fro m the p a s s e d s truc ture
allocated, and there are many references to MWs.

• S a v ing the a d d re s s re turne d fro m p fV a rFind (”MW ”...) — the required way if MWs need to be
allocated.

• — an efficient way if MWs need not be

Ind ire c t re fe re nc ing to MW fro m the p a s s e d s truc ture
allocated, and there are not many references to MWs. Indirect referencing is not quite as
efficient as direct addressing, but there is minimal difference.

The pfFindVar routine is used to obtain the pointer to any variables that are to be made
available to the external process. All variables (with a few isolated exceptions) are
stored as double precision values. Calls to pfFindVar need to be made only during the
first entry into the procedure; the returned addresses can be stored in static cells so that
pfFfindVar need not be called on every entry. The Matrix program allocates MW arrays
only when it is necessary, so the routine has to make sure that any MWs that it wishes
to use are allocated. This can be done by calling pFfindVar for MW, and appending the
integer numbers of the MWs that the procedure will use. If this is not done, and the
routine accesses an MW that has not been allocated, the routine will access a dummy
array. If the user is sure that all the desired MWs have been previously allocated by the
Matrix program, pfFindVar need not be used at all.
The pfPrnLine function is called, with two arguments, to print a message:
• nCtl — The control word for print the message. It has the format SFEN where,
m
F is a 1 if the message is to be written to the error file
m
E is the level of the message (0,1,2=Message, Warning, Fatal),
m
N is the number of new lines to print before printing the message.

• — The message string (ASCIIZ) to be printed; it may contain any normal printer
sMmessage
characters, including \n, \r,\f,\t etc.
Matrix Program > Control statements > CALL > Example

Exam ple
CALL DLL=user(_User1) ; call the following code in user.dll
// Sample of user function code in C
/*TITLE: User1 -- user function*/
#include <stdio.h>
typedef struct { int I, J, Zones, Iteration;
double** MW;
void* (*pfFindVar)(char*,...);
void* (*pfPrnLine)(int, char*);
} CallStack;
int _export User1 (CallStack* Stack)
{
char message[100];
static double** MW=NULL; /* store the address of MW array */
int m,j;
/*
* At first entry (when MW==NULL),
* establish MW and insure that MW[1-5] have been allocated
*/
if (MW == NULL) {
MW = (*Stack->pfFindVar)("MW",1,2,3,4,5);
/* Example of forming a message */
sprintf(message,"User1 Call I=%i, J=%i, Zones=%i",
Stack->I, Stack->J, Stack->Zones);
/* Example of printing a message */
(*Stack->pfPrnLine)(1,message);
}
/* Sample to fill in MW[1-5] */
for (m=1; m<=5; m++)
for (j=1; j<=Stack->Zones; j++)
MW[m][j] = Stack->I*100 + m*10 + j;
/* Stack->MW[m][j] is a similar way to reference MW[m][j] */
return 0;
}
Matrix Program > Control statements > CHOICE

CHOICE
Program: Matrix
Implements a logit-choice model.

NOTE: XCHOICE is the preferred command statement for implementing logit-choice

models.

Use the CHOICE command to implement logit-choice models, which can be based either
on generalized costs or utilities. The actual keywords supported depend on whether you
use cost-based or utility-based models:
• CHOICE keywords: Cost-based models

• CHOICE keywords: Utility-based models

Matrix Program > Control statements > CHOICE > CHOICE keywords: Cost-based models

CHOICE keyw ords: Cost-based models

Keywords and sub-keywords applicable to CHOICE cost-based models include:
• A LT E R N A T IV E S

• B A S E COS T S

• B A S E D E MA N D

• COS T S

• D COS T S

• D E MA N D

• D E S T S P LIT
m
COEFF
m INCLUDE
m EXCLUDE
m SPLITINTO

• OCOMP COS T

• OD E MA N D

• S P LIT
m COEFF
m SPLITINTO

• S T A R T MW

CH OICE k e y wo rd s : Co s t-b a s e d mo d e ls

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ALTERNATIVES |S99| Lists the set of discrete choices in the

forecast scenario. If the model is
confined to destination choice, then the
alternatives list comprises just one item
(representing the demand matrix). The
names used in the alternatives list are
subsequently used in SPLIT or
DESTSPLIT commands which define
the structure of the logit choice model,
and also determine the order that input
or output data are specified.

BASECOSTS |S99| Supplies the names of the base-cost

variables. For lists of two or more
variables, the order must match the list
of choices given in the ALTERNATIVES
clause.
This clause is only used in incremental
models which specify base and
forecast costs (as opposed to cost
differences). The corresponding
forecast costs are specified using the
 COSTS clause.

BASEDEMAND |S99| Supplies the names of the base-

demand variables for incremental
models only. For lists of two or more
variables, the order must match that in
the ALTERNATIVES clause.

COSTS |S99| Specifies forecast costs. If there is more

than one cost specified, their order must
be the same as that used in the
ALTERNATIVES clause.
See also BASECOSTS and DCOSTS
(cost-differences) for incremental
models; the COSTS clause is not used
in conjunction with the latter.

DCOSTS |S99| For incremental models only, the

change in cost for each choice can be
given instead of the base and forecast
costs. These cost-differences may be
specified as matrices, or numeric
values such as 0.0.

DEMAND |S| Specifies total demand for an absolute

model. Demand is typically a matrix,
although numeric values may be
specified. For example, a demand of
100.0 will give output demand
corresponding to the percentages
which choose each alternative.

DESTSPLIT |S99| The DESTSPLIT clause is used when

COEFF |S| the nest in the hierarchy corresponds to
INCLUDE a destination choice model. It divides
|IPa|
the travel demand between destination
EXCLUDE |IPa| zones, rather than alternatives. The
SPLITINTO |S99| output list must comprise just one item,
representing either a distinct choice
from the ALTERNATIVES clause or an
output which links to a subnest.
Like the SPLIT command, it may be
specified in one clause or divided into
constituent parts by use of the COEFF
and SPLITINTO clauses. Examples
are:
DESTSPLIT = TOTAL, 0.3,
allTrips,
and
DESTSPLIT = TOTAL, COEFF =
0.3, SPLITINTO = allTrips,
By default the destination choice model
works over all zones. By using the
INCLUDE or EXCLUDE clauses the
choice process may be restricted to a
subset of all zones. The following
example shows destination choice over
zones 1 to 57:
DESTSPLIT = TOTAL, 0.3,
allTrips, INCLUDE = 1-57,
This shows destination choice over
zones except for 88 to 100, which are
 specified by the EXCLUDE subkeyword:
DESTSPLIT = TOTAL, COEFF =
0.3, SPLITINTO = allTrips,
EXCLUDE = 88-100,
Note that certain restrictions apply to
the use of destination choice models.
The composite costs may not be
saved, and this form of logit model may
not be used inside a JLOOP construct.

OCOMPCOST |I| Optional. Outputs the composite cost of

all choices for an absolute model. The
list contains a numeric value, which
specifies the working matrix (MW) that
stores the result. Where the choice
model has a hierarchic structure, the
composite cost for the highest level
nest may be saved. This clause is not
supported for destination-choice
models, as the composite costs are
zonal values rather than matrices.

ODEMAND |I| Specifies the working matrices (MWs)

used to store the forecast demand; the
list comprises a list of working matrix
numbers. If there is more than one cost
variable, then the list must be in the
same order as used in the
ALTERNATIVES clause.
This command is optional, and may be
omitted if only the composite costs are
required.

SPLIT |S99| The structure of the logit choice model

COEFF |S| is specified by the SPLIT and
SPLITINTO DESTSPLIT clauses. One of these
|S99|
clauses is required for each nest (or
subnest) in the model hierarchy. For a
hierarchic model, these are typically
specified starting at the top-level and
working down the structure.
Each SPLIT clause specifies an input, a
scale parameter (or coefficient of cost),
and one or more outputs. The
coefficient and outputs may both be
specified in the SPLIT clause or
specified using the COEFF and
SPLITINTO subkeyword clauses.
The input (or first item listed in a SPLIT
clause) may either be TOTAL
(representing the total demand at the
top level of the choice hierarchy) or for
subnests it is the name of an output from
the appropriate higher level nest.
The coefficient is specified as the
second item in the SPLIT clause, or
using the COEFF subclause. It may be
specified as a numeric value, a
variable, or even a matrix with differing
values between origin-destination
pairs. The latter is appropriate when the
demand matrix comprises distinct
segments (such as travel within study
 area, trips from cordon into study area,
and through traffic) and these segments
respond differently to cost differences.
The remainder of the SPLIT clause, or
the SPLITINTO clause define the output
list. The items represent either distinct
choices (from the ALTERNATIVES
clause), or links to subnests which are
given unique meaningful names and
used as inputs to lower splits.
The following examples shows a
subnest taking AllPT as an input and
using a scale parameter of 0.3 to divide
between bus and rail alternatives.
Specified as a SPLIT clause it takes the
form:
SPLIT = AllPT, 0.3, Bus,
Rail,
and using subkeywords it is:
SPLIT = AllPT, COEFF = 0.3,
SPLITINTO = Bus, Rail,

STARTMW |I| The calculations performed by the logit

choice model require a number of
working matrices (or MWs) to be
allocated for the use of the CHOICE
command. The STARTMW clause
specifies a numeric value
corresponding to a particular working
matrix which is higher than that of any
other working matrix referenced in the
script. Working matrices from the
STARTMW value upwards are used by
the CHOICE command, and should not
be used elsewhere in the script. Where
a Matrix script contains several CHOICE
commands, the same STARTMW value
may be used in all instances.
Matrix Program > Control statements > CHOICE > CHOICE keywords: Utility-based models

CHOICE keyw ords: Utility-based models

Keywords and sub-keywords applicable to CHOICE utility-based models include:
• A LT E R N A T IV E S

• B A S E D E MA N D

• B A S E U T ILS

• D E MA N D

• D E S T S P LIT
m INCLUDE
m EXCLUDE

• D U T ILS

• OCOMP U T IL

• OD E MA N D

• S P LIT

• S T A R T MW

• U T ILIT IE S

CH OICE k e y wo rd s : U tility -b a s e d mo d e ls

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ALTERNATIVES |S99| Lists the set of discrete choices in the

forecast scenario. If the model is
confined to destination choice, then the
alternatives list comprises just one item
(representing the demand matrix). The
names used in the alternatives list are
subsequently used in SPLIT or
DESTSPLIT commands which define
the structure of the logit-choice model,
and also determine the order that input
or output data are specified.

BASEDEMAND |S99| Supplies the names of the base-

demand variables. For incremental
models only. For lists of two or more
variables, the order must match that in
the ALTERNATIVES clause.

BASEUTILS |S99| Supplies the names of the base utilities

for the various alternatives. For lists of
two or more variables, the order must
match that given in the ALTERNATIVES
clause.
This clause is only used in incremental
models which specify base and
forecast utilities (as opposed to utility
differences). The corresponding
forecast costs are specified using the
 UTILITIES clause.

DEMAND |S| Specifies the total demand for an

absolute model. Demand is typically a
matrix, although numeric values may be
specified. For example, a demand of
100.0 will give output demand
corresponding to the percentages
which choose each alternative.

DESTSPLIT |S99| Use the DESTSPLIT clause when the

INCLUDE |IPa| nest in the hierarchy corresponds to a
EXCLUDE destination-choice model. It divides the
|IPa|
travel demand between destination
zones, rather than alternatives. The
output list must comprise just one item,
representing either a distinct choice
from the ALTERNATIVES clause or an
output which links to a subnest. This
output item may be preceded by a
scale parameter.
The following example applies a
scaling factor to the ModeSplit logsum
utility, and performs a destination
choice dividing the total trips across all
destinations:
DESTSPLIT = TOTAL 0.9
ModeSplit,
By default the destination-choice model
works over all zones. By using the
INCLUDE or EXCLUDE subkeyword
clauses the choice process may be
restricted to a sub-set of all zones. The
following example restricts destination
choice to zones 1 to 23:
SPLIT = TOTAL, allTrips,
INCLUDE = 1-23,
NOTE: Certain restrictions apply to the
use of destination-choice models. The
composite utilities cannot be saved,
and this form of logit model may not be
used inside a JLOOP.

DUTILS |S99| Gives the change in utility for each

choice rather than the base and
forecast utilities. For incremental
models only. These utility-differences
may be specified as matrices, or
numeric values such as 0.0.

OCOMPUTIL |I| Optional. Outputs the composite utility

(or logsum value) of all choices for an
absolute model. The list contains a
numeric value which specifies which
working matrix (MW) is used to store the
result. Where the choice model has a
hierarchic structure, the composite utility
for the highest level nest may be saved.
This clause is not supported for
destination-choice models, as the
composite costs are zonal values
rather than matrices.

ODEMAND |I| Optional. Specifies the working

 matrices (MWs) used to store the
forecast demand; the list comprises a
list of working matrix numbers. If there is
more than one cost variable, then the
list must be in the same order as used
in the ALTERNATIVES clause.
This command may be omitted if only
the composite costs are required.

SPLIT |S99| The structure of the logit choice model

is specified by the SPLIT and
DESTSPLIT clauses. One of these
clauses is required for each nest (or
subnest) in the model hierarchy. For a
hierarchic model, these are typically
specified starting at the top-level and
working down the structure.
Each SPLIT clause specifies an input,
and one or more outputs which may
have their own scale parameters. (A
choice with only one output may be
specified to apply a scaling factor to a
sub-nest logsum utility, and so achieve
consistent scaling at all equivalent
levels in a complex hierarchic
structure.)
The input (or first item listed in a SPLIT
clause) may either be TOTAL
(representing the total demand at the
top level of the choice hierarchy) or for
subnests it is the name of an output from
the appropriate higher level nest.
The remainder of the SPLIT clause
define the output list, and any scale
parameters which apply to subnests.
The main items in the output list
represent either distinct choices (from
the ALTERNATIVES clause), or links to
sub-nests which are given unique
meaningful names and used as inputs
to lower splits. An example is:
SPLIT = AllPT Bus Rail,
Subnests in the output list may be
preceded by a scale parameter, which
is applied to the composite (or logsum)
utility of the subnest before evaluating
this choice nest. The scale parameter
should be greater than 0, and must not
exceed 1.0. The scale parameter may
be omitted where its value is 1.0, as this
is the assumed default. Examples are:
SPLIT = TOTAL Car 0.5 PT 0.4
WalkCycle,
where scale parameters are applied to
the PT and walk/cycle subnests. Car
either is a distinct alternative, or a
subnest with a default scale parameter
of 1.0.
Where the same scale parameter
applies to several subnests, the scale
parameter may be specified once
followed by the list of relevant subnests
 grouped together by use of brackets.
An example is:
SPLIT = TOTAL, 0.4 Car 0.5
(Bus Rail),
where the bus and rail subnests share
the same scale parameter, and a
different value applies to the car
subnest.

STARTMW |I| The calculations performed by the logit

choice model require a number of
working matrices (or MWs) to be
allocated for the use of the CHOICE
command. The STARTMW clause
specifies a numeric value
corresponding to a particular working
matrix which is higher than that of any
other working matrix referenced in the
script. Working matrices from the
STARTMW value upwards are used by
the CHOICE command, and should not
be used elsewhere in the script. Where
a Matrix script contains several CHOICE
commands, the same STARTMW value
may be used in all instances.

UTILITIES |S99| Specifies forecast utilities. If there is

more than one utility, their order must be
the same as that used in the
ALTERNATIVES clause.
See also BASEUTILS and DUTILS
(utility-differences) for incremental
models; the UTILITIES clause is not
used in conjunction with DUTILS.
Matrix Program > Control statements > XCHOICE

XCHOICE
Program: Matrix
XCHOICE implements a logit choice model. XCHOICE replaces the CHOICE command
statement, resulting in improved run times. Though you can continue to use CHOICE,
Citilabs recommends using the XCHOICE command statement for logit choice models.
Usage is similar with XCHOICE, but there are some differences in keyword usage and in
value formats for keywords. See “Summary of syntax usage differences between
XCHOICE and CHOICE” on page 574.
Use the XCHOICE command to implement logit choice models, based on either
generalized costs or utilities. The actual keywords supported depend on whether you
use cost-based or utility-based models:
• XCHOICE keywords: Cost-based models

• XCHOICE keywords: Utility-based models

Matrix Program > Control statements > XCHOICE > XCHOICE keywords: Cost-based models

X CHOICE keyw ords: Cost-based models

Keywords and sub-keywords applicable to XCHOICE cost-based models include:
• A LT E R N A T IV E S

• B A S E COS T S MW

• B A S E D E MA N D MW

• COS T S MW

• D COS T S MW

• D E MA N D

• D E MA N D MW

• D E S T S P LIT
m COEFF
m INCLUDE
m EXCLUDE
m SPLITINTO

• OD E MA N D MW

• S P LIT
m COEFF
m SPLITINTO
m SPLITCOMP

• S T A R T MW

XCH OICE k e y wo rd s : Co s t-b a s e d mo d e ls

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ALTERNATIVES |S99| Lists the set of discrete choices in the

forecast scenario. If the model is
confined to destination choice, then
the alternatives list comprises just one
item (representing the demand
matrix). The names used in the
alternatives list are subsequently
used in SPLIT or DESTSPLIT
keywords which define the structure of
the logit choice model, and also
determine the order that input or output
data are specified.

BASECOSTSMW |S99| Supplies the names of the base cost

matrices. For lists of two or more
matrices, the order must match the list
of choices given in the
ALTERNATIVES keyword.
This keyword is only used in
incremental models which specify
 base and forecast costs (as opposed
to cost differences). The
corresponding forecast costs are
specified using the COSTSMW
keyword.

BASEDEMANDMW |S99| Supplies the names of the base

demand matrices. For incremental
models only. For lists of two or more
matrices, the order must match that in
the ALTERNATIVES keyword.

COSTSMW |S99| Specifies forecast costs matrices. If

there is more than one cost specified,
their order must be the same as that
used in the ALTERNATIVES keyword.
See also BASECOSTSMW and
DCOSTSMW (cost-differences) for
incremental models; the COSTSMW
keyword is not used in conjunction
with DCOSTSMW.

DCOSTSMW |S99| Gives the change in cost for each

choice rather than the base and
forecast costs. For incremental
models only. These cost-differences
may be specified as matrices, or
numeric values such as 0.0.

DEMAND |S99| The demand value for a destination-

choice or mode- and destination-
choice model.

DEMANDMW |S99| The demand matrix for a pure mode-

choice model.

DESTSPLIT |S99| Use the DESTSPLIT keyword when

COEFF |R| the nest in the hierarchy corresponds
INCLUDE to a destination-choice model. It
|IPa|
divides the travel demand between
EXCLUDE |IPa| destination zones, rather than
SPLITINTO |S99| alternatives. The output list must
comprise just one item, representing
either a distinct choice from the
ALTERNATIVES keyword or an output
which links to a subnest.
Like the SPLIT command, it may be
specified in one keyword or divided
into constituent parts by use of the
COEFF and SPLITINTO subkeywords.
Examples are:
DESTSPLIT = TOTAL, 0.3,
allTrips,
and
DESTSPLIT = TOTAL, COEFF =
0.3, SPLITINTO = allTrips,
By default the destination choice
model works over all zones. By using
the INCLUDE or EXCLUDE
subkeywords the choice process may
be restricted to a subset of all zones.
The following example shows
destination choice over zones 1 to 57:
 DESTSPLIT = TOTAL, 0.3,
allTrips, INCLUDE = 1-57,
and this shows destination choice
over zones except for 88 to 100, which
are specified by the EXCLUDE
subkeyword:
DESTSPLIT = TOTAL, COEFF =
0.3, SPLITINTO = allTrips,
EXCLUDE = 88-100,
NOTE: Certain restrictions apply to the
use of destination-choice models.
The composite costs may not be
saved, and this form of logit model
may not be used inside a JLOOP
construct.

ODEMANDMW |S99| Specifies which working matrices

(MWs) store the forecast demand; the
list comprises a list of working matrix
numbers. If there is more than one
cost matrix, then the list must be in the
same order as used in the
ALTERNATIVES keyword.

SPLIT |S99| The structure of the logit choice model

COEFF |R| is specified by the SPLIT and
SPLITINTO DESTSPLIT keywords. One of these
|S99|
keywords is required for each nest (or
SPLITCOMP |S99| subnest) in the model hierarchy. For a
hierarchic model, these are typically
specified starting at the top level and
working down the structure.
Each SPLIT keyword specifies an
input, a scale parameter (or coefficient
of cost), and one or more outputs. The
coefficient and outputs may both be
specified in the SPLIT keyword or
specified using the COEFF and
SPLITINTO subkeyword clauses.
The input (or first item listed in a SPLIT
keyword) may either be TOTAL
(representing the total demand at the
top level of the choice hierarchy) or for
subnests it is the name of an output
from the appropriate higher level nest.
The coefficient is specified as the
second item in the SPLIT keyword, or
using the COEFF subkeyword. It may
be specified as a numeric value, a
variable, or even a matrix with differing
values between origin-destination
pairs. The latter is appropriate when
the demand matrix comprises distinct
segments (such as travel within study
area, trips from cordon into study
area, and through traffic) and these
segments respond differently to cost
differences.
The remainder of the SPLIT keyword,
or the SPLITINTO subkeyword define
the output list. The items represent
either distinct choices (from the
 ALTERNATIVES keyword), or links to
sub-nests which are given unique
meaningful names and used as inputs
to lower splits.
The following examples shows a
subnest taking AllPT as an input and
using a scale parameter of 0.3 to
divide between bus and rail
alternatives. Specified as a SPLIT
keyword it takes the form:
SPLIT = AllPT, 0.3, Bus,
Rail,
and using subkeywords it is:
SPLIT = AllPT, COEFF = 0.3,
SPLITINTO = Bus, Rail,
(continued)

SPLIT The SPLITCOMP subkeyword

(continued) specifies the working matrix to store
the composite costs or composite
utilities for the nest defined by its
parent SPLIT keyword.
Example:
XCHOICE ALTERNATIVES =
A,b,c,
baseCOSTSmw = 2,3,4,
COSTSmw = 2,3,5,
basedemandmw=1,1,1,
ODEMANDmw=6,7,8,
SPLIT= Total 0.1 desta,
destpt,
SPLITCOMP=20,
destSPLIT= desta 0.15 a,
destSPLIT= destpt 0.15 pt,
SPLIT= pt 0.2 B C,
SPLITCOMP=21,
startmw=30
MW 20 is composite cost of
alternative "Total"
MW 21 is composite cost of
alternative "pt"

STARTMW |I| The calculations performed by the

logit choice model require a number
of working matrices (or MWs) to be
allocated for the use of the XCHOICE
command. The STARTMW keyword
specifies a numeric value
corresponding to a particular working
matrix which is higher than that of any
other working matrix referenced in the
script. Working matrices from the
STARTMW value upwards are used
by the XCHOICE command, and
should not be used elsewhere in the
script. Where a Matrix script contains
several XCHOICE commands, the
same STARTMW value may be used
in all instances.
Matrix Program > Control statements > XCHOICE > XCHOICE keywords: Utility-based models

X CHOICE keyw ords: Utility-based models

Keywords and sub-keywords applicable to XCHOICE utility-based models include:

• A LT E R N A T IV E S

• B A S E D E MA N D MW

• B A S E U T ILS MW

• D E MA N D

• D E MA N D MW

• D E S T S P LIT
m INCLUDE
m EXCLUDE

• D U T ILS MW

• OD E MA N D MW

• S P LIT

• S T A R T MW

• U T ILIT IE S MW

XCH OICE k e y wo rd s : U tility -b a s e d mo d e ls

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ALTERNATIVES |S99| Lists the set of discrete choices in the

forecast scenario. If the model is
confined to destination choice, then
the alternatives list comprises just one
item (representing the demand
matrix). The names used in the
alternatives list are subsequently
used in SPLIT or DESTSPLIT
commands which define the structure
of the logit choice model, and also
determine the order that input or output
data are specified.

BASEDEMANDMW |S99| Supplies the names of the base

demand matrices. For incremental
models only. For lists of two or more
matrices, the order must match that in
the ALTERNATIVES keyword.

BASEUTILSMW |S99| Supplies the names of the base utility

matrices for the various alternatives.
For lists of two or more matrices, the
order must match that given in the
ALTERNATIVES keyword.
This keyword is only used in
incremental models which specify
base and forecast utilities (as
 opposed to utility differences). The
corresponding forecast costs are
specified using the UTILITIESMW
keyword.

DEMAND |S99| The demand value for a destination-

choice or mode- and destination-
choice model.

DEMANDMW |S99| The demand matrix for a pure mode-

choice model.

DESTSPLIT |S99| Use when the nest in the hierarchy

INCLUDE |IPa| corresponds to a destination-choice
model. It divides the travel demand
EXCLUDE |IPa|
between destination zones, rather
than alternatives. The output list must
comprise just one item, representing
either a distinct choice from the
ALTERNATIVES keyword or an output
which links to a subnest. This output
item may be preceded by a scale
parameter.
The following example applies a
scaling factor to the ModeSplit logsum
utility, and performs a destination
choice dividing the total trips across
all destinations:
DESTSPLIT = TOTAL 0.9
ModeSplit,
By default the destination choice
model works over all zones. By using
the INCLUDE or EXCLUDE
subkeywords the choice process may
be restricted to a subset of all zones.
The following example restricts
destination choice to zones 1 to 23:
SPLIT = TOTAL, allTrips,
INCLUDE = 1-23,
NOTE: Certain restrictions apply to the
use of destination choice models. The
composite utilities cannot be saved,
and this form of logit model may not
be used inside a JLOOP.

DUTILSMW |S99| Gives the change in utility for each

choice rather than the base and
forecast utilities. For incremental
models only. These utility-differences
may be specified as matrices, or
numeric values such as 0.0.

ODEMANDMW |S99| Specifies working matrices (MWs)

used to store the forecast demand;
the list comprises a list of working
matrix numbers. If there is more than
one cost matrix, then the list must be in
the same order as used in the
ALTERNATIVES keyword.
This command is optional, and may
be omitted if only the composite costs
are required.
SPLIT |S99| The structure of the logit choice model
is specified by the SPLIT and
DESTSPLIT keywords. One of these
keywords is required for each nest (or
subnest) in the model hierarchy. For a
hierarchic model, these are typically
specified starting at the top level and
working down the structure.
Each SPLIT keyword specifies an
input, and one or more outputs which
may have their own scale parameters.
(A choice with only one output may be
specified to apply a scaling factor to a
subnest logsum utility, and so achieve
consistent scaling at all equivalent
levels in a complex hierarchic
structure.)
The input (or first item listed in a SPLIT
keyword) may either be TOTAL
(representing the total demand at the
top level of the choice hierarchy) or for
subnests it is the name of an output
from the appropriate higher level nest.
The remainder of the SPLIT keyword
define the output list, and any scale
parameters which apply to subnests.
The main items in the output list
represent either distinct choices (from
the ALTERNATIVES keyword), or links
to subnests which are given unique
meaningful names and used as inputs
to lower splits. An example is:
SPLIT = AllPT Bus Rail,
Subnests in the output list may be
preceded by a scale parameter,
which is applied to the composite (or
logsum) utility of the subnest before
evaluating this choice nest. The scale
parameter should be greater than 0,
and must not exceed 1.0.
For utility-based models, if one
alternative has a scalar, all others
must also have scalars. For example:
split=total,0.5,auto,1.0,pt,
Scalars of 1.0 cannot be omitted in
XCHOICE.
(continued)

SPLIT (continued) Examples are:

SPLIT = TOTAL 1.0 Car 0.5 PT
0.4 WalkCycle,
where scale parameters are applied
to the PT and walk/cycle subnests.
Car either is a distinct alternative, or a
subnest with a scale parameter of 1.0.
Where the same scale parameter
applies to several sub-nests, the
scale parameter may be specified
once followed by the list of relevant
subnests grouped together by use of
brackets. An example is:
 SPLIT = TOTAL, 0.4 Car 0.5
(Bus Rail),
where the bus and rail subnests share
the same scale parameter, and a
different value applies to the car
subnest.

STARTMW |I| The calculations performed by the

logit choice model require a number
of working matrices (or MWs) to be
allocated for the use of the XCHOICE
command. The STARTMW keyword
specifies a numeric value
corresponding to a particular working
matrix which is higher than that of any
other working matrix referenced in the
script. Working matrices from the
STARTMW value upwards are used
by the XCHOICE command, and
should not be used elsewhere in the
script. Where a Matrix script contains
several XCHOICE commands, the
same STARTMW value may be used
in all instances.

UTILITIESMW |S99| Specifies forecast utilities. If there is

more than one utility, their order must
be the same as that used in the
ALTERNATIVES keyword.
See also BASEUTILSMW and
DUTILSMW (utility-differences) for
incremental models; the
UTILITIESMW keyword is not used in
conjunction with DUTILSMW.
Matrix Program > Control statements > XCHOICE > Summary of syntax usage differences between XCHOICE and
CHOICE

Summary of syntax usage differences betw een X CHOICE

and CHOICE
In each XCHOICE, there must be one and only one case-insensitive “Total” in a SPLIT
clause. “Total” is the starting node for mode split.
All matrix valued keywords must end with MW. For example:
• UTILITIES is now UTILITIESMW

• COSTS is now COSTSMW

DEMANDMW is only available to pure mode choice models where input demand is a
matrix. In destination-choice or mixed mode- and destination-choice models, use
DEMAND instead. DEMAND in XCHOICE can be any of these values:

• Constant

• Variable

• Array without index

• Array with constant index

• Array with variable index

For example:
....
array tripsfromi=5
if(i==1)
tripsfromi[1]=100
tripsfromi[2]=200
tripsfromi[3]=300
tripsfromi[4]=400
tripsfromi[5]=500
endif
myvar=100
myindex=3
...
DEMAND =100,
.OR.
DEMAND =myvar,
.OR.
DEMAND =tripsfromi,
.OR.
DEMAND =tripsfromi[1],
.OR.
DEMAND =tripsfromi[myindex],

For mixed mode- and destination-choice models, DESTSPLIT must start with alternatives
prefixed with “dest” (for example, destx), and end with corresponding alternative name,
for example “x.” Here is an example:
ALTERNATIVES=car b c,
SPLIT = TOTAL 0.01 destcar destpt,
DESTSPLIT = destcar 0.02 car,
DESTSPLIT = destpt 0.03 pt,

Both “x” or “destx” are acceptable in the higher level SPLIT clause. In previous example,
both of these two following cases work:
SPLIT = TOTAL 0.01 destcar destpt,

Or
SPLIT = TOTAL 0.01 car pt,

For utility-based model, if one alternative has a scalar, all others must also have scalars,
example:
split=total,0.5,auto,1.0,pt,

Scalar 1.0 can be omitted in CHOICE, but it cannot be omitted in XCHOICE.

OCOMPCOST and OCOMPUTIL in CHOICE are replaced by a new keyword SPLITCOMP in
XCHOICE. Unlike OCOMPCOST and OCOMPUTIL, which can be used only on the upper most
level of a nested mode choice structure, SPLITCOMP can be used on any level to get nest
specific composite costs or composite utilities.
Matrix Program > Control statements > COMP

COMP
Programs : Distribution, Fratar, Generation, Matrix
Computes a variable, matrix, or matrix element. Keywords and sub-keywords include:
• MW
m EXCLUDE
m INCLUDE

• VAR

Usage is:
VAR=expression
MW[]=expression (INCLUDE EXCLUDE)

The COMP statement is probably the most important of all the statements in the program.
It is used to compute variable and work matrix values.
COMP k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

MW |KN| Working matrix that you can use to store

values between origin zones and
destination zones (I zones and J zones).
Set the keyword equal to an expression
you want to solve and store in a working
matrix. You can specify working matrix
expressions per origin zone or per origin
zone and destination zone:
• MW[n] — For the current origin zone
(I), defines the expression solved for
all destination zones (all values of J).
The Matrix program’s internal I-loop
specifies I. The Matrix program
stores the values in working matrix n.
You may define up to MAXMW
working matrices. You may specify
the index n using a constant or a
variable name.
The program solves the expression for
all values of J (1 through ZONES),
filtering values indicated by any
INCLUDE or EXCLUDE lists on this
statement.
Within a JLOOP statement, the
program only solves the expression
one time only, with J being the value of
the loop’s current J.
• MW[n][d] — For the current origin
 zone (I), defines the expression to
solve at destination zone d. The
second index, d, must be between
one and ZONES. The Matrix program
stores the computed value in working
matrix n.

MW E XCLU D E |IP| Optional. Values of J excluded when

computing the MW[n] expression. As the
program internally loops on J, the program
compares J to the values in the EXCLUDE
list. If the current J is on the list, the program
does not evaluate or store the expression
for that J.
Specified values can range from 1 to the
highest zone number.
Filter applies to all MW[n] values on the
COMP statement.
Not permitted if COMP statement within
JLOOP ... ENDJLOOP block.
Always processed after INCLUDE
subkeyword.
By default no zones are excluded.

MW IN CLU D E |IP| Optional. Values of J included when

computing the MW[n] expression. As the
program internally loops on J, the program
compares J to the values in the INCLUDE
list. If the current J is not on the list, the
program does not evaluate or store the
expression for that J.
Specified values can range from 1 to the
highest zone number.
Filter applies to all MW[n] values on the
COMP statement.
Not permitted if COMP statement within
JLOOP ... ENDJLOOP block.
By default all zones are included.

VAR |KN| V A R is the name of a variable where the

result of expression is to be stored. The
name may be as long as desired (within
reason). The expression is solved one
time for each encounter, with J being either
one (not in JLOOP), or the value of the
JLOOP J. If expression results in a
character string, the variable must be a
character string variable. All variables are
assumed to be numeric variables, unless
their first appearance as a result in a
COMP statement is with an expression that
results in a character string. Examples:
abc = '123'
def = 123
abc = def ; invalid: abc has
been declared a string
abc = abc+'456' ; valid
abc = abc+def ; messy -- don’t
mix types
jkl = 1 ; jkl is declared
 numeric
jkl = xyz ; invalid: xyz is
declared a string (later)
xyz = 'xyz' ; xyz is declared a
string
The program does not always bother
computing expressions for variables that
are not used as input to some process. In
the above examples, the statements with
jkl= might never be executed, because
jkl is never used.

If a COMP statement includes any INCLUDE or EXCLUDE filters, the filters apply to all MW[]=
values, and special matrix functions on the statement, no matter where they appear on
the statement. EXCLUDE is processed after INCLUDE. INCLUDE and EXCLUDE may not be
specified within a JLOOP block.
Matrix Program > Control statements > COMP > Supported expressions

Suppo rted expressio ns

Special Matrix variables:

MW[] MI.n.name MI.n.matnum MI.n.name.T MI.n.matnum.T
The expression is a standard Cube Voyager numeric expression, but there are also
certain special variables names that may be used within it.

V a ria b le D e s c rip tio n

MW[Rexpression] Value from any work matrix; the column

index (not explicitly expressed) will be
supplied as J. Rexpression may contain
nested MW[]; be careful! MW[Rexpression]
[Cexpression] is the value from any work
matrix for zone Cexpression.

MI.n.name Value from the MATI[n].name matrix; the

column index (not explicitly expressed) will
be supplied as J. The row index [n], must be
a constant. MI.n.name[Cexpression] is a
variation; the column index is computed.
Valid matrix names contain only
alphanumeric characters, spaces, and
underscores (_). If matrix names have
spaces, then you must include the entire MI
matrix reference in double quotes to
recognize the name. For example:
MW[1]="MI.1HBW TRIPS"

MI.n.matnum Value from the MI[n].matnum matrix; the

column index (not explicitly expressed) will
be supplied as J. The row index [n] and the
matnum must be constants.
MI.n.matnum[Cexpression] is a variation; the
column index is computed.

MI.n.name.T Special cases for the above two MI formats.

MI.n.matnum.T The appended “.T” indicates to use the
transposed values for the matrix. This
triggers a preprocessor program that will
transpose the matrix. Thus, the retrieved cell
represents the J-I value, instead of the I-J
value. If a column index is used, the
retrieved cell will represent the value of the
cell for the index to I.

ZI.n.name Value from the ZDATI[n].name matrix; the

zone index (not explicitly expressed) will be
supplied as I.
ZI.n.name[Cexpression] is a variation; the
zone index is computed.

The expression may contain the following special matrix row processing functions:
ROWSUM() ROWCNT() ROWMIN() ROWMAX() ROWAVE() ROWFIX()
 ROWFAC() LOWEST() ROWADD() ROWMPY() ROWDIV() ROWREAD()
In addition to the standard numeric expression functions (abs, exp, int, ln, log, max, min,
round, sqrt—see “Expressions” on page 33 for more details), some special purpose
functions are available. The matrix oriented functions process all cells in a matrix
(subject to the restrictions of any INCLUDE and EXCLUDE lists), and should not be used
within JLOOP blocks and MW[]= expressions.
Most of these functions could be duplicated with a combination of MW[]= statements.
The function format has two advantages: coding is much easier, and processing is more
efficient. Combining functions on a single statement is permissible; they will be
processed in appropriate order. Example: DUMMY = ROWFAC(3,1.5) + ROWFIX(3) will factor
matrix 3 and then integerize it.
In the following matrix function descriptions, the first argument (mw) indicates the work
matrix to process, and must be specified. If “lo,hi” is allowed, and lo is supplied, and hi is
not, hi will be set to lo. Lo and hi are inclusive values. If an invalid argument is detected
by a function, the function will return a zero, without any diagnostics.
Ma trix func tio n d e s c rip tio ns

Func tio n 1 D e s c rip tio n

ARRAYSUM(array_name) Returns sum of an array (see “Examples and

FAQ” on page 654).

LOWCNT Stores actual number of cells used in

LOWEST. Warning: Dividing by LOWCNT, if it
is 0, will cause a program error message. In
some cases, you can use the max function to
prevent this. For example:
W[mw][I] = LOWEST(mw,4,.01,5,I)
/max(1,LOWCNT)/ 2

LOWEST (mw,#) Sum of lowest # cells

LOWEST(mw,#,lo,hi) Sum of lowest # cells where lo>=value<=hi

LOWEST(mw,#,lo,hi,z,z,...) Sum of lowest # cells but exclude specific

cells
LOWEST is quite useful for computing an
intrazonal value based upon the proximity to
the nearest zones. The range of arguments
accommodates most situations. Use lo and
hi to exclude possible dummy zones that
appear as zero in the row. Use z to exclude
specific zones; normally, the intrazonal cell (I)
would be excluded. This exclusion is in
addition to any on an EXCLUDE list.
NOTE: LOWEST treats zeros as regular
numbers. Since all MWs are initialized to
zeros, use caution when applying LOWEST
with no range specified.

MATVAL (F, M, I, J [, E]) Returns random access values from MATIs

(see “Examples and FAQ” on page 654).
F = MATI[#]
 M = Matrix #
I=I
J =J
E = the value to return if the request for the
cell is invalid.
Each of the arguments can be an expression,
variable, or constant. Because the arguments
are dynamically set, the program can not pre-
edit the values. For example:
K = matval(3,1,I,J,-1) indicates to get the value
from I to J from matrix 1 on MATI[3].
Since this is direct access, the function can
be slow in some cases and quite efficient in
others. The Matrix program maintains a
cache of the matrix rows to try to help speed
up the process. However, some types of
processing will not be helped much by the
use of the cache. In general the larger the
cache, the more efficient the access will be.
The cache size is specified by the
PARAMETERS MATVALCACHE.

ROWADD(d,s1...sn) Add matrix mw[1] + … mw[sn] into mw[d]

Same as:
MW[d] = MW[s1] + MW[s2] + MW[sn]

ROWAVE(mw) Average cell value for nonzero values

ROWAVE(mw,lo,hi) Average cell value for nonzero values,

including only cells where: lo>=value<=hi

ROWCNT(mw) Number of cells with nonzero values

ROWCNT(mw,lo,hi) Number of cells with nonzero values, but

include only cells where: lo>=value<=hi (this
can include 0).

ROWDIV(d,s) Divide MW[d] by MW[s] making all divided-

by-zero cells equal to 0.
Same as:
JLOOP
IF (MW[s] == 0)
MW[d] = 0
ELSE
MW[d] = MW[d] / MW[s]
ENDIF
ENDJLOOP

ROWFAC (mw,fac) Factors the row by fac.

Same as:
MW[mw] = MW[mw] * fac

ROWFIX(mw) Integerize mw (start at column intrazonal + 1,

with rounding factor = 0);

ROWFIX(mw,n) Integerize mw (start at column n, w/ rounding

factor = 0)

ROWFIX(mw,n,rnd) Integerize mw (start at column n, using

specified rounding factor, rnd)
ROWFIX integerizes the values in each cell of
the matrix (that is, drops all fractional portions
of the number). ROWFIX ensures the integer
 total is consistent with the original total. It
integerizes each cell after adding the
rounding factor and the accumulated
fractional portions from the previously treated
cells. With a rounding factor of 0, each cell is
truncated and its fractional remainder is
carried to the next cell. With a rounding factor
of 0.5, each cell is rounded to the nearest
integer and the difference (original – rounded)
is carried to the next cell.
If the process always begins at zone 1, the
lowest numbered zones never gets their fair
share of the fractions. To eliminate this bias,
the default condition starts at the cell after the
intrazonal cell and wraps around until the
intrazonal cell is the last cell processed. The
optional second argument specifies which
cell the process is to end with.

ROWMAX(mw) Maximum value in the row

ROWMIN(mw) Minimum value in the row

ROWMPY(d,s) Multiply MW[d] by MW[s]

Same as:
MW[d] = MW[d] * MW[s]

ROWREAD(MW#, MATI#, Reads a random row from the input matrix

I, M) and places it in the current row of the
referenced working matrix. Allows for
processing input matrix data not in I zone
ascending sort order.
Where:
MW# — Desired MW to which the record will
be saved
MATI# — Number of the input matrix file being
accessed (Mati[#])
I — Desired origin zone
M — Desired matrix number on the input file to
process
Example:
run pgm=matrix
FILEI MATI[1]=trips00.mat
; input matrix
; with random I zone order from
; external user program
FILEO
MATO[1]=Fixed_trips00.mat,mo=1‑20,
dec=20*8

; Matrix automatically runs an

ILOOP
; from I=1 to I=ZONES
loop m=1,20
; loop over the 20 matrices
; in the input file
x=ROWREAD(m,1,I,m)
; read row for the
; current value of I and places
it
; in the work matrix
endloop
endrun
 ROWSUM(mw) Row total

ROWSUM(mw,lo,hi) Row total, but include only cells where:

lo>=value<=hi

1 mw is a working matrix number (that is, MW[1])

lo is the lo end of a range
hi is the hi end of a range; defaults to lo if not specified
Matrix Program > Control statements > COMP > Example

Exam ple
MW[2]=J
MW[K]=MW[2] * MW[5] / SQRT(A*MW[3][MW[22]])
A=1, B=2, MW[A]=A+B INCLUDE=1-5,8,47-93
MW[3]=5*A, MW[4]=MW[3]*2, MW[K][I%10+1]=ODD,
INCLUDE=1-100,401-500, EXCLUDE=90,93,452; will apply to all MW[]s=
ABC=LOOKUP(DEF)*3
; move input matrices to work areas
MW[11]=MI.1.1, MW[12]=MI.1.2, MW[13]=MI.1.3
MW[21]=MI.2.1, MW[22]=MI.2.2, MW[23]=MI.1.3
JLOOP J=I
MW[6]=J ; store only at intrazonal column
ENDJLOOP
set var=sumaf1,rowsum1 ; clear variables
lookup name=f1, file=f1.txt
JLOOP
rowsum1 = rowsum1 + mw[1] ; get total for mw[1]
mw[2] = zi.1.attr[j] * f1(mi.12.1) ; A * F's
sumaf1 = sumaf1 + mw[2] ; sum A*F
endjloop
; Next line is same process done with functions:
rowsum1=ROWSUM(1) mw[2]=zi.1.attr[j]*f1(MI.12.1) sumaf1=ROWSUM(2)
Matrix Program > Control statements > CONTINUE

CONTINUE
Programs : Distribution, Fratar, Generation, Matrix
Jumps to end of loop.
Use CONTINUE to immediately jump to the end of a loop, bypassing all stack statements
between it and its associated end of loop. If it is within a LOOP or JLOOP block, control
passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise, stack
processing for the I zone is terminated but output and zonal reporting statistics will not be
bypassed.
Matrix Program > Control statements > CONTINUE > Example

Exam ple
LOOP L1=1,3
IF (!(condition)) CONTINUE
ENDLOOP
IF (condition) CONTINUE ; no more processing for this origin zone
LOOP L2=K1,K2,KINC
JLOOP EXCLUDE=25-50,88
IF (condition) CONTINUE ; jump to ENDJLOOP
.
ENDJLOOP
LOOP L3=L2,L2+5
IF (condition) CONTINUE ; jump to ENDLOOP for L3
.
ENDLOOP
ENDLOOP
Matrix Program > Control statements > EXIT

EXIT
Programs : Distribution, Fratar, Generation, Matrix
Exit the program before the end of zone processing
Upon encountering EXIT, the program immediately terminates stack processing, and
goes to the end of I-loop processing.
Matrix Program > Control statements > EXIT > Example

Exam ple
IF (expression) EXIT
Matrix Program > Control statements > FILEI

FILEI
NOTE: See “FILEI” on page 50 for general information about FILEI and for important
limitations when using Application Manager.

Programs : Distribution, Fratar, Generation, Matrix

Selects input data files. Keywords and sub-keywords include:

• DBI • ZD A T I
m AUTOARRAY m AVE
m AUTOMDARRAY m AVEX0
m DELIMITER m CNT
m FIELDS m DEFAULT
m JOINTODBI m FIRST
m JOINTOFIELDS m LAST
m MAXRECS m MAX
m NAME m MIN
m SORT m NAME

• LOOKU P I m SELECT

• MA T I m SUM
m AUTOMDARRAY m Z
m FIELDS
m PATTERN
m SKIPRECS

• R E CI
m DELIMITER
m FIELDS
m LISTERRS
m MAXERRS
m MAXRECS
m MAXSCAN
m NAME
m SORT

FILEI input data is normally entered in either matrix format or zonal vector format. Matrix
data is read dynamically (at the start of each I-loop), and must be in origin zone (I) order,
whereas zonal data is read prior to the initiation of the I-loop, and need not be in any
specified order. Data from these files is accessed via COMP statements, and are
identified as MI.n.name and ZI.n.name. The n designates subscript of the file, name
designates the matrix name or number. Cube Voyager matrices can have names and/or
numbers, other matrices have only numbers, and zonal data files have names only.
Example: MI.1.3 indicates matrix number 3 on the MATI[1] file. ZI.6.POP indicates the
POP variable from ZDATI[6] file. Valid matrix names contain only alphanumeric
characters, spaces, and underscores (_). If matrix names have spaces, then you must
include the entire MI matrix reference in double quotes to recognize the name. For
example:
MW[1]="MI.1HBW TRIPS"

On the FILEI statement the subscript is either explicitly, or implicitly, specified. MATI=...
defaults to MATI[1], and MATI[3]=name3,name4,name5 sets up MATI[3], MATI[4], and
MATI[5]. Since it is required that ZDATI files have variables explicitly defined for them,
the vector form of ZDATI (ZDATI=file1, file2...) will be treated as an error.
When an input file is used in an expression, it may have an additional subscript
appended to it to specify a zone number. For matrices, the subscript references the
column within a row, and for zonal data, it references the nth item in the vector. Zonal
data can be viewed as having zones rows with one column per zone, or as one row
having zones columns (user’s choice, it doesn’t matter). If there is no subscript specified,
the current value of J is used. J will always be in the range 1-zones. Example: MI.6.3[I]
accesses the intrazonal cell. ZI.1.TRMTIME[I] and ZI.1.TRMTIME[J] reference the origin
and destination terminal times, respectively.
Matrices can be input as either binary matrices or as data on ASCII or DBF type
records. In the latter case, PATTERN and FIELDS must be specified. ASCII type records are
more subject to variation (empty fields, invalid values, etc.), and the program is a bit
more tolerant with them. If a J or M is out of range, the values for the field are ignored.
On the other hand, if the field contains non-numeric data, it is treated as an error, and
further processing of the record is terminated.
The FILEI file keywords ZDATI, RECI, and DBI can point to elements in a multidatabase
(MDB) file by designating the filename followed by a backslash and the element name.
The program will generate a temporary file of records, each record containing all the
variables in the element. If the FILEI file keyword value is followed by variable definitions,
those definitions are ignored, or in some cases, cause a fatal termination. On a ZDATI file
name, you can specify a definition for Z to indicate which MDB element represents the
zone number. Z= is not necessary if one of the element variables has an appropriate
name for the zone number (see description of ZDATI for details).
NOTE: Cube 6.4 does not support EMME/2 data bank files.
FILE I k e y wo rd s
Ke y wo rd S ub k e y wo rd D e s c rip tio n

DBI |KF9| Name of a DBF file, MDB data element, or

an ASCII record file with either delimited
(separated by a space or a comma or
combination of both space and comma) or
fixed format records.
If you specify a DBF file, the program
recognizes the file and the fields.
Reference the field names in the DBF
header directly in the script as
DI.#.fieldname. Do not explicitly define the
variables in the DBI statement.
If you specify an MDB\element file and
name, the program recognizes the file and
the fields. Reference the field names in the
MDB data element directly in the script as
DI.#.fieldname. Do not explicitly define the
variables in the DBI statement.
If you specify an ASCII record file, define
all variables that you want the program to
recognize (DBI.#.name) in the DBI
statement, using the appropriate
keywords.
ASCII record files are either a fixed format
text file (fixed field locations and lengths),
or free format. You must indicate which
format is used in the definition of each
field. Indicate free format with field
definitions containing a single number.
Indicate fixed format fields by using
name=lo[-hi] or field=lo[‑hi] syntax, where
lo is the first column number of the field
and hi is the last column. (Indicate a
single-column character with the hi column
number the same as the lo column
number.)
Define a field as a character variable by
appending “(C)” to the name. For example,
TITLE(C)=1 would define the variable
named DI.#.TITLE as a character
variable, and would read the data from the
first data field in the input file
You can specify the delimiters for free-
format records using the DELIMITER
keyword.
(continued)

DBI The following special variables are

(continued) available for all file formats:
DBI.# — String variable containing the full
data record
DBI.#.JOINCOND — - Integer indicating the
status from a JOINTODBI action, i.e. when
the "Join To" DBI file is moved to a
different record. The return value is the
same as the return code for the DBISeek
function (see “More on DBI” on page 612):
• 0 = a match was found
• 1 = error (not common)
 • 2 = match not found and the current
record is the next higher key record

• 3 = match not found and the search

for key is greater than the last
record; the current record is the last
record
• -1 = no match found within in the
chain of joins; the current record is
not changed
DBI.#.NUMFIELDS — Number of defined
data fields
DBI.#.NUMRECORDS — Number of data
records in file
DBI.#.RECNO — Number of the currently
processed record
Different arrays are available. Each array
is dimensioned as [DBI.#.NUMFIELDS].
All the values (except Name and Type)
are updated each time the record is
processed. The arrays are:
DBI.#.CFIELD — String value for the
field (Null if DBI.#.TYPE=’N’)
DBI.#.FIELDERR — 1 if the field had a
format conversion error
DBI.#.FIELDERRCNT — Cumulative
count of errors for this field.
DBI.#.NAME — Name of the field
DBI.#.NFIELD — Numeric value for the
field (0 if DBI.#.TYPE=’C’)
DBI.#.TYPE — Type of field (either ‘N’
for numeric or ‘C’ for character

See “More on DBI” on page 612.

DBI AUTOARRAY |S| Designates the name(s) of the field(s) that

are to be stored in arrays with the
specified name. An array for each named
field will be generated and populated with
values from the DBI records. If you enter a
value of “ALLFIELDS,” all the fields will be
placed into arrays (no other names need
be supplied).
You can reference each array as
DBA.#.name[Index], where Index may be
0-DBI.#.NUMRECORDS. If Index is less
than 0 or greater than NUMRECORDS, the
value in DBA.#.name[0] is used. By
default, the value at ARRAY[0] will be 0 for
numeric fields and NULL for character
fields. You can provide a substitute value
for invalid Index processes, such as
DBA.1.Name[0] = 'ERROR' or
DBA.1.Name[0]=999999. Note that if the
name is included in a SORT, [0] will be
revised during the SORT, because the
SORT routine uses that cell for temporary
storage.

DBI AUTOMDARRAY |S| FILEI DBI[]=, TYPE=, AutoMDArray=,

Indexes=fld-size,fld-size,fld-size,
 ArrayFields=fld,fld,fld
This will load database or text file data into
arrays before any script processing. This
is very similar to the current AutoArray
capability but can be used to load data
into multi dimension arrays. The
AutoMDArray keyword is used to define
the array name.
The TYPE keyword is the same as the
TYPE keyword in the ARRAY statement for
declaring the data type/size of the array.
All AutoMDArray defined after the TYPE
keyword will have the same type as
specified by the TYPE keyword. Data from
the DBI record will be converted to a form
that is compatible with the array type (e.g.
string to numeric).
With no Indexes or ArrayFields specified,
the DBI file is loaded into a 2-dimension
array, the first dimension is the record
number and the second dimension is the
field number.
With the ArrayFields keyword, selected
fields can be loaded into the array. If there
are 2 ArrayFields, then the second
dimension will have a size of 2. The
special field name DBI.RECNO can be
included to add a field that contains the
record number of the DBI record.
If the data file has only one field or if only
one field is specified in the ArrayFields
keyword, then the array will have one less
dimension because there will be no need
to have an extra dimension to hold
multiple fields of data.

DBI AUTOMDARRAY |S| With the Indexes keyword, some of the

(continued) fields in the record can be used as array
indexes to populate the array. A size value
must be specified for each Indexes field
and it should be large enough to
accommodate the largest index value.
Any records with an index value large than
the stated size will not be loaded into the
array. This feature can be used to load
only selected records into the array. For
example:
FILEI DBI[x]=xxx, AutoMDArray=name3,
Indexes=fld1-10,fld2-20,fld3-30,
ArrayFields=fld4,fld5,fld6,DBI.RECNO
In this case, name3 will have 4 dimensions
(10x20x30x4), the values in fld1, fld2 and
fld3 determines the indexes for the first 3
dimensions and the fld4, fld5, fld6 and
DBI.RECNO values will go into 4th
dimension. If the field values in record 3
are:
fld1=11 fld2=12 fld3=13 fld4=14 fld5=15
fld6=16
then:
name3[11][12][13][1]=14, name3[11][12]
[13][2]=15, name3[11][12][13][3]=16,
 name3[11][12][13][4]=3
Another example:
FILEI DBI[x]=xxx, AutoMDArray=name3,
ArrayFields=fld1,fld2,fld3
In this case, name3 will have 2
dimensions, the record number is the
index for the 1st dimension and the fld1
value will go into index 1 of the 2nd
dimension. If the field values in record 3
are:
fld1=11 fld2=12 fld3=13
then:
name3[3][1]=11, name3[3][2]=12,
name3[3][3]=13
This form can be used to replace multi-
key discrete lookup tables. It will be easier
and faster.

DBI DELIMITER |S2| Use to specify two different controls for

free-format records.
DELIMITER[1] specifies the field-separator
characters. The default values are “ ,t”;
where t is used to designate a tab:
DELIMITER[1]=" ,t"
DELIMITER[2] specifies escape-character
sequences that permit field-separator
characters in free-format records. Specify
characters in pairs, the character that
marks the start of an escape sequence
along with the character that marks the end
of an escape sequence. Upon
encountering the starting escape-
sequence character, Cube Voyager treats
all subsequent data as part of the same
record until it encounters the ending
escape-sequence character, even if it
encounters a field-separator character.
The default value specifies single quotes,
double quotes, parenthesis, brackets, and
braces as escape character sequences:
DELIMITER[2]="""''()[]{}"
NOTE: You must enclose the entire value
in double quotes or single quotes.
If you include a single space as the last
character in DELIMITER[2], Cube Voyager
will remove the leading and trailing
character from any string it reads.
The starting escape-sequence character
in DELIMITER[2] cannot be a field-
separator character in DELIMITER[1].
You can specify both DELIMITER[1] and
DELIMITER[2] in one expression: Specify
DELIMITER= followed by two values
enclosed within quotes and separated by
a space or a comma.
Cube Voyager automatically removes
leading spaces from all fields, unless the
field is enclosed in an escape-character
sequence and DELIMITER[2] does not
contain a space as its last character.
 Example
Suppose you set a comma as field-
separator and double quotes as an
escape sequence:
DELIMITER=',' '""'
When reading the following input data:
John Smith, "Oakland, CA", USA
Cube Voyager reads three fields: “ John
Smith,” “Oakland, CA,” and “USA.”

DBI FIELDS |IPV| An optional method for defining data fields

in the input file. Used only when the DBI
records are fixed or free format. If this
keyword is present, only the fields
specified will be extracted.
The values specify the columns or fields
of the DBI file records where a desired
field is located. If a data field (FIELDS= or
name=) is defined by a pair of numbers
(lo-hi), that sets the format as fixed. If a
data field is defined by a single number
(field number on the records), that sets the
format as freeform. All data fields must be
defined in the same format.
For example:
FIELDS=1-5,6-10,21-25
Specifies that the data is fixed format and
DBI.#.NFIELD[1] is in columns 1-5,
DBI.#.NFIELD[2] is in columns 6-10, and
DBI.#.NFIELD[3] is in 21-25.
FIELDS=6,9,13
Specifies that the data is in free format and
defines DBI.#.NFIELD[1] comes from field
number 6, DBI.#.NFIELD[2] comes from
field number 9, and DBI.#.NFIELD[3]
comes from field number 13.
Optionally, FIELDS can specify multiple
successive fields with a single
specification (providing all fields are the
same type, N or C).
For example:
FIELDS=6(7)
Specifies that DBI.#.NFIELD[1]…
DBI.#.NFIELD[7] will be obtained from
fields 6 through 13 of the data records.
FIELDS=6(C7)
Specifies the same, but those fields would
all be character values.

You can reference these field values as

DBI.#.NFIELD[#], DBI.#.CFIELD[#] or as
DI.#.FIELD# in script statements.

DBI JOINTODBI |I| Specifies the number of the input DBI file to
join this DBI file to. If JOINTODBI is
specified for a DBI file, then the SORT
keyword must also be specified. The field
names referenced by the SORT keyword
define the join key. You must also specify
the JOINTOFIELDS subkeyword.
 You can use the DBI.#.JOINCOND
variable to check the status of the join
action, i.e. when the "Join To" DBI file is
moved to a different record. Please see
“DBI” on page 591.

DBI JOINTOFIELDS |SV8| Specifies the fields on the file referenced

by JOINTODBI that corresponds to the join
key fields identified by the SORT keyword.
This keyword can have fewer referenced
field names than the SORT keyword but
cannot have more than the number of sort
keys.
For example:
FILEI DBI[1] =
"TRIPRECORDS.DBF",
SORT=HHNO,PERSNO TRIPNO
FILEI DBI[2] = "PERSON.DBF",
SORT=HHID,PERSID JOINTODBI=1
JOINTOFIELDS=HHNO,PERSNO
In this example, DBI file 2 is a person-level
survey record file. This file contains the
fields HHID and PERSID, which uniquely
identify the person record, along with other
household and person-level demographic
data fields. DBI file 1 contains the person-
level trip records from a travel survey. This
file contains the fields HHNO, PERNO,
and TRIPNO, which uniquely identify each
person-trip record, along with other trip-
related data fields. Note that the key field
name on which the join is performed does
not need to match in the two files. With the
files joined, script statements that process
a trip record are linked to the
corresponding person-level data file,
enabling trip-based computations to
directly reference the household and
person-level characteristics in the joined
file.

DBI MAXRECS |I| Limits the number of records read from the
DBI file. If the DBI is not a DBF file, the
program treats both zero length and blank
records as legitimate records. If the file is
a DBF file, deleted records (flagged with a
“*”) are not counted as records.

DBI NAME |IP| Name of a variable to extract from a text

format record. The value contains the
location of that variable on the data
record.
You can reference the variable in other
parts of the script as DI.#..name. If the
name has “(C)” appended to it, the
variable type is character. If the name has
nothing— or “(N)”— appended, the variable
type is numeric.
The value must be either a single integer,
or a pair of integers (separated by a
dash). If the records are in free format, the
values must be single integers indicating
the field number in the data record. If the
 input records in fixed format, the value will
be lo-hi; if the field is a single column, it
must be designated as lo-hi, where
lo=hi=the column number of the data field.

DBI SORT |S9| Designates that the input records are to be

processed in a specified sorted order.
The values are the names of the variables
that the sort is based upon. There may be
up to nine sort keys. If a sort name is
preceded by a minus (-) sign, that field is
to be sorted in descending order. If there
is no leading sign, or there is a preceding
plus (+) sign, that field is to be sorted in
ascending order.
Note that SORT can reference the field
names created using FIELDS under the
current FILEI DBI. In this case the DI prefix
is not needed.

For example:
FILEI DBI[1] = "{FixedFormat}",
DELIMITER=' ', FIELDS=1(8),
SORT=FIELD3

Here, the SORT is performed on the third

field (of eight) declared in the DBI
statement.

LOOKUPI |FKV999| Name of file containing records for a

lookup function implemented with the
LOOKUP control statement.
Equivalent to the FILE keyword of the
LOOKUP control statement. You must
index LOOKUPI.

MATI |KFV20| Specifies the input files with matrix data. If

the file specifies a Cube Voyager, TP+,
MINUTP, or Tranplan binary matrix file, or
a standard data base (DBF) file, the
program will automatically detect it. If it is
not detected as one of those, it is
assumed to be an ASCII text file. If it is not
a binary matrix file, PATTERN and FIELDS
must be associated with the MATI.
MATI can process matrix files of any size,
subject to available system memory and
storage.

MA T I AUTOMDARRAY |S| FILEI MATI[]=, AutoMDArray=, MI=, I=, J=,

RESTRICTION=
This will load matrix data into multi-
dimensional arrays before any script
processing. Selected tables can be
loaded into arrays. If only one table is
selected, it will be loaded into a 2
dimension array. If multiple tables are
selected, then they will be loaded into a 3
dimension array with the first index being
the table number. For example:

FILEI MATI[x]=xxx, AutoMDArray=name1,

 MI=4,6-8

will load the matrix file table 4 to array

name1[1][i][j], matrix file table 6 to array
name1[2][i][j] etc. The same table number
can be specified multiple times to load the
same table into different part of the array.
The list of input table numbers do not need
to be in order (e.g. MI=6-8,4) but a range
pair must be specified in low-high order.
(continued)

MA T I AUTOMDARRAY |S| Selected I's and J's can be loaded into a

(continued) smaller array. For example:
FILEI MATI=xxx,
AutoMDArray=name2, MI=4, I=11-
15,21-25, J=31-35,41-45

will load parts of the matrix file table 4 to a

10x10 array with name2[1][1] = matrix[11]
[31], name2[6][7] = matrix[21][42],
name2[10][10] = matrix[25][45] etc. The
same I/J number can be specified multiple
times to load the same I/J into different
part of the array. The list of input I/J
numbers do not need to be in order (e.g.
I=6-8,4) but a range pair must be specified
in low-high order.
Additional restrictions can be applied
when loading the matrix data. The
RESTRICTION keyword can have a
combination of the following values:

LOWER – only load the lower part of the

matrix (I < J)
UPPER – only load the upper part of the
matrix (I > J)
DIAGONAL – only load the diagonal part
of the matrix (I = J)
IJ – applies the LOWER, UPPER, and
DIAGONAL filter based on the original IJ
number from the input matrix table

MATI FIELDS |S| Specifies the data fields to be read from

an input record. Any one (and only one)
format may be used to specify the fields. If
the MATI file is a database file, the values
in FIELDS must be names found in the dbf
dictionary. A range of names (name-
name) may be used to specify a string of
consecutive fields.
If the file is not a DBF, its format may be
either fixed or variable; the first field
definition establishes the format. If the first
field value is a number, the format will be
fixed; if it begins with a letter (not a digit),
the format will be variable.
With variable format, every field value
must end with a number (only the first field
value is required to have a leading non-
digit). Ranges of variable format fields
 may be specified. For example: #4-
6,10,13,2. A leading # is recommended
for variable format, although any character
string is acceptable. The program extracts
the number from the right end of the
definition; leading non-digits are ignored.
With fixed format, the field values define
the positions on the record where a data
field is located. The field values may be
entered as single values (single column),
pairs of numbers (beg-end), or as a group
of three (beg-end-numflds) to indicate a
series of equal length fields. Example:
FIELDS=1-3, 6-8, 10,11-20-8. For
a PATTERN=IJM:V, this example would
indicate that I is in columns 1-3, J is in
columns 6-8, M is in column 10, and eight
data fields (each 10 characters wide) are
in columns 11-20, 21-30,etc. (Note: When
reading with fixed format, the highest begin
column number may not exceed 2047. For
example, for a record longer than 2047
bytes, FIELDS=1-10-204 is OK, while
FIELDS=1-10-205 will get a warning
because the program is unable to read in
the last field. This limit is not applicable to
variable format files.)
When the field value of M is set to zero, it
indicates that the starting matrix number is
not included in the input data, hence,
implied, and the matrix number always
starts at one for each record. The
specification of FIELDS with implied matrix
number will be shown in the example in the
next section.

MATI PATTERN |S| Sequence of letters that specifies how the

program processes the associated text or
DBF MATI file. The pattern has two
portions separated by a colon: a base
portion and a repeating portion.
In the pattern definition:
• There must be a single I, J, and V. I
must be the first letter in the base
portion, and V must be in the
repeating portion.
• There may be one M to specify the
starting matrix number. If there is no
M, matrix 1 is assumed. The highest
M that the program recognizes is
255.
• If there are multiple characters in the
base portion, the last character in the
base portion indicates which
variable is incremented for each
repeating set.
Valid combinations are:
IJ:V — I J values for J,J+1,J+2...
IMJ:V — I M J values for J,J+1,J+2...
IJM:V — I J M values for M,M+1,M+2...
I:JV — I sets of J and V
 I:VJ — I sets of V and J
IJ:VM — I J sets of V and M
IJ:MV — I J sets of M and V
IM:JV — I M sets of V and J
IM:VJ — I M sets of J and V
I:JVM — I sets of J, V, and M
I:JMV — I sets of J, M, and V
I:MJV — I sets of M, J, and V
I:MVJ — I sets of M, V, and J
I:VJM — I sets of V, J, and M
I:VMJ — I sets of V, M, and J

(continued)

MATI PATTERN This method allows Cube Voyager to read

(continued) any commonly encountered input format. It
is necessary to have FIELDS specified in
conjunction with PATTERN. The above
examples assumed that the FIELDS
values implied variable format and that
there was an appropriate number of
FIELDS values specified. If the values
specified in FIELDS do not align correctly
with the PATTERN, a warning message is
issued. When reading a data record, the
program aligns the next FIELDS value with
the next letter in the PATTERN, and extracts
the data. When the PATTERN is exhausted,
the reading continues from the beginning
of the repeating portion of the PATTERN.
This continues until the FIELDS list is
exhausted. If the FIELDS list is exhausted
before the end of the PATTERN, reading is
terminated without storing the last repeat
value.
Note that the data values need not be
read in sequential order from the input
records. The FIELDS values can be used
to specify any order.
See “More on MATI PATTERN” on
page 613.

MATI SKIPRECS |I| Instructs MATRIX to skip over a number of

records in the input file before processing
the data records. This is useful when the
file has header line(s) which do not contain
data.
For example:
MATI[1] = Inputs.CSV
PATTERN=IJ:V FIELDS=1-10-202
SKIPRECS=2

In this case, the first two records (rows of

data) in Inputs.CSV will be ignored when
processing the file.
RECI |KF| Name of a DBF file, an element in a
multidatabase file, or an ASCII record file
with either delimited or fixed format
records.
 NOTE: RECI can process up to 32,000
characters per record (or ‘row’ of the data
file). If there are more than this, MATRIX
will issue an error message. Note also that
Cube Voyager might not properly process
database files larger than 2 GB.
For text files, you must define all variables
that the program will recognize (RI.name)
in the FILEI RECI statement using the
appropriate subkeywords. For DBF or
MDB files, the program recognizes field
names in the DBF or MDB header; do not
explicitly define the variables in the FILEI
RECI statement. You can reference these
fields directly in the script as
RI.fieldname.
For text files (files other than DBF or MDB
files), use the first variable to indicate the
file format, either delimited (free format,
separated by commas or spaces) or fixed
format. Define the first field as a single
number to indicate delimited format.
Define the first field as name=lo[-hi] or
field=lo[-hi] to indicate fixed format
(where lo is the first column number of the
field and hi is the last column). For single-
column characters, you must designate
the hi column as the same as the lo
column. To define a variable as a
character variable, append “(C)” to the
name. For example, TITLE(C)=#1 would
define the variable named TITLE as a
character variable; the program consider
data read from the first data field on the
input file to be character data.
You can also specify the delimiters for
delimited records with the DELIMITER
keyword.
If there are any RECO statements, all RECI
variables (RI.name) on the input file are
automatically copied into equivalent
RO.name variables immediately when a
record is read. The RI.variable attributes
are ported to the corresponding
RO.variables. Only variables with the
RO.prefix can be written to the RECO file.

RECI The following special variables are

(continued) available to the user for all file formats:
RECI — String variable containing full data
record
RECI.NUMFIELDS — Number of defined
data fields
RECI.NUMRECORDS — Number of data
records on the RECI file
RECI.RECNO — Number of the current
record being processed
The program also makes four different
arrays available to the user. Each array is
dimensioned as [RECI.NUMFIELDS]. The
arrays are:
RECI.NAME — Name of the field
 RECI.TYPE — Type of field (either ‘N’ for
numeric or ‘C’ for character
RECI.NFIELD — Numeric value for the field
(0 if RECI.TYPE=’C’)
RECI.CFIELD — String value for the field
(Null if RECI.TYPE=’N’)
The NFIELD and CFIELD values are
updated to the values from each record as
the record is read.
If a RECI statement is present, the
program enters a record processing loop
instead of the traditional I-loop. Thus,
MATIs are not read unless a MATVAL
function is used, and FILEO MATO
keywords should not be used. As each
RECI record is read, it is processed
against the script statement stack. The
PRINT statement allows the user to write
out any portion of the input record plus any
computed variables.
The record processing loop sets I=1 and
reads records until the end of file is found
where it sets I=0. To test on end of file the
IF (I=0) condition can be used.
See “More on RECI” on page 615 for
some examples.

RECI DELIMITER |S2| Use to specify two different controls for

free-format records.
For details, see DELIMITER description
under DBI keyword on page 596. Usage
of DELIMITER is the same under both
keywords.

RECI FIELDS |IPV| This is an optional method to NAME for

defining data fields on the input file and it is
used only when the RECI records are fixed
or free ascii format. If this keyword is
present, only the fields specified will be
extracted. The values specify the columns
or fields of the RECI file where a field is
located. If a data field (FIELDS= or name=)
is defined by a pair of numbers (lo-hi), that
sets the format as fixed. If a data field is
defined by a single number (field number
on the records), that sets the format as
freeform. All data fields must be defined in
the same format.
For example: FIELDS=1-5,6-10,21-25
specifies that the data is fixed format and
RECI.NFIELD[1] is in columns 1-5,
RECI.NFIELD[2] is in columns 6-10, and
RECI.NFIELD[3] is in 21-25.
FIELDS=6,9,13 specifies that the data is
in free format and will define
RECI.NFIELD[1], RECI.NFIELD[2], and
RECI.NFIELD[3] coming from data fields
number 6, 9, 13 respectively.
Optionally, FIELDS can specify multiple
successive fields with a single
specification (providing all are the same
TYPE, N or C). FIELDS=6(7) specifies
 that RECI.NFIELD[1] … RECI.NFIELD[7] will
be obtained from fields 6 through 13 of the
data records. FIELDS=6(C7) would be
the same, but those fields would all be
character values.
These fields can either be referenced as
RECI.NFIELD[#], RECI.CFIELD[#] or as
RI.FIELD# in stack statements.
Up to 16,384 fields may be defined.

RECI LISTERRS |?| Flag that indicates if errors should be

listed to the run print file. Default value is F.
If LISTERRS=T then MAXERRS
automatically defaults to MAXERRS=1000.
This is to prevent excessive listing of error
messages to the run print file. If the user
wishes to see more than 1000 error
messages in the run print file then he must
explicitly code the MAXERRS value
desired.

RECI MAXERRS |I| Maximum number of errors allowed in

reading the RECI records before a fatal
error message is returned. Default value is
no limit. The default setting will not return a
fatal error message no matter how many
errors are detected.

RECI MAXRECS |I| Places a limit on the number of records to

be read in from the RECI file. Default value
is no limit.

RECI MAXSCAN |I| Allows the user to limit the file sampling for
text records in order to reduce front end
time on very large files. The program
normally scans the entire file to obtain the
longest record, the number of records, the
maximum length of each field, etc. That
could be quite time consuming, and not
really productive for very large files such
as the census files. If the user is certain
that all the records are the same length,
the use of this keyword can reduce front
end time. This value will be used only if the
format is fixed, and there is no SORT
specified. The value must be >= 10, if
specified. This control should not
generally be used and was added
primarily for internal Citilabs use. I maybe
save time if processing very large data
files.

RECI NAME |IP| Name of a variable to be extracted from a

text format record and the value will be the
location of that variable on the data
record. It can be referenced in all other
parts of the script as RI.name. If the name
has “(C)” appended to it, the variable will
be considered as character. If it has
nothing, or “(N)”, appended, the variable
will be considered numeric. The value
must be either a single integer, or a pair of
integers (separated by a dash), to
designate where the variable will be
 obtained from each record. If the records
are read in free format, the values must be
single integers indicating the field number
on the data record. If the input records are
read in fixed format, the value will be lo-hi;
if the field is a single column, it must be
designated as lo-hi, where lo=hi=the
column number of the data field.

RECI SORT |S5| Designates that the input records are to be

processed in a specified sorted order.
The values are the names of the variables
that the sort is based upon. There may be
up to five sort keys. If a sort name is
preceded by a minus (-) sign, that field is
to be sorted in descending order. If there
is no leading sign, or there is a preceding
plus (+) sign, that field is to be sorted in
ascending order.

Note that SORT can reference the field

names created using FIELDS under the
current FILEI RECI. In this case the RI prefix
is not needed.

For example:
FILEI RECI = "{FixedFormat}",
DELIMITER=' ', FIELDS=1(8),
SORT=FIELD3

Here, the SORT is performed on the third

field (of eight) declared in the RECI
statement.

ZD A T I |KFV10| Specifies the input files containing zonal

data. There can be up to 10 zonal data
files. Zonal data is data which is specific
for each zone. Every zonal record must
include a field that identifies the zone to
which the record data applies. Aside from
the zone number, any fields from the
record can be extracted and used by the
program.
The file format can be: ASCII, DBF, MDB,
or a Cube Voyager binary network. The
program will try to detect what type of file it
is. If it cannot identify the file as a DBF,
MDB, or a Cube Voyager network, it will
assume ASCII. When the program detects
a Cube Voyager network file, it opens the
node database portion of the file as zonal
data.
If the file is of ASCII format, the fields to be
extracted must be named and identified
on the ZDATI statement by either relative
field number, or by exact column positions
on the records. The field that contains
zone number must be specified using 'Z='
keyword.

(continued)
ZDATI If the file is a DBF, MDB, or a Cube
(continued) Voyager network, it is not necessary to
name the fields to be extracted. All fields
will be extracted and can be referenced, in
the script, by existing field names from the
input file. (DBF field names up to 11
characters long may be input). The
specification of zone number field is
optional for those two file formats. If 'Z=' is
present, the specified field will be used to
extract zone number. Otherwise, the
program will try to determine the zone
number field based on file type. For DBF
or MDB files, the program will go through
all field names to find a match with one of
the following possible zone field names, in
the given order: {Z, I, J, ZONE, ZONA,
TAZ}. The first matched name will be used
to extract zone number. (Note: For files with
more than one possible zone field from the
list above, it is recommended to specify
zone number field explicitly to ensure the
correct field is used.) For Cube Voyager
network files, node numbers (N) will be
used as zone numbers by default.
ZDATI can contain string data fields.
Where fields cannot have their type
automatically determined such as NET,
MDB or DBF files, require the type to be
specified with the parameters. Character
fields must have the "(C)" suffix appended
to be treated as string input. E.g. FILEI
ZDATI[2] = "EITrips.csv",
OID_=#1,Z=2,EITRIPS=3,NAME(C)=4

ZDATI AVE |SV| Average of all records.

ZDATI AVEX0 |SV| Average of all records, where the value

from the file records is not 0.

ZDATI CNT |SV| Count of the records that contain the

variable.

ZDATI DEFAULT |R| Value with which to initialize the array for
the named variable. Then, if there are no
records for a zone, or the field is blank on
a record, this value will be used.
The following keywords indicate a
process to use in obtaining the value for
the variables that are listed following the
keyword when there is more than one
record per zone. The values for the
variables will be obtained only from file
records that contain the variable. A
variable may appear in only one keyword
list; any variables that are not in any list will
be set to LAST.

ZDATI FIRST |SV| Directly from the record from the FILEI with
the lowest index [].

ZDATI LAST |SV| Directly from the record from the FILEI with
the highest index [].

ZDATI MAX |SV| Maximum value of all the records.

ZDATI MIN |SV| Minimum value from all the records.

ZDATI NAME |S| Identifies a data variables that is to be

extracted from each record. Only the
variables named will be extracted. If the
file is a dbf, the value for each name is the
name from the DBF dictionary. In most
DBF cases, name=name would be the
standard, but it is not necessary to keep
the same names. For text files, the value
assigned to name is either a field number
(delimited format), or the columns (fixed
format) where the variable is located on
the record. All names must be specified
with the same format; the first name value
(including Z) establishes the format. If the
first value is a number, fixed format is
assumed; otherwise, delimited format is
assumed. If delimited format is specified,
each name value MUST end in a number.
It doesn’t matter what string precedes the
number (the value need not be prefixed
with a string). Example: Z=#1,POP=#2,
AREA=3, SALES=xxx4. These are all be
valid, because Z specified triggered
delimited format. Z=1-5,POP=#2 would be
invalid because Z specifies fixed format.

ZDATI SELECT |S3| Used to cause selective reading of zonal

data records from ASCII files. The
program will compare a field from each
record with the string specified in
SELECT[1], and if the comparison fails,
the record is bypassed. This selection is
not used if SELECT is not specified.
SELECT[2] specifies the input record field
whose value is to be compared with the
value of SELECT[1]. If SELECT[2] is a
number, it designates the beginning
column of the comparison field on the input
record, and SELECT[3] can be optionally
specified to designate the ending column.
SELECT[2] and [3] must both be numeric
and should be separated by a dash.
Alternatively, if`SELECT[2] is not numeric,
but ends with a number (first example), it is
assumed that the value indicates a
relative field number on the data record.
That field is the comparison string.
SELECT[3] is ignored if SELECT[2] is a
free field definition.
SELECT=abc,6-8 select only if columns 6-
8=abc
SELECT=1,#2 select only if a 1 in field no.
2

ZDATI SUM |SV| Sum of all the records.

ZDATI Z |S| Identifies where the zone number identifier

is found on each data record; Z is required
for ASCII files and also if a DBF file is
being used and one of the special field
names :
 {Z, I, J, ZONE, ZONA, TAZ} is NOT in the
DBF file.. 'Z=' is a special case for
'name='.

Caveat: The program establishes a buffer to read file records into. It has to know how
long a buffer is required. With DBFs and fixed format records, the required length is
known, but with delimited format, the required length can not be estimated exactly. For
delimited files, the record length is estimated by multiplying the highest field number by
10. If the estimated length is inadequate, a dummy variable with a high field number can
be specified to generate a larger record length.
Matrix Program > Control statements > FILEI > More on DBI

M o re o n DBI

DBI files are not automatically processed. You must write scripts to read the records.
Several functions are available to read the records. Use these functions in a COMP
statement with the form: N=DBIfunc(DBI#,...). DBI# must always be the first argument.
All the functions return a value to indicate the success of the operation. A return value of
0 indicates a successful operation; any other value indicates the read was not 100%
successful. You must check the return code. The functions are:
• DBIReadNext(#,R) where R indicates the record to read, specified relative to the current
record. A negative R means prior to the current record, and a positive R means after the
current record. Write sequential reads as DBIReadNext(#,1), though DBIReadNext(#) is
also allowed. A return code of 1 indicates any of the following errors: bad #, R<1, or
R>DBI.#.NUMRECORDS.

• DBIReadRecord(#,R) where R indicates the record to read. R must be 1 –

DBI.#.NUMRECORDS, or the return code will be 1.

• DBISeek(#, R,...) where R is a value to search for in the field specified as SORT[1]. In
order to use this function, there must be at least as many SORT values as there are R
arguments. There may be fewer R values than there are SORT fields, but not more. This
function searches for the record that matches all the specified R values. The return values
are:
m
0 — A match was found.
m
1 — An error in setup occurred.
m
2 — A match was not found, and DBI.#.RECNO is set to the record that is above the R
selections.
m
3 — The R values are greater than the last record and DBI.RECNO is set to the last
record.
In all cases, the DI.#.field values are extracted from the record indicated by
DBI.#.RECNO, and the record pointer points to that record.
See “Example 5: DBI processing using JOINTODBI” on page 659 and “Example 6:
DBI processing using AUTOARRAY” on page 659 for examples of DBI processing.

NOTE: Youcan create and populate arrays with just a FILEI DBI statement; you do not
need DBIRead functions.
Matrix Program > Control statements > FILEI > More on MATI PATTERN

M o re o n M ATI PATTERN
Example for MATI[1]
PATTERN Data record fields I M [J] Values
IJ:V 1 15 21 22 23 24 I=1 MI.1.1[15-18] 21,22,23,24
IMJ:V 1 6 18 100 101 105 I=1 MI.1.6[18-20] 100,101,105
I:JMV 5 12 1 8 14 2 90 I=5 MI.1.1[12] 8
I=5 MI.1.2[14] 90
IJM:V 5 12 3 8 14 2 90 I=5 MI.1.3[12] 8
I=5 MI.1.4[12] 14
I=5 MI.1.5[12] 2
I=5 MI.1.6[12] 90

The above PATTERNS do not provide for the situation where the record contains I, J,
then multiple values to represent matrix 1, 2, 3… In this case, the PATTERN IJM:V, with
the FIELD value of M set to zero, can be used to describe the input data. The matrix
number is implied and always starts with 1 on each record. The following example
illustrates the specification of PATTERNS and FIELDS for input data with implied matrix
number:
Example (implied matrix number)

(input data record)

1 15 21 22 23 24
(Cube Voyager script)
MATI[1]=input.txt, PATTERN=IJM:V, FIELDS=1-2,3-4,0,5-7-4 ; fixed format
or
MATI[1]=input.txt, PATTERN=IJM:V, FIELDS=#1,2,0,3-6
; variable format
or
MATI[1]=input.dbf, pattern=IJM:V, FIELDS=I,J,0,V1,V2,V3,V4; DBF format
; The input dbf in this example would have the named
; fields I,J,V1,V2,V3,V4
(results)
I=1, J=15, MI.1.1=21, MI.1.2=22, MI.1.3=23, MI.1.4=24

The above PATTERNs also do not provide for the situation where the record contains I,
then multiple values to represent J values 1, 2, 3... for a single matrix (implied matrix
number M=1). In this case, the PATTERN IJ:V, with the FIELDS value of J set to zero,
can be used to describe the input data. The J value is implied and always starts with 1
on each record. The following example illustrates the specification of PATTERN and
FIELDS for input data with implied J number:
Example (implied j index number)

(input data record)

1 37.3912 54.5413 6.8414 14.5015
2 167.1612 269.2513 35.5314 75.1215
3 13.0612 22.1213 4.8514 10.6815
4 31.6512 54.2813 12.2914 31.3815
This example data represents a 4 zone matrix with the I values in column and the cell
values for the implied J zones in columns 2 through 5. The script example below will
build a binary matrix using the implied J values.
RUN PGM=MATRIX
FILEI MATI=temp1.DAT PATTERN=IJ:V FIELDS=#1,0,2-5
FILEO MATO=temp1.mat MO=1
PAR ZONES=4
MW[1]=mi.1.1
ENDRUN
Matrix Program > Control statements > FILEI > More on RECI

M o re o n RECI

Example RECI statements:

FILEI RECI=myfile.dbf, SORT=key2, -key1, +key6
FILEI RECI=myfile.mdb\mytable, SORT=key2, -key1, +key6
FILEI RECI=myfile.txt, nvar1=1-3, nvar2=5-8, cvar3(c)=10-10, SORT=nvar2, cvar3
FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(C)=3, DELIMITER[2]='//'
FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(C)=3, DELIMITER[2]='""'' '
FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(c)=3,
DELIMITER=' ,;t' , '//() ' SORT=-nvar1,+cvar3

Example of usage: to sum all the housing units in a record (even if the exact names are
not known, but we do know that all units fields are named xxUNITS):
TotUnits=0
Loop k=1,RECI.NUMFIELDS
If (RECI.TYPE[K] = 'N' && substr(RECI.NAME[k],3,5) = 'UNITS') TotUnits = TotUnits +
RECI.NFIELD[K]
EndLoop

Example:
In a record processing run of matrix
VAR1TOTAL=VAR1TOTAL+VAR1
IF (I=0)
VAR1AVG=VAR1TOTAL/RECI.NUMRECORDS
PRINT LIST=RECI.NUMRECORDS,VAR1TOTAL,VAR1AVG
ENDIF

would sum the values of the variable VAR1 and once all records have been read (I=0)
compute the average value of VAR1 and print to the report file the number of records,
the total of VAR1 and the average of VAR1
Example:
RUN PGM=MATRIX
FILEI RECI=network_link.dbf
PARAMETERS MAXSTRING=100
if (RI.A>25 & RI.B>25)
print, list=ri.A,',',ri.B,',',ri.ROAD_TYPE,',',
ri.IMPORTANCE,',',ri.ROAD_NAME,',',
ri.CLASS,',',ri.SPEED,',',
ri.PICTUREFIL file=tmp1.csv
endif
if (I=0)
print list='Number of link records=',
RECI.NUMRECORDS file=tmp2.dat
endif
ENDRUN

Example:
copy file = junk.txt
11 22 33 44 55 66 77 88 99 aa bb cc dd 56 78 90 12
aa bb cc dd 56 78 90 12
endcopy

RUN PGM=MATRIX
;get 1st 5 data fields as numeric fields and also as character fields
FILEI RECI = junk.txt,Fields=1(c5),1(n5)
FILEO RECO[1]=junkout.dbf FIELDS=reci.allfields
FILEO PRINTO[1]=junkprn.prn

write reco=1

print printo=1 form=5lr,list='\nRecno=',reci.recno,' NumFields=',reci.numfields,

' highest field=',reci.fields,' lng=',reci.lng

print printo=1 form=5lr,list=reci,'\ncfield[1-5] =',

reci.cfield[1],'..',reci.cfield[2],'..',reci.cfield[3],'..',
reci.cfield[4],'..',reci.cfield[5],'..\nnfield[6-9] =',

reci.nfield[6],'..',reci.nfield[7],'..',reci.nfield[8],'..',
reci.nfield[9],'..',reci.nfield[10],'..\nri.field1..5 =',

ri.field1,'..',ri.field2,'..',ri.field3,'..',
ri.field4,'..',ri.field5,'..\nri.field6..10=',

ri.field6,'..',ri.field7,'..',ri.field8,'..',
ri.field9,'..',ri.field10,'..'
endrun

Results of the PRINTO file from the above example:

Recno=1 NumFields=10 highest field=5 lng=50

11 22 33 44 55 66 77 88 99 aa bb cc dd 56 78 90 12
cfield[1-5] =11..22..33..44..55..
nfield[6-9] =11..22..33..44..55..
ri.field1..5 =11..22..33..44..55..
ri.field6..10=11..22..33..44..55..
Recno=2 NumFields=10 highest field=5 lng=23
aa bb cc dd 56 78 90 12
cfield[1-5] =aa..bb..cc..dd..56..
nfield[6-9] =0..0..0..0..56..
ri.field1..5 =aa..bb..cc..dd..56..
ri.field6..10=0..0..0..0..56..
Matrix Program > Control statements > FILEI > Example of FILEI statements

Exam ple o f FILEI statem ents

These statements show various examples of FILEI usage:

FILEI MATI=test11.dat,test12.dat ; MINUTP binary matrix files
MATI[4]=tppltrips.mat ; TPP or MINUT matrix file
MATI[5]=external.txt, PATTERN=IJ:V, FIELDS=1-4,6-8,11-10-20
MATI[6]=external.var, PATTERN=IJM:V FIELDS=#1-30
MATI[7]=external.dbf, PATTERN=I:JMV FIELDS=ORG,DEST,MAT,TRIPS
ZDATI[1]=housing.txt, Z=#1,DU1=#2,DUPLEX=3,MULTI_FAMILY=4,
CONDO=5,RETIREMENT=6 SELECT=abc-1-3 FIRST=DU1, LAST=DUPLEX
ZDATI[4]=pop.txt,Z=1-5,poptotal=6-15,popmale=16-25,popfemale=26-35,
popyouth=36-45,pop19-65=46-55,popsr=56-65

These statements show an example of simple record processing:

copy file=reci_in.txt ; generate input file
A 1 2 3 4 5 6 7 8 9 10
B 1 2 3 4 5 6 7 8 9 10
endcopy
run pgm=matrix
reci=reci_in.txt, FIELDS=1-3 ; switch to record processing mode
; each data record is stored in a string variable ”reci”
s2=substr(reci,11,12)
s3='Z'
if (substr(reci,1,1)=='A') s3='B'
; I is the end-of-file indicator
print list=i(3.1), ' ', reci(10), s2, '.', s3, file=out_reci.txt,
print=y
; will result in
; 1.0 A 1 2 3 4 5 6 7 8 9 10.B
; 0.0 B 1 2 3 4 5 6 7 8 9 10.Z
endrun

These statements show an example of getting I-J values from a delimited file:
RUN PGM=MATRIX
RECI = myfile, org=1, dest=2
MATI[1] = mymat; contains time and distance matrices in 1 and 2
If (RI.ORG > 0 && RI.DEST>0)
Time = matval(1,1,RI.ORG,RI.DEST,0)
Dist = matval(1,2,RI.ORG,RI.DEST,0)
Else
Time=0, dist=0
Endif
print file=outfile, list=reci, time(6.2LR), dist(8.2LR)
; duplicate RECI and append time and dist in delimited format
ENDRUN
Matrix Program > Control statements > FILEO

FILEO
Programs : Distribution, Fratar, Matrix
Outputs data files. Keywords include:
• MA T O
m DEC
m DELIMITER
m FIELDS
m FORMAT
m MAXFIELDS
m MO
m NAME
m PATTERN

• P R IN T O
m APPEND

• R E CO
m CFORM
m EXCLUDERECI
m FIELDS
m FORM
m NAME
m REPORT
m Z

Use FILEO to specify the type and number of output files for the program to produce.
Cube Voyager writes matrix type output files at the end of each I zone.
PRINT statements write formatted print files to the PRINTO file. WRITE statements write
RECO files to the referenced DBF file or can point to elements in a multidatabase (MDB)
file by designating the file name followed by a backslash and the element name.
NOTE: Cube 6.4 does not support EMME/2 data bank files.
FILE O k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

MATO |KFV20| Name of an output matrix file. May have an

index [x] appended. If you do not specify an
index, the program assumes the index is 1.
Indices need not be monotonic or
 sequential. The program can write output
matrices in various formats, which you can
use with other software.
MATO may generate matrix (*.mat) files of
any size, subject to available system
memory and storage.

MATO DEC |SV*| Specifies numeric format of values in the

output matrix. Specify a separate for each
MO. Valid entries vary by file format:
• Cube Voyager files
Valid entries include:
m 0 through 9 — Writes output matrix
cells in fixed-point format,
preserving the indicated number
of digits following the decimal.
This is the traditional format for
transportation planning matrices.
NOTE: Cube Voyager stores fixed-
point format as a decimal-coded
integer. If the cell value exceeds the
maximum integer value
(2,147,483,647), then Cube Voyager
reduces the number of digits stored
after the decimal. For example, with
=5, Cube Voyager stores
1,258,756.33715 as the integer
1,258,756,337, which translates to
1,258,756.337.
m S — Writes output matrix cells in
single-precision floating-point
format (4 bytes). This format
provides seven to eight significant
digits (or significant figures). As
such, the largest floating point
mantissa which can be
consistently respresented is
9999999. Additional digits may
change from their original value
when a program reads them.
Certain matrices might require
more precision.
m D — Writes output matrix cells in
double-precision floating-point
format (8 bytes). This format
provides 15 to 16 significant digits
(figures)., twice the number when
using single precision (S, above).
If you do not specify , the default value
is 2.
Cube Voyager processes all matrices
in double-precision floating-point format
to accommodate a wider range of
values and to maintain accuracy and
precision. However, writing double-
precision numbers to the matrix files
might produce very large files. In most
cases, a few decimal places for each
cell value are adequate.
(continued)
MATO DEC For example, for a cell computed as
(continued) 10/3, the result is 3.33333333... to sixteen
digits. If stored as fixed-point with =0, the
result is 3, and requires one byte to
store. However, this result might not be
precise enough for the subsequent
uses. If stored as fixed-point with =2, the
result is 3.33, and requires two bytes to
store. If stored as single precision with
=S, the result is accurate to about seven
digits, and requires four bytes to store. If
stored as double precision with =D, the
result requires eight bytes to store.
• MINUTP or Tranplan files
Do not set . The program ignores the
setting and automatically writes 4‑byte
values, usually integer numbers. You
must set the included work matrices to
the desired external format before the
program writes the matrices. Storing
numbers larger than the maximum
integer value (2,147,483,647) will result
in erroneous values.
NOTE: Normally, you round matrices
that represent level-of-service (time,
distance, cost, and so on), and “bucket
round” matrices that represent trips to
ensure row totals.
COMP MW[1]=INT(MW[1]*100+.5)
; LOS rounding
COMP MW[2]=MW[2]*100,
Total=ROWFIX(2) ; bucket
rounding
Optionally, set =S to write a single-
precision matrix. However, you cannot
use such a matrix as input to Cube
Voyager.
• TRIPS files
Set to the number of digits after the
decimal point (0 to 9). The program
stores numbers as integers with implied
decimal. If you set to S or D, the
program treats as =0. If a number’s
integer value with implied decimal
exceeds the maximum integer value
(2,147,483,647), the program substitutes
the maximum integer value for that
number.
(continued)

MATO DEC • Text files

(continued)
Set to the number of decimal places to
format in text records. If you do not code
, the program uses the default value of
2. If you specify DELIMITER, the
program writes variable-length values
and truncates trailing zeros, otherwise
the program writes fixed field lengths,
based on the values of FIELDS.
• DBF files
 Set as for Cub Voyager files. However,
the program uses the [1] value for all
the matrix data fields unless “M”
immediately precedes the colon in
PATTERN (for example,
PATTERN=IJM:V). If you set PATTERN
such that M varies in a record’s matrix
data values, the program uses [#]
appropriately.
NOTE: Regardless of file format and value
format, Cube Voyager can never store
matrix values smaller than 10-300 or larger
than 10300. Cube Voyager will cap values
outside this range. In addition, calculations
that result in values outside the double-
precision number range, will result in an
overflow condition.

MATO DELIMITER |S| For text files only (FORMAT=TXT). Character

that separates data values. When you code
this subkeyword, the program writes data
values in variable length and separates
values with this character. If you do not
specify DELIMITER, the program writes fixed
field lengths, based on the values of
FIELDS. Usually, you delimit data with a
comma or space. To use a comma or
space, enclose with quotes, ' '.

MATO FIELDS |IV4| Field width for data values when DELIMITER
is not specified. The number of values
specified with FIELDS must match the
number of letters in PATTERN (the “base”
portion precedes the colon, and the
“repeating” portion follows the colon). The
first FIELDS value always sets the length for
I. After exhausting the list of FIELDS values,
the program reverts to the FIELDS value that
corresponds to the repeating portion of
PATTERN. If the FIELDS value that
corresponds to a base portion of PATTERN
is set to 0, the program omits the
corresponding data.
Examples:
PATTERN=IJ:V FIELDS=4,4,6
• I will always be in 1-4
• J will always be in 5-8
• V will be in 9-14,15-20,21-26 ...
PATTERN=I:JVM FIELDS=4,4,6,2
• I will always be in columns 1-4
• J will be in 5-8, 17-20, 29-32 ...
• V will be in 9-14, 21-26, 33-38 ...
• M will be in 15-16, 27-29, 39-40 ...
PATTERN=IJM:V FIELDS=4,4,0,8
• I will always be in columns 1-4
• J will always be in 5-8
 • M will not be written to the data
records

• V will be in 9-16,17-24,25-32 ...

MATO FORMAT |S| Type of file written:

• TPP — Standard Cube Voyager/TP+
matrices
• MINUTP — Standard MINUTP
matrices
• TRANPLAN — Standard Tranplan
matrices
• TRIPS — Standard TRIPS matrices
(also used for Cube Analyst)
• TXT — Text records of matrix values
• DBF — DBF records for matrix values
Default value is TPP, unless you set
PATTERN. With PATTERN set, the default
value is TXT.

MATO MAXFIELDS |I| Maximum number of value sets written on a

single record. If not set, the program does
not limit the size of a data record (there is a
limit of 255 fields in a DBF record). A “value
set” is the group of values that follow the
colon in PATTERN.
For example, with IJ:V, MAXFIELDS=10,
the program writes at most 10 V values on a
record. With IJ:VM, MAXFIELDS=10, the
program would write at most 10 sets of VM
values on a record, for a maximum of 20
fields.
Use care with DBF files. If MAXFIELDS is
less than the number of matrices specified
with MO, the program will split a logical data
record into multiple records. The results
might be confusing.
Citilabs recommends that you always set
MAXFIELDS.
The program tests MAXFIELDS before
writing a value set. If the repeating portion of
PATTERN (the “repeating” portion follows the
colon) is only V and the program
encounters a string of zero values, the
program will start a new record if starting a
new record requires less space. The new
record will begin with the next J containing a
value. If the repeating portion of PATTERN is
more than V (contains a J or M, or both), and
V is zero, the program does not write the
value set.
Example
FILEO MATO=TPPTEST.MAT, MO=1-5,
NAME=HBWORK,HBOTHER,NHB,IXI,XX
MATO[3]=DEMO12.DAT,
FORMAT=MINUTP, MO=1,3,5‑7,
NAME[3]=PURP_5
MATO[4]=TEST4.TXT,
PATTERN=IJ:MV, MO=1-8,
 MAXFIELDS=1000, DELIMITER=','
MATO[15]=TEST15.TXT,
PATTERN=I:JMV, MO=3‑7,42,
FIELDS=4,4,2,6,
=6*0, [3]=2

MATO MO |IVP| List of working matrices that the program

writes in the output file. You may index MO.
Note that missing MO index values are
acceptable when writing binary files but not
when writing text files. The highest implicit or
explicit index determines the number of
matrices included in the output file. You may
write the same working matrix more than
one time.
For example, with MO=1-5,11-15,
MO[20]=1, MO[6]=31 the program will
write 20. Nine of the matrices (11-19) will be
empty because no data was entered for
them. The program numbers output
matrices monotonically beginning with 1.

MATO NAME |SV| For TP+, Cube Voyager, Tranplan, and

TRIPS output files, specifies the names for
the matrices. Each output matrix (specified
by MO) does not require a name, but
including a name helps document the file.
Valid matrix names contain only
alphanumeric characters, spaces, and
underscores (_). Cube Voyager programs
reading the file can reference the matrices
by name and/or number.
For MINUTP and text output files, the
program ignores NAME.
For DBF output files, specifies user names
for the record variables. NAME[1..n] will
refer to the beginning n record fields, which
will align with PATTERN. If there are three
characters prior to the colon in PATTERN,
NAMES[1-3] refers to those fields.
NAME[n+1] refers to the first actual data
field that corresponds with the first character
following the ”:” in PATTERN.

MATO PATTERN |S| Sequence of characters that indicates the

order the program writes values to the
output records. Valid values of PATTERN
are listed and described under FILEI MATI
PATTERN on page 603. The program
begins a new record each time either of the
first two characters of PATTERN change
values (exception: IJ:V begins new
record for each I change).

PRINTO |KF| Specifies the name of the file where the

output from a PRINT statement is to be
directed using PRINT PRINTO=#.

PRINTO APPEND |?| See APPEND under “PRINT” on page 69.

R E CO |KF20| File name for the RECO specified. Each

RECO must have an index [x] appended to
it. If there is no index, the index is assumed
 to be 1. The indices need not be monotonic
or sequential. Data written to this file is
defined with the FIELDS keyword below and
directed to the appropriate file using the
RECO keyword on the write statement. See
“WRITE” on page 653. Currently, DBF and
MDB are the only file formats supported for
this record file.
NOTE: Citilabs recommends producing
database files no larger than 2 GB, the
largest size that Cube Voyager and Cube
Base can properly process.

RECO CFORM |I| Length of field for all character variables that
follow it on the statement, and do not have a
specific format associated with it. A later
occurrence of CFORM will reset the value
for character variables following it. The
allowed range is 1-255; the default is 15.

RECO EXCLUDERECI |S| Used to exclude selected fields when using

the RECI.ALLFIELDS include macro
described under FIELDS above.

RECO FIELDS |S| Defines the variable names to be written to

the output RECO file. These variables are
referenced as RO.name variables in the
script. If a RECO variable name matches a
variable in the RECI record, the RO.name
variable will take on the same value as the
matching RI.name variable each time a new
RECI record is read. All RO. variables (with
or without matching RI. variables) can be
modified in the script, the current variable
values are written to these fields in the
RECO DBF file when the WRITE statement
is executed. For RECO fields that have no
matching RECI fields, the field values are
NOT initialized when a new RECI record is
read. For RECO fields that are not assigned
a value in the script or do not have a
matching RI. variable, they will be left empty
in the output record. The include macro
RECI.ALLFIELDS can be specified on the
FIELDS list to indicate that all of the data
fields on the input RECI file are to be
included on this RECO output file. The RECI
fields will be inserted on the RECO file at the
location where this macro is found. Care
should be taken to ensure that the other
names in the FIELDS list do not conflict with
the names on the RECI file.
For backward compatibility to Voyager
version 3.2, the RO. prefix of the RECO
variable name can be omitted when
referencing the variable in the script if the
variable has no matching RECI variable
and it is not referenced with the RO. prefix
anywhere in the script (a 3.2 script would
never have an RO. Prefix in the first place).
However, it is strongly recommended that
the RO. prefix be used at all times to avoid
confusion.

RECO FORM |R| Format specification (w.d) for all numeric

 variables that follow it on the statement, and
that do not have a variable- specific format.
A later occurrence of FORM will reset the
value for numeric variables following it. The
maximum value of w (the field width) is 20
and the maximum value for d (digits after the
decimal) is 9— but d must be at least 2 less
than w; the default is 10.2.
NOTE: Variable-specific formats can
specify larger values of d— up to 18, but d
must still be at least 2 less than w.

R E CO N A ME |S| Optional. Used in conjunction with the

FIELDS subkeyword.

RECO REPORT |?| Can be specified to have the program print

a listing of the fields (name, mode, length,
decimals) as they will appear in the DBF.
Default value is F.

R E CO Z |S| Optional. Used in conjunction with the

FIELDS subkeyword. Required when writing
MO or MD matrices.
Matrix Program > Control statements > FILEO > Example: FILEO

Exam ple: FILEO

These statements demonstrate FILEO.

RUN PGM=MATRIX
FILEI RECI = " LINK_DATA.DBF",SORT = -VULNERABIL
FILEO RECO[1] = "PRESCEENED_LINKS.DBF", FIELDS=A,B,rank_bas
NUMLINKS=RECI.NUMRECORDS ; number of records (links) in the input file
LOG PREFIX=CNT VAR=NUMLINKS ; writes the number of links to CNT.NUMLINKS
; in the *.var file
; PrescreenType and PRESCREEN value set in SM with KEYS
IF ({PrescreenType}=1) ; screen based on a fixed number of links
; (i.e., top N based on Vulnerability)
PRESCREEN={PRESCREEN}
ELSE ; screen based on a percentage of number of links
; in the input network (i.e., top N% of links based
; on Vulnerability)
PRESCREEN=ROUND(NUMLINKS*{PRESCREEN}/100)
ENDIF
LOG PREFIX=CNT VAR=PRESCREEN
RO.RANK_BAS=RO.rank_bas+1
Anode=RI.A
Bnode=RI.B
If (RO.rank_bas<=PRESCREEN)
If (Anode <={Zones} | Bnode <= {Zones}) ; prevents any centroid links
; from being included in set
; of links to be analyzed
RO.rank_bas=RO.rank_bas-1
Else
WRITE RECO=1
EndIf
EndIf
ENDRUN
Matrix Program > Control statements > FILET

FILET
Programs : Distribution, Fratar, Matrix
Sets temporary file paths. Keywords include:
• PAT H

FILET is used to specify where various temporary files are to be written.

FILE T k e y wo rd

Ke y wo rd D e s c rip tio n

PATH |KS| Specifies the path(s) to the disk area where any
temporary files are to be written. When transposing is
required, the transposed matrices are written to a
temporary file and then recalled during stack
processing. Up to two files are required for this process.
The first file is the actual transposed data, and the
second file is an index to the data file. The index file
may not be necessary, and if it is, it will be relatively
small. It may speed retrieval somewhat if the two files
are on different physical drives. If there is a ram disk
installed, then the index file might fit on it. The index file
size will be zones * chunks * transposes * 4 bytes.
Chunks depends upon the amount of RAM that is
available for the transposing processing; it could be
none.
Assume a 1000 zone system, 20 matrices to be
transposed, and 2 Mb of RAM available. The actual
RAM requirement would be 1000 * 1000 * 20 * 4, or 80
Mb. The number of chunks would be 40 (80 Mb / 2 Mb).
The index file would require 800,000 bytes of RAM. The
amount required for the data would be something less
than 80 Mb, depending upon how well it compresses. In
most cases, the compressed data would require about
30 Mb.
The values for PATH are entered as standard
operating system paths. If PATH[1] is specified, and
PATH[2] is not, or vice-versa, the non-specified path is
set equal to the specified one. If neither is specified,
they both will default to the path in the environment
variable named TMP, or TEMP. The logic for
determining the appropriate path, and opening the files
is:
• If the PATH=' ', use current directory.
• If the PATH is specified, use the PATH.
• If not specified, and TMP is specified in the
Operating System environment, use the
TMP.setting. (Same logic for TEMP.)
• If the open fails, Fatal.
Matrix Program > Control statements > FILET > Example

Exam ple
PATH=' ' ; use current directory for both
PATH=..\,R: ; up a directory for data, drive R: for index
PATH=c:\ d ; root of c: for data, current directory on d: for index
Matrix Program > Control statements > FILLMW

FILLMW
Programs : Distribution, Fratar, Matrix
Fill work matrices. Keywords include:
• MW

This statement is used to speed up the process of filling matrices with values from other
matrices. Because of its structure, matrices can be very easily moved from input
matrices to work matrices or from work matrices to other work matrices. Multiple matrices
can be easily filled on one specification. The beginning MW target is the keyword and
the values are the matrices that are to be moved into the target matrices. After the first
value, the following values may be unqualified (they do not have to have MI.#. prefixed
to their names/numbers). This is also true for MW sources.
MI sources may have .T affixed to indicate that they shall be transposed (see Example 2
below).
Everything that can be done on a FILLMW statement can be accomplished by COMP
statements, but FILLMW sets up very fast moves in contrast to internal computational
solutions performed by COMP statements.
FILLMW k e y wo rd

Ke y wo rd D e s c rip tio n

MW |s| Specifies the matrices to be moved

directly from their source to the
destination work matrices named on the
keyword.
Matrix Program > Control statements > FILLMW > Example 1

Exam ple 1
; The following five statements all do the same thing

FILLMW MW[1]=mi.1.1(3)
FILLMW MW[1]=mi.1.1,mi.1.2,mi.1.3
FILLMW MW[1]=mi.1.time,mi.1.distance,mi.1.cost
FILLMW MW[1]=mi.1.1,2,3
FILLMW MW[1]=mi.1.time,distance,cost

; The next two statements illustrate the simplicity of FILLMW vs. COMP
FILLMW MW[11]=mw[1],2,3,9,6
COMP MW[11]=mw[1], mw[12]=mw[2], mw[13]=mw[3], mw[14]=mw[9], mw[15]=mw[6]

; An example of multiple keywords

FILLMW MW[1]=mi.1.1,2,3, MW[4]=mi.2.2,3,4
FILLMW MW[101]=mi.1.1(5), MW[1](3)
;will fill MW[101-108] with MI.1.1-5,MW[1,2,3]
Matrix Program > Control statements > FILLMW > Example 2

Exam ple 2
;--- FILLMW using transposed inputs

RUN PGM=MATRIX
MATI=TEST_FILLMW.MAT
MATO=TEST_FILLMW_2.MAT MO=1-2, 11-12

FILLMW MW[1]=MI.1.1(2) ; write the original matrices

FILLMW MW[11]=MI.1.1.T, 2.T ; write transposed matrices 1 & 2
FILLMW MW[21]=MI.2.1.T(5) ;write transposed matrices 1 - 5

ENDRUN
Matrix Program > Control statements > FREQUENCY

FREQUENCY
Program: Distribution, Fratar, Matrix
Stratifies one matrix’s values based upon the values of another. Keywords include:
• B A S E MW

• R A N GE

• R E P OR T

• T IT LE

• V A LU E MW

Use FREQUENCY to obtain a frequency of occurrence of the values of a work matrix. A

typical use is for a trip length distribution, where the number of trips in a matrix is stratified
according to the times from a time or distance matrix. The final results are reported at the
end of all zone processing.
FR E QU E N CY k e y wo rd s

Ke y wo rd D e s c rip tio n

BASEMW |I| Work matrix number ( MW[ ] ) whose

values will be used for the stratification
(the time matrix for a trip length
distribution).

RANGE |RP| Set of two, or three, numbers that

establishes the valid values for
stratification. The numbers are separated
by a dash. The first number (RANGE[1]) is
the lowest value for which there is to be a
stratification. The second number
(RANGE[2]) is the highest value for
stratification. The third, optional, number
(RANGE[3]) is an increment for
stratification. If there is no increment, the
default will be 1. During accumulation, if
the value from BASEMW is less than
RANGE[1], or higher than RANGE[2], the
value from VALUEMW is accumulated
into an out-of-range bucket.

REPORT IP| Iterations for which the report will be

printed. If this keyword is not specified, or
if any of the values exceed the last
iteration, the report will be printed for the
last iteration. REPORT is used primarily
only when the Matrix program is invoked
as a process that runs in a multiple
iteration mode (Distribution program).

TITLE |S| Title for identifying the final report at the

end of the application.

VALUEMW |I| Work matrix number ( MW[ ] ) whose

values will be accumulated according to
the values of BASEMW (the trip matrix for
a trip length distribution).
Matrix Program > Control statements > FREQUENCY > Example

Exam ple
FREQUENCY BASEMW=1,VALUEMW=2,RANGE=1-100,
TITLE='Work Trips vs. Minutes'
FREQUENCY BASEMW=1,VALUEMW=2,RANGE=0-100-0.5, REPORT=99
Matrix Program > Control statements > GOTO

GOTO
Program: Distribution, Fratar, Generation, Matrix
Use GOTO to jump to statement named :label.
When GOTO is processed, flow immediately branches to the statement named label.
Label can be within IF and LOOP blocks; but care should be taken if this is to be done.
label is a character string that must have a matching LABEL statement. The leading colon
”:” is removed from label when determining the qualified name of the statement to
branch to.

NOTE: The placement of a :label inside a JLOOP is not allowed. This prevents using
GOTO from jumping into a JLOOP. A GOTO may be used inside a JLOOP to jump to a
:label that is outside the JLOOP but not to one that is inside the JLOOP.
Matrix Program > Control statements > GOTO > Example

Exam ple
GOTO buildhwy
GOTO :buildhwy

A statement that begins with : is a label statement, that has meaning with only GOTO
statements. A label statement can be within IF and LOOP blocks; care should be taken if
this is done. The leading ”:” is ignored.
Matrix Program > Control statements > GOTO > Example

Exam ple
GOTO buildhwy
.
.
:buildhwy
IF (expression) GOTO :buildhwy ; It is permissible to go backwards.
Matrix Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF

IF ... ELSEIF ... ELSE ... ENDIF

Program: Distribution, Fratar, Generation, Matrix
IF (expression) ELSEIF (expression) ELSE (expression) ENDIF
IF/ENDIF blocks are used to determine if certain operations are to be performed. IF
blocks may be nested, but they may not overlap LOOP, JLOOP, or other IF blocks. If a
variable in the expression is MI.n.name, ZI.n.name, or MW[], the same rules for indexing
in a COMP statement are applied. MI.n.name or MW[] should realistically only be used
within a JLOOP.
For more information on IF syntax, see Chapter 3, “General Syntax” in this manual.
Lengthy IF expression solutions could be time consuming; it is suggested that they be
used judiciously. Although IF expressions can be quite powerful for zonal selection,
sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection
process (see the examples in this section).
The following control statements may be appended to a single IF statement:
BREAK CONTINUE COMP EXIT GOTO PRINT
Matrix Program > Control statements > IF ... ELSEIF ... ELSE ... ENDIF > Example

Exam ple
IF (time_to_bcd < 20) simple statement ;single IF with process
IF (expression) EXIT
IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) )
.
ELSEIF (loop_cntr > 10)
.
ELSEIF (loop_cntr > 5 && diff.time < 32)
.
ELSE
.
ENDIF
; The above IF example is rather esoteric,
; and probably can not be aided by a filter.
; The J selection could have been filtered, but that might have caused
; conflicts with the use of J in other parts of the expression.
; The following illustrates a more efficient process for using IF for
; lengthy zonal selections within JLOOPs
; ***** Inefficient *****
JLOOP
IF (I=i_ranges... && J=j_ranges...) statement
ENDJLOOP
; ***** More efficient *****
IF (I=i_ranges...)
JLOOP INCLUDE=j_ranges...
statement
ENDJLOOP
ENDIF
Matrix Program > Control statements > JLOOP ... ENDJLOOP

JLOOP ... ENDJLOOP

Programs : Distribution, Fratar, Generation, Matrix
Control a J loop for processing matrices. Keywords include:
• J

• E XCLU D E

• IN CLU D E

JLOOP ENDJLOOP blocks are used primarily to control computations on matrices that
a single COMP MW[]= can not properly control. A JLOOP block causes the program to
loop between the JLOOP statement and its ENDJLOOP varying J from Jbeg to Jend by
increments of Jinc. The logic for JLOOP and ENDJLOOP processing is:
• at JLOOP:
m
If J is specified, establish values for J, Jend, and Jinc.
m
Else set J=1, Jend=Zones, Jinc=1.
m
If (J < 1 or J > Zones or Jend <1 or Jend > Zones) fatal termination.
m
If (INCLUDE, and J fails INCLUDE) go to ENDJLOOP.
m
If (EXCLUDE, and J meets EXCLUDE) go to ENDJLOOP.
m
Next statement.

• at ENDJLOOP:
m
Add Jinc to J.
m
If (Jinc > 0 and J <= Jend) go to statement following JLOOP.
m
If (Jinc < 0 and J >= Jend) go to statement following JLOOP.
m
If (INCLUDE, and J fails INCLUDE) go to ENDJLOOP.
m
If (EXCLUDE, and J meets EXCLUDE) go to ENDLOOP.

All statements between the JLOOP and ENDJLOOP statements are processed with the
current value of J. JLOOP blocks may not be nested, and may not overlap other
JLOOP, LOOP or IF blocks. COMP MW[]= statements are processed only for the
current value of J. Only the following statements are valid within a JLOOP block:
BREAK CALL COMP CONTINUE EXIT
GOTO IF ELSEIF ELSE ENDIF
PRINT REPORT SET
NOTE: The placement of a :label inside a JLOOP is not allowed. This prevents using
GOTO from jumping into a JLOOP. A GOTO may be used inside a JLOOP to jump to a
:label that is outside the JLOOP but not to one that is inside the JLOOP.

J LOOP & E N D J LOOP k e y wo rd s a nd e xp re s s io ns

Ke y wo rd D e s c rip tio n

J |I| Sets Jbeg, Jend and Jinc.

EXCLUDE |I| Optional. List of origin zones that the

program will not process. If you
include this keyword, the program will
not process statements for these
zones, and instead skip to the next
zone.

INCLUDE |I| Optional. List of origin zones that the

program will process. If you include
this keyword, the program will only
process statements for these zones.

Jbeg Expression to initialize J; the value

may not be less than 1, nor greater
than Zones.

Jend Expression that establishes the Jend

for the loop; the value may not be
less than 1 nor greater than Zones. If
there is no Jend, Jend is set to Jbeg,
and Jinc is set to 1.

Jinc Expression that establishes the Jinc

for the loop. If Jinc is not specified,
Jinc is set to 1 or -1, depending upon
the direction from Jbeg to Jend.

If Jbeg is not specified, Jend and Jinc can not be, and the values 1,Zones,1 are used. If
Jend is not specified, Jinc can not be, and the values Jbeg and 1 are used. If Jinc is not
specified, it is set to 1 ( -1, if Jbeg > Jend). Because all these values can be
expressions, they must be separated by commas; if an expression contains any
commas, it must be enclosed within ().
Matrix Program > Control statements > JLOOP ... ENDJLOOP > Example

Exam ple
JLOOP J=I EXCLUDE=500-535 ;process only intra zonal values
. ; but exclude externals
ENDJLOOP
ROWSUM1 = 0 ROWSUM3=0
JLOOP ; get rowsums for matrices
ROWSUM1 = ROWSUM1 + MW[1]
ROWSUM3 = ROWSUM3 + MW[3]
ENDJLOOP
Matrix Program > Control statements > LOOP ... ENDLOOP

LOOP ... ENDLOOP

Programs : Distribution, Fratar, Generation, Matrix
Control a general variable loop. Keywords include:
• LV A R = Lbeg, Lend, Linc

LOOP ENDLOOP blocks are used to repeat of a series of statements. LOOP initializes
a variable; ENDLOOP compares the contents of the variable to another value, and
branches back to the statement following the LOOP statement if the comparison fails.
LOOP blocks may be nested; they may not overlap IF blocks. The process differs
considerably from JLOOP. The logic is as follows:
• at LOOP:
m
Initialize LVAR to Lbeg.
m
Proceed to next statement.

• at ENDLOOP:
m
If Lend not specified, jump to next statement.
m
Compute Lend.
m
If Linc not specified:
m
Set Linc to 1 or -1 (if Lbeg and Lend are constants, and Lbeg > Lend)
m
Else compute Linc.
m
Add Linc to LVAR.
m
Compare LVAR to Lend.
m
If (Linc > 0 and LVAR > Lend) jump to statement after ENDLOOP
m
If (Linc > 0 and LVAR <= Lend) jump to statement after LOOP
m
If (Linc < 0 and LVAR < Lend) jump to statement after ENDLOOP
m
If (Linc < 0 and LVAR >= Lend) jump to statement after LOOP

Because of the flexibility of this logic, unpredictable results and/or endless loops can
occur if care is not taken. This would only happen if the Lend and/or Linc values are
expressions that contain variables which could be altered during the loop. On the other
hand, the flexibility provides for powerful control. The loop will be processed at least one
time regardless of Lend and Linc values. Most uses will involve constants. Because
LVAR values can be expressions, Lbeg, Lend, and Linc must be separated by commas
(standard white space delimiting can not be interpreted properly).
 LOOP & E N D LOOP k e y wo rd s a nd e xp re s s io ns

Ke y wo rd D e s c rip tio n

LVAR Name of the loop control variable. LVAR is

not protected during the loop; computational,
program, and other LOOP statements can
alter its value. LVAR must be followed by
Lbeg, and optionally, Lend and Linc.

Lbeg Numeric expression to initialize LVAR.

Lend Numeric expression that LVAR is to be

compared with when the ENDLOOP
statement is processed. If it is not specified, it
is assumed no comparison is to be made
(rather meaningless loop).

Linc Numeric expression that is to be added to

LVAR before the ENDLOOP comparison is
made. If Linc is not specified, it will be set to 1
(-1 if Lbeg and Lend are both constants and
Lbeg < Lend; a backwards loop).
Matrix Program > Control statements > LOOP ... ENDLOOP > Example

Exam ple
LOOP iter=1,10 ; perform 10 iterations
.
ENDLOOP
LOOP xyz=abc*def,ghi+jkl,mno/pqr
LOOP abc=xyz,xyz+2,2 ; nested LOOP
ENDLOOP
ENDLOOP
LOOP jj=10,3,-2.5 ; 10, 7.5, 5.0
ENDLOOP
Matrix Program > Control statements > PARAMETERS

PARAMETERS
Program: Matrix
Sets general parameters. Keywords include:
• MA T V A LCA CH E

• MA XMW

• MA XS T R IN G

• T RAM

• ZON E MS G

• ZON E S

P A R A ME T E R S k e y wo rd s

Ke y wo rd D e s c rip tio n

MATVALCACHE |KI| Number of matrix rows to cache when

dealing with the MATVAL function.
Default value is 50. Each matval call
requires a direct access lookup on
the designated MATI. Each read of a
row for matval results in a matrix row
being read and stored for possible
later use. In general, the larger the
number, the more efficient matval is.
Each value requires (zones*8 + 4)
bytes of RAM. If too large a value is
used, the RAM for cache might come
from disk, which could possibly
hinder performance. The user might
have to experiment to determine the
best number of his application.

MAXMW |KI| Optional. Maximum index for work

matrices (MWs). Valid values range
from 1 to 999. Default value is 999.
Normally, you do not specify this
keyword and override default value.

MAXSTRING |KI| Establishes the maximum length for a

string variable’s value. The default is
100, but if it is desired to compute
longer strings, the value must be
defined. All string variables will have
this possible length.
The maximum is 32,000 characters.

TRAM |KI| Establishes the maximum amount of

memory that is to be used for
temporary storage when transposing
matrices. The program will request
the amount that it thinks will provide
the most efficient processing. The
amount of memory required to do the
transposing in one pass is (Zones *
 (Zones+1) * 8 * NumberTransposes)
bytes. However, allocating huge
amount of memory (greater than 1
GB) sometimes actually slow down
the process, so the default for TRAM
is the smaller of 500 MB, the one pass
memory requirement, and 80% of
available physical memory divided
by the number of processes (if
running DISTRIBUTEINTRASTEP). It is
specified in MB (1,000,000 bytes) and
the valid range is between 4 and 2000
(4 MB to 2 GB). The specified amount
is still subject to the 80% of available
physical memory restriction. This is to
prevent the program from using virtual
memory (temporary work space on
disk). The use of virtual memory will
significantly affact the efficiency for
the transposing process. Generally
there is no reason to specify memory
higher than the default but there are
times when it is necessary to lower
the TRAM setting so that there will
memory available memory for other
running processes. The TRAM
setting is per process, so if
DISTRIBUTEINTRASTEP is being
used, the main process and each
Cluster node will get the same setting.
Please note that using
DISTRIBUTEINTRASTEP in a MATRIX
program with a large number of
transpose processes may slow down
the process because each process
will have to create its own temporary
transposed matrix file, increasing the
demand for memory and disk access
many folds.

ZON E MS G |IK| Optional. Frequency with which the

program writes zonal timing
messages to the run monitor or
console.
Value corresponds to number of
zones. For example, with a value of 1,
the program writes a message for
every zone. With a value of 10, the
program writes a message for every
10 zones. With a value of 0, the
program writes no zonal messages.
Specify a larger value to reduce run
times.
Program writes to the run monitor
when initiated through Application
Manager or voyager.exe. The
program writes to the console when
initiated through runtpp.exe.
Valid values are greater than or
equal to zero. Default value is 1.

ZONES |KI| Establishes the number of zones to

process. If ZONES is not specified,
and the program has no other way to
identify the appropriate number of
zones, it will be set to 100. If there are
any input MATI statements
processed, the default value for
ZONES will be determined by the
highest value from any MATI.
Matrix Program > Control statements > PARAMETERS > Example

Exam ple
ZONES=3000
Matrix Program > Control statements > PRINT

PRINT
Programs : Distribution, Fratar, Generation, Matrix
Format and print a line of information. See “PRINT” on page 69 for details about the
standard Cube Voyager statement.
Matrix Program > Control statements > PRINT > Example

Exam ple
PRINT FORM=0 LIST=I,J,TOTAL(6.2CS) 'ABCDE'(6.3), FORM=LRCD,
LIST=N,JLOOP_J ;Note this line is a continuation
LIST= I(6) J(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001
PRINT FORM=6.0CDLR LIST=I,J,TOTAL1,TOTAL2 FILE=PRINTFIL.002
Matrix Program > Control statements > PRINTROW

PRINTROW
Program: Distribution, Fratar, Matrix
Prints row of matrices. See “PRINTROW” on page 77 for details about the standard
Cube Voyager statement.
Matrix Program > Control statements > PRINTROW > Example

Exam ple

Examples of output with various parameters follow:

pagewidth=80
mw[1]=j
mw[2]=j include=1-5,31-60,90-100 exclude=35,83
printrow mw=1-2,1 form=LRD title='form=LRD'
printrow mw=1-21 form=6D base1=y maxperline=10,
title='form=6D base1=y, maxperline=10'

Resulting Output:
J: I=1 PRINTROW MW[1] form=LRD Tot=5,050
1: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
27: 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
50: 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
73: 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
96: 96 97 98 99 100
J: I=1 PRINTROW MW[2] form=LRD Tot=2,390
1: 1 2 3 4 5 - - - - - -- - - - - - - - - - -- - - - - - - - - - 31 32
33: 33 34 - 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56
57: 57 58 59 60 -- - - - - - - - - - -- - - - - - - - - - -- - - - - - -
90: 90 91 92 93 94 95 96 97 98 99 100
J: I=1 PRINTROW MW[1] form=6D base1= Tot=5,050
1: 1 2 3 4 5 6 7 8 9 10
11: 11 12 13 14 15 16 17 18 19 20
21: 21 22 23 24 25 26 27 28 29 30
31: 31 32 33 34 35 36 37 38 39 40
41: 41 42 43 44 45 46 47 48 49 50
51: 51 52 53 54 55 56 57 58 59 60
61: 61 62 63 64 65 66 67 68 69 70
71: 71 72 73 74 75 76 77 78 79 80
81: 81 82 83 84 85 86 87 88 89 90
91: 91 92 93 94 95 96 97 98 99 100
J: I=1 PRINTROW MW[2] form=6D base1= Tot=2,390
1: 1 2 3 4 5 -- -- -- -- --
31: 31 32 33 34 -- 36 37 38 39 40
41: 41 42 43 44 45 46 47 48 49 50
51: 51 52 53 54 55 56 57 58 59 60
81: -- -- -- -- -- -- -- -- -- 90
91: 91 92 93 94 95 96 97 98 99 100
Matrix Program > Control statements > RENUMBER

RENUMBER
Programs : Fratar, Matrix
Renumbers (aggregate, split) zones for output matrices. Keywords include:
• FILE

• FILE S

• MIS S IN GZI

• MIS S IN GZO

• ZON E O

• ZON E S

RENUMBER causes the program to assign new zone numbers to all values in the output
matrices. This causes an extra layer of processing, because the matrices must be
saved, and then retrieved and combined after all normal processing is completed. Each
input zone must be assigned a new output zone number, and a pair of percentages
(ROWPCT and COLPCT) to indicate how the outgoing matrix zonal values are to be
allocated to the renumbered zones. These equivalencies are obtained from records in
the designated FILE. The records may have from one to four fields to specify the
renumbering. A semi-colon (;) terminates data on a record; anything following the ; is a
comment.
The standard fields are:

Fie ld D e s c rip tio n

IPZONE Input zone number

OPZONE Output zone number

ROWPCT Percentage of IPZONE’s values to be

assigned to OPZONE when renumbering the
IPZONE row

COLPCT Percentage of IPZONE’s values to be

assigned to OPZONE when renumbering the
IPZONE columns

If there is only one field, OPZONE is set to 0.

If there are less than three fields, ROWPCT and COLPCT are set to 100.
If there are three fields, COLPCT is set to ROWPCT.
ROWPCT and COLPCT may not exceed 327
An alternate record format for aggregating several zones into a single district:
 D e s c rip tio n

District Word that begins with the letter D (for traditional

DISTRICT). The word may be any length, but
the first character must be D.

OPZONE Output zone number; it MUST be followed by ”=”.

IPZONEs Remaining fields are the input zones that are

allocated 100% (ROWPCT and COLPCT) into
OPZONE. Two fields may be separated by a
dash (”-”) if the two are to form a range.

If the list of IPZONEs is large, and the length of the record would exceed 250 characters,
the record must be broken into several records. Each record must begin with the District
string, and may not terminate with a dash.
Matrix Program > Control statements > RENUMBER > Example

Exam ple

D 1=1-10,20-30 45,48, 58-60

D 1=100-110 200-210 300-305 410 415 500-515
Those two formats can be mixed in the same file to allow efficient specification of zonal
equivalencies.
An IPZONE may appear more than one time; usually the case when a zone is to be split
into several new zones. An OPZONE may appear more than one time, usually the case
when aggregating zones. The sum of all ROWPCTs and COLPCTs for each IPZONE
should each be 100; if not, a message is issued. Every IPZONE (1-IPzones) should be
fully allocated. An IPZONE of 0 means there is intentionally no IPZONE for the
OPZONE. An OPZONE of 0 means there is intentionally no OPZONE for the IPZONE.
There should be an OPZONE for every zone (1-OPZONES); if not, a message is
issued.
To accommodate this process, the normal output matrices are trapped, renumbered,
and saved, at the normal output phase. When all zones have been processed, the
saved matrices are retrieved in appropriate order, combined when necessary, and
written to the MATO files. The intermediate matrices are saved either in RAM (normal
format), or on disk files (compressed format). If saved on disk, there must be sufficient
disk space for both the intermediate rows, and the final output files. The process is
optimized to the extent possible; the use of the FILES and INRAM keywords could help
considerably in reducing running times.
R E N U MB E R k e y wo rd s

Ke y wo rd D e s c rip tio n

FILE |F| File that contains the zonal equivalencies.

FILE and ZONEO are mutually exclusive.
Only one of those two keywords can be
used at one time.

FILES |I| Number of temporary files to use to store

intermediate factored matrix rows, until
they can be sorted and combined in the
final stages of the application. The value
must be in the range 1-10, inclusive. If the
keyword is not specified, the program will
set the value to ZONES/100, but never
less than 1, nor greater than 10. The
number of files affects the running time
when the final matrices are being formed;
more files generally speeds up the final
stage. Ten files will normally reduce the
application time by a factor of about 20-35
per cent as compared to one file.

MISSINGZI |S| Single character (if a longer string is

 specified, only the first character is
processed) to indicate how to treat input
zones that are not fully allocated
(ROWPCT and COLPCT totals of 100).
The character may be F, W, or M, and if it
is none of these, or MISSINGZI is not
specified, it defaults to F. The meanings
are:
F — Fatal
W — Warning
M — Message only (no penalty
associated)

MISSINGZO |S| Indicator similar to MISSINGZI. It indicates

the level of error associated with gaps in
the OPZONE structure.

ZONEO |S| Alternate method of specifying zonal

equivalencies using an input zonal data
file. A typical value of ZONEO is an input
zonal attribute: ZI.**.***. In this convention,
the IPZONE is the current zone number
and the OPZONE is the specified input
zonal attribute, for example, district or TAZ
number. ZONEO and FILE are mutually
exclusive. Only one of those two
keywords can be used at one time.

ZONES |I| Designates the highest new zone number

and serves as an editor as the file records
are read, to ensure that each OPZONE
doesn’t exceed this value. If ZONES is not
designated, no edit is performed, and
ZONES is set to the highest OPZONE. A
check is made to ensure that there is an
OPZONE for all values: 1-ZONES; if there
are any gaps, a message is issued.
Matrix Program > Control statements > RENUMBER > Example[1]

Exam ple[1]
FILEI MATI=IN.MAT
FILEO MATO=OUT.MAT, MO=1
MW[1]=MI.1.1 ; must load values into MW[1], else OUT.MAT will be all zeros
; renumber OUT.MAT according to 2005ZON.EQ
RENUMBER FILE=2005ZON.EQ, MISSINGZI=M, MISSINGZO=W
Matrix Program > Control statements > RENUMBER > Example[2]

Exam ple[2]
FILEI MATI=IN.MAT,
ZDATI=ZDATIN.DAT, Z=#1, DIST=2
FILEO MATO=OUT.MAT, MO=1
MW[1]=MI.1.1 ; must load values into MW[1], else OUT.MAT will be all zeros
; renumber OUT.MAT according to ZDATIN.DAT
RENUMBER ZONEO=ZI.1.DIST
Matrix Program > Control statements > RENUMBER > Example[3]

Exam ple[3]
/* This is a two step process to show an example of using RENUMBER to split an
existing pair of trip tables for a new disaggregate zone system. A typical process
might be to split zones into fully nested sub zones in ArcView. This example
assumes such a spatial procedure has been preformed and the resulting dbf file has
the zonal area of both the parent zones and the new split zones. This first step
uses MATRIX to compute split factors based on the ratio of the new zone-to-old zone
area and writes out the zonal equivalency file for use in the subsequent renumbering
step.
*/
;STEP 1
RUN PGM=MATRIX
FILEI ZDATI[1] = TAZDATA1.DBF
; Data structure of TAZDATA1.DBF is:
;Z NEW_Z1 NEW_Z2 Z_AREA Z1_AREA Z2_AREA
;1 1 2 6.40 2.22 4.18
;2 3 4 6.42 3.18 3.24
;3 5 6 6.44 3.78 2.66
;4 7 8 6.46 2.58 3.88
;5 9 10 6.48 3.75 2.73
; . . .
PARAMETERS ZONES=2999
; establishes a split factor based on the new zone geography
; the split factor is the ratio of the area of the new zone to the area
; of its parent. This set up assumes all input zones are split into two output
zones
; and that the total area of the new zones is equal to the area of the parent zone.
SPLIT1=100*(ZI.1.Z1_AREA/ZI.1.Z_AREA)
SPLIT2=100-SPLIT1
; writes the split factors to the PRN file
PRINT LIST=SPLIT1,SPLIT2
; write the zonal equivalency file
PRINT LIST=I,ZI.1.NEW_Z1,SPLIT1,
FILE = EQUIV_1.DAT"
PRINT LIST=I,ZI.1.NEW_Z2,SPLIT2,
FILE = EQUIV_1.DAT"
; data structure of EQUIV_1.DAT is :
; 1.00 1.00 34.69
; 1.00 2.00 65.31
; 2.00 3.00 49.53
; 2.00 4.00 50.47
; 3.00 5.00 58.70
; 3.00 6.00 41.30
; 4.00 7.00 39.94
; 4.00 8.00 60.06
; 5.00 9.00 57.87
; 5.00 10.00 42.13
; . . .
ENDRUN
;STEP 2 – split input trip table to new zonal system
RUN PGM=MATRIX
FILEO MATO[1] = TRIPS2.MAT,
MO=1-2, NAME=AUTO, TRANSIT
FILEI MATI[1] = TRIPS1.MAT
mw[1]=mi.1.1 ; fill work matrix 1 with AUTO trips from input matrix 1
mw[2]=mi.1.2 ; fill work matrix 2 with TRANSIT trips from input matrix 2
RENUMBER,
FILE = EQUIV_1.DAT
; the zonal equivalency file has the fields IPZONE, OPZONE and ROWPCT
; the default when no COLPCT is specified is to set the COLPCT=ROWPCT.
; if different COLPCT factors are desired they would need to be specified in the
; fourth column of the file.
ENDRUN
Matrix Program > Control statements > REPORT

REPORT
Program: Matrix
Request reports and establish tracing. Keywords and sub-keywords include:
• MA R GIN R E C
m CFORM
m FILE
m FORM
m LIST
m PRINT

• MA R GIN S

• MA T S T A T

• T R A CE

• ZD A T
m DEC

R E P OR T k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

MARGINREC |K?| Switch that indicates that MARGIN

summary records for each zone are to
be written to the standard output and/or
a designated file. It differs from the
function of the MARGINS keyword. The
keywords that are subordinate to
MARGINREC are a subset of those
available on a standard Cube
Voyager PRINT control statement as
shown below. Variable values are
formatted to the zonal record; normally,
the variables are row and column
values obtained from the accumulation
of margin values for work matrices, but
any variable or literal string can be
specified.

MARGINREC CFORM |S| Format to use for any character data

items that appear after this keyword.

MARGINREC FILE |F| Specifies a file where the formatted list

is to be written. Only one FILE value is
allowed per each MARGINREC switch.
A separate file is written for each
MARGINREC FILE value. If names
conflict, the earlier files will be
overwritten.

MARGINREC FORM |S| Format to use for any numeric data

items that appear after this keyword.
MARGINREC LIST |KSV| Specifies the items (variables and/or
strings) that are to be formatted to the
print line. If it is desired to have an
explicit format for any item in the list,
there may be a format appended to
the it. Such a format is surrounded by
(); the format applies to only that item.
Example:
J ITEM1(6) ITEM2(8C) 'abcde'
'i='(8R) K(L)
The variables are normally a
character (R, C, or I) followed by a
number. R1 indicates the row total for
work matrix one; C2 indicates the
column total for work matrix two, and I4
is the intrazonal value for work matrix
four. Variables can be formed by
concatenating R, C, and I names with
an underscore '_' acting as the
concatenating character. Example:
R1_C1 is the sum of the row value and
the column value for the zone. I1_I2_I3
is the sum of the intrazonal values for
matrices one, two, and three.
Other variables can be inserted into
the record, but the most meaningful
one would be J. A record is written for
each zone (J=1,Zones), and J is the
zone variable that is used.

MARGINREC PRINT |?| Switch that indicates that the FILE

record is to also be written to the
standard printed output.

MARGINS |KIP| Requests that row and column totals

be accumulated and reported for the
specified MWs (work matrices). If, for
some reason, there is insufficient RAM
to accumulate all the totals, the
program will delete (and notify) some,
or all, of the requests as required.
Each MW report is listed in telephone
book style with empty zones being
omitted.
NOTE: MARGINS and MARGINREC
cause the program to accumulate
margin values for each zone for each
of the included matrices. If there is
insufficient RAM, margin accumulation
could be canceled for certain matrices.

MATSTAT |S3| Specifies desired matrices for which

statistical summaries will be formatted
and reported in the run print file. Valid
values are: MI, MO, and MW to
generate reports for input matrices,
output matrices and working matrices.

TRACE |K?| Controls the listing of the stack

statements as they are processed
(can be quite voluminous, so be
careful). Trace can be turned on and
off at any time, thus controlling the
 amount of output as desired. If a COMP
is traced, only the first five J values will
be reported.

ZDAT |?| Switch that indicates that the zonal data

arrays generated by any FILEI ZDATI
keywords are to be formatted and
reported.

ZDAT DEC |I| Sets the maximum number of decimal

places to be printed for any variable.
This one value applies to all variables
on all ZDATI statements.
Matrix Program > Control statements > REPORT > Example

Exam ple

These statements illustrate REPORT.

REPORT MARGINS=1-3,8 ; request margins summaries
REPORT TRACE=y ; turn stack tracing on
REPORT TRACE=n ; turn stack tracing off
MARGINREC=y LIST=J,R1,C1,R2,C2,R3_R4_C3_C4,R5_C5
MARGINREC=y LIST=J,' sum intras for 1-3=', I1_I2_I3,
FILE=r:\intras,print=y
REPORT MATSTAT=MW ; request statistical summaries for working matrices

Example MATSTAT REPORT:

Table 1 - Matrix Summary (625 cells)
----------- Sum ----------- ---- Cnt --- ----------- Ave ----------
ALL >0 <0 >0 <0 ALL >0 <0
MW[1] 16,455.14 16,455.14 -- 256 -- 26.32822 64.27789 --
MW[2] 9,923.04 9,923.04 -- 256 -- 15.87686 38.76187 --
MW[3] 978.99 978.99 -- 256 -- 1.56638 3.82418 --
MW[4] 27,357.17 27,357.17 -- 256 -- 43.77147 106.86395 --
Table 2 - Matrix Min/Max (625 cells)
---------- Minimum -------------- ------------ Maximum --------------
>0 @I-J <0 @I-J >0 @I-J <0 @I-J
MW[1] 2.5450 3-16 -- --- 1,007.71 13-13 -- ---
MW[2] 3.1050 3-16 -- --- 370.64 13-13 -- ---
MW[3] 0.1015 13-12 -- --- 39.65 1-1 -- ---
MW[4] 6.0145 3-16 -- --- 1,378.97 13-13 -- ---
Table 3 - Matrix Intrazonal Summary (625 cells)
---------- Sum ---------- ---- Cnt --- ----------- Ave ----------
ALL >0 <0 >0 <0 ALL >0 <0
MW[1] 3,059.99 3,059.99 -- 16 -- 4.895984 191.24937 --
MW[2] 1,629.70 1,629.70 -- 16 -- 2.607520 101.85625 --
MW[3] 178.27 178.27 -- 16 -- 0.285232 11.14187 --
MW[4] 4,867.96 4,867.96 -- 16 -- 7.788736 304.24750 --
Table 4 - Matrix Intrazonal Min/Max (625 cells)
---------- Minimum ------------- ------------ Maximum --------------
>0 @I-J <0 @I-J >0 @I-J <0 @I-J
MW[1] 4.82 3-3 -- --- 1,007.71 13-13 -- ---
MW[2] 6.09 12-12 -- --- 370.64 13-13 -- ---
MW[3] 0.12 5-5 -- --- 39.65 1-1 -- ---
MW[4] 18.74 7-7 -- --- 1,378.97 13-13 -- ---
Matrix Program > Control statements > SET

SET
Programs : Distribution, Fratar, Generation, Matrix
Stores numeric values into one, or more, variables. Keywords include:
• VAL

• VARS

Use SET to set any number of variables to some value. All variables are set to zero at the
beginning of the I-loop, and are then changed only by the user. Most changes are the
result of COMP statements. A COMP statement can accomplish all that SET does, but it is
not as efficient, and is somewhat wordier.
S E T k e y wo rd s

Ke y wo rd D e s c rip tio n

VAL |R| Numeric value that the VARS that follow will
be set to. VAL is initialized to zero when the
statement is started, and then reset as this
keyword is encountered. If there is no VAL,
the coded VARS are all set to zero.

VARS |S| List of variables that are to be set to the more

recent value of VAL obtained from this
statement. If a named VARS is an array
allocated by an ARRAY statement, the entire
array is set to the value of VAL.
Matrix Program > Control statements > SET > Example

Exam ple
SET VAL=0, VARS=TOT1,TOT2,COUNTER
COMP TOT1=0 TOT2=0 COUNTER=0 ; is the same as previous statement
SET VARS=TOT1 TOT2 COUNTER ; is also the same (VAL defaults to 0)
SET VAL=123 VARS=C123, VARS=TOT1, TOT2, TOT3 ; sets all to 123
ARRAY SUMS=50
SET VAL=100, VARS=SUMS ; sets all 50 cells of SUMS to 100
SET VARS=SUMS ; sets all 50 cells of SUMS to 0
Matrix Program > Control statements > SORT

SORT
Programs : Distribution, Fratar, Generation, Matrix
Sort user-defined arrays. Keywords include:
• ARRAY

• N U MR E CS

See “SORT” on page 81 for details about the standard Cube Voyager statement.
Matrix Program > Control statements > SORT > Example

Exam ple
ARRAY ZONENO=ZONES, HH=ZONES, INCOME=ZONES
.
.
ZONENO[I] = I
HH[I] = ZI.1.HH[I]
INCOME[I] = ZI.1.INCOME[I]
.
.
SORT ARRAY=-INCOME,-HH,ZONENO, NUMRECS=ZONES
LIST=’ Zone Income HHs’
JLOOP
PRINT FORM=8, LIST=ZONENO[J], INCOME[J], HH[J]
ENDJLOOP
Matrix Program > Control statements > WRITE

WRITE
Programs : Distribution, Fratar, Generation, Matrix
Output record data files to DBF format. Keywords include:
• R E CO

Use WRITE to specify the record files that are to be written at the end of each I zone.
W R IT E k e y wo rd

Ke y wo rd D e s c rip tio n

RECO |I| Number of the FILEO RECO[#] DBF file where

you want to direct this print output.
Matrix Program > Examples and FAQ

Examples and FAQ

This section contains examples that demonstrate the Matrix program, along with a link to
frequently asked questions.
• Example 1: Generate zonal data

• Example 2: Obtain I-J values

• Example 3: RECI/RECO processing

• Example 4: CHOICE command

• Example 5: DBI processing using JOINTODBI

• Example 6: DBI processing using AUTOARRAY

• Example 7: Simple logit model using XCHOICE

• Example 8: Cost-based nested logit model using XCHOICE

• Frequently asked questions

Matrix Program > Examples and FAQ > Example 1: Generate zonal data

Example 1: Generate zonal data

This sample program generates a zonal data file from input files. The resulting zonal file
will contain combined data from the input zonal data and a summary of trips to the zones
that are in the central business district.

RUN PGM=MATRIX

mati[1]=tripfile.mat
zdati[1]=socoecon.dat,z=#1, pop=#2, area=#3, income=#4, hh1=#5, hh2=#6, hh3=#7
zdati[2]=employ.dat, z=#1, gov=#2, retail=#3, other=#4
ARRAY pop=10, area=10 totemp=10, tothh=10 ; this is a 10 zone problem
area[i]=zi.1.area
totemp[i]=zi.2.gov + zi.2.retail + zi.2.other
tothh[i]=zi.1.hh1 + zi.1.hh2 + zi.1.hh3
jloop include=1-5,38,56-100,145-150 ;cbd zones
cbdtrips[j] = cbdtrips[j] + mi.1.tottrips[j]
endjloop
if (i==zones) ; at last zone
jloop ; write a file of zonal records
print file=newzdat.zda form=6 list=j(3) pop[j] area[j] totemp[j] tothh[j]
cbdtrips[j]
endjloop
endif

ENDRUN
Matrix Program > Examples and FAQ > Example 2: Obtain I-J values

Example 2: Obtain I-J values

This example program get I-J values for records with trip tours on them. The MATRIX
program processes the tours.dat file. For each leg of the tour, it looks up highway or
transit time based on the major mode for that journey. Mode 1 corresponds to highway,
transit otherwise.
The program will read each input record from the RECI file and do calculations as
specified. The MatVal function is used to randomly access any i-j value from any input
matrix.
The format is: MatVal( filenumber, tablenumber, i, j, failvalue)
The failvalue is returned if lookup fails (invalid filenumber, tablenumber, i, or j). This
script has been tested for validity, but has not been thoroughly tested for logical content.

RUN PGM=MATRIX

mati=hwytime.mat,trntime.mat
reci=tours.dat, org=23, dst=26

; there are 80 fields on the record, can be referenced by reci.nfield[#].

; Field 23 can also be referenced as ri.org, and field 26 as ri.dst
; setup array to store time values with max of 8 legs on each tour
array hwyt=8 trnt=8
set val=0, vars=hwyt trnt ; initialize output variables
; trips from org to dst
from=ri.org
leg=1
loop stops=32,42,5 ; flds 32,37,42
if (reci.nfield[stops] > 0)
; if main mode org-dst is hwy
if (reci.nfield[76] = 1)
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0)
endif
leg=leg+1
from=reci.nfield[stops]
endif
endloop
; from last stop to dst
if (reci.nfield[76] = 1) ; if main mode org-dst is hwy
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,ri.dst,0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,ri.dst,0)
endif
; trips from dst to org
from=ri.dst
leg=5
loop stops=47,57,5
if (reci.nfield[stops] > 0)
if (reci.nfield[77] = 1) ; if main mode dst-org is hwy
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0)
endif
leg=leg+1
from=reci.nfield[stops]
endif
endloop
; from last stop to org
if (reci.nfield[77] = 1) ; if main mode dst-org is hwy
; from file 1 table 1
hwyt[leg]=MatVal(1,1,from,ri.org,0)
else
; from file 2 table 1
trnt[leg]=MatVal(2,1,from,ri.org,0)
endif
; write out I/P record(RECI) and append highway and transit time values
print file=tourtime.dat, form=5 list=reci,
hwyt[1],hwyt[2],hwyt[3],hwyt[4],hwyt[5],hwyt[6],hwyt[7],hwyt[8],
trnt[1],trnt[2],trnt[3],trnt[4],trnt[5],trnt[6],trnt[7],trnt[8]
; compute totals of highway and transit time arrays
hwyt_tot=arraysum(hwyt)
trnt_tot=arraysum(trnt)

ENDRUN
Matrix Program > Examples and FAQ > Example 3: RECI/RECO processing

Example 3: RECI/RECO processing

This is an example of using RECI/RECO to process DBF data files.

RUN PGM=MATRIX

FILEI RECI = ZONES_2002.DBF

FILEO RECO[1] = ZONES_2002_NEW.DBF,
FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2),
EXCLUDERECI=HOUSEHOLDS
FILEO RECO[2] = ZONES_2010.DBF,
FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2),
POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(4.2),
EXCLUDERECI=HOUSEHOLDS
FILEO RECO[3] = ZONES_2020.DBF,
FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2),
POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(6.2),
POP_2020(8.0), HH_2020(8.0), HHsiz_2020(4.2), Pden_2020(6.2),
EXCLUDERECI=HOUSEHOLDS

; compute regional base year statistics

TotalHH=TotalHH+RECI.NFIELD[5]
TotalPop=TotalPop+RECI.NFIELD[6]
avgHHsize=TotalPop/TotalHH
; print regional base year statistics
if (I=0) ; check for end of file
PRINT LIST='Total Households = ',TotalHH
PRINT LIST='Total Population = ',TotalPop
PRINT LIST='Average Household size = ',avgHHsize
endif
; rename RECI field
RO.HH_2002=ri.HOUSEHOLDS
; calculate zonal average household size for base year
RO.HHsiz_2002=ri.POP_2002/HH_2002
; calculate zonal population density per/acre for base year
RO.Pden_2002=ri.POP_2002/(ri.AREA/43560)
; factor base year data for 2010
RO.HH_2010=HH_2002*1.2
RO.POP_2010=RECI.NFIELD[6]*1.4
RO.HHsiz_2010=POP_2010/HH_2010
RO.Pden_2010=POP_2010/(ri.AREA/43560)
; factor base year data for 2020
RO.HH_2020=HH_2002*1.5
RO.POP_2020=RECI.NFIELD[6]*1.8
RO.HHsiz_2020=POP_2020/HH_2020
RO.Pden_2020=POP_2020/(ri.AREA/43560)

; write data to defined output files

WRITE RECO=1,2,3

ENDRUN
Matrix Program > Examples and FAQ > Example 4: CHOICE command

Example 4: CHOICE command

This example uses the CHOICE command in MATRIX to estimate a singly-constrained
gravity model, constrained on production trip ends.

RUN PGM=MATRIX

FILEO MATO[1] = "C:\CUBETOWN\MODEL\MODELS\SINGLEPRODDIST.MAT" MO=1 NAME=HBW

FILEI ZDATI[1] = "{SCENARIO_DIR}\TRIPENDS.DBF"
FILEI MATI[1] = "{SCENARIO_DIR}\CURRENTCOSTS.MAT"

;The general approach for a singly constrained in Voyager is to use the

;MATRIX program and the CHOICE command to implement a destination choice
;model.
;If you require a gamma curve deterrence function rather than the negative
exponential,you need to specify the appropriate calculations yourself.
;This example gives a ”destination choice” model constrained on production trip
ends.
CHOICE ALTERNATIVES=all1, DEMAND=ZI.1.P1, COSTS=mi.1.1,
ODEMAND=1, STARTMW=99,
DESTSPLIT = TOTAL 0.2 all1

;To apply singly constrained on attractions;

;- transpose the cost matrix, saving it to output file
;- run MATRIX, reading the transposed costs, reversing your use of the
; production and attraction data (i.e., TOTAL=ZI.1.A[1] etc)
; to implement a destination choice, with attraction totals as the single
constraint.
;- transpose the resulting matrix to correct orientation.

ENDRUN
Matrix Program > Examples and FAQ > Example 5: DBI processing using JOINTODBI

Example 5: DBI processing using JOINTODBI

This example uses DBI processing to combine two fields from different tables into a new
table, using the JOINTTODBI functionality. The inputs and output are stored in an MDB
file.

RUN PGM=MATRIX

FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta2",

FIELDS=ZONE_ ALFA BETA
FILEI DBI[2] = "DBI_Examples.mdb\BETA",
SORT=ZONE_ JOINTODBI=1 JOINTOFIELDS=ZONE_
FILEI DBI[1] = "DBI_Examples.mdb\ALFA"

ZONES=1

LOOP k=1,DBI.1.NUMRECORDS
x=DBIReadRecord(1,k)
RO.ZONE_=DI.1.ZONE_
RO.ALFA=DI.1.ALFA
RO.BETA=DI.2.BETA

WRITE RECO=1
ENDLOOP

ENDRUN
Matrix Program > Examples and FAQ > Example 6: DBI processing using AUTOARRAY

Example 6: DBI processing using AUTOARRAY

This example performs the same function as Example 5: DBI processing using
JOINTODBI. This time, the AUTOARRAY functionality accomplishes the task.

RUN PGM=MATRIX

FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta3",

FIELDS = ZONE_ ALFA(10.4) BETA(10.4)
FILEI DBI[2] = "DBI_Examples.mdb\BETA",
AUTOARRAY=BETA
FILEI DBI[1] = "DBI_Examples.mdb\ALFA",
AUTOARRAY=ALFA

ZONES = 1

LOOP L3=1,DBI.1.NUMRECORDS,1
RO.ZONE_ = L3
RO.ALFA = DBA.1.ALFA[L3]
RO.BETA = DBA.2.BETA[L3]
WRITE RECO = 1
ENDLOOP

ENDRUN
Matrix Program > Examples and FAQ > Example 7: Simple logit model using XCHOICE

Example 7: Simple logit model using XCHOICE

This model uses XCHOICE to implement a simple logit model, where demand is
allocated between car and bus trips.

RUN PGM=MATRIX MSG='Absolute XChoice'

FILEI MATI[1] = ".\Inputs\COSTCAR.MAT"

FILEI MATI[2] = ".\Inputs\COSTPTBUS.MAT"
FILEI MATI[3] = ".\Inputs\ALLDEMAND.MAT"

FILEO MATO[1] = ".\ABSOLUTE_OD.MAT", MO=15-16

MW[1] = MI.3.1

MW[3] = MI.1.1
MW[4] = MI.2.1

; Absolute logit model

XCHOICE,
; List choices
ALTERNATIVES = car, bus,
; Input total demand
DEMANDMW = 1,
; Input costs
COSTSMW = 3, 4,
; Forecast demand
ODEMANDMW = 15,16,
; Model structure
SPLIT = TOTAL 0.02 car bus,
; Forecast composite cost
SPLITCOMP = 19,
; Working matrices
STARTMW = 30

ENDRUN
Matrix Program > Examples and FAQ > Example 8: Cost-based nested logit model using XCHOICE

Example 8: Cost-based nested logit model using

XCHOICE
This example employs XCHOICE to implement a hierarchical logit choice model. The
top-level options are car and public transportation, with bus and rail as options within
public transport.

RUN PGM=MATRIX MSG='Cost Based Nested XChoice'

FILEI MATI[4] = ".\Inputs\AllDemand.mat"

FILEI MATI[3] = ".\Inputs\CostPTrail.mat"
FILEI MATI[1] = ".\Inputs\COSTCAR.MAT"
FILEI MATI[2] = ".\Inputs\COSTPTBUS.MAT"

FILEO MATO[1] = ".\Nested_OD.MAT", MO=14-16

MW[1] = MI.4.1

MW[4] = MI.1.1
MW[5] = MI.2.1
MW[6] = MI.3.1

; Absolute hierarchical logit model

; Specify scale parameters
lambda = 0.02
mu = 0.03

XCHOICE,
; List choices
ALTERNATIVES = car bus rail,
; Input demand
DEMAND = 1,
; Input costs
COSTSMW = 4, 5, 6,
; Forecast demand
ODEMANDMW = 14,15,16,
; Model Structure
; Top level nest
SPLIT = TOTAL lambda car pt,
; Forecast composite cost top level
SPLITCOMP = 19,
; PT nest
SPLIT = PT mu bus rail,
; Forecast composite cost PT level
SPLITCOMP = 20,
; Working matrices
STARTMW =70

ENDRUN
Matrix Program > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see Matrix & Distribution in Chapter 17, “Frequently Asked Questions.”
Distribution Program > Introduction to the Distribution program

Introduction to the Distribution program

This section introduces you to the Distribution program. Topics include:
• Overview

• Convergence: Iteration control

• Multiple purposes

• Referencing productions and attractions

• Travel function values: Friction factors

Distribution Program > Introduction to the Distribution program > Overview

Overview
Trip distribution is the process of estimating the number trips that will travel between all
the zones in the system. Usually the process uses the number of trip ends in each zone
as the starting point. These margin totals are distributed to the rows and column of a
generated matrix. Usually, additional information about some measure of travel between
each zone pair should be included in the process. The most commonly used distribution
process is the “gravity” model, but other processes are also employed. Cube Voyager
does not have any automatic, or default, trip distribution process. The Matrix program
provides a framework that allows the user to perform distribution in a variety of ways. In
some cases, the Matrix program does have some built-in functions that aid in the
implementation of the more popular distribution processes.
A gravity model distribution can be easily implemented within Matrix, but it does need
some help, and the user has to follow certain guidelines for proper implementation. A
brief illustration of a typical gravity distribution follows. The gravity model equation is:
TRIPi-j = Pi * Aj * func(Ti-j) / Sz=1..n (A * func(T)).
where:
P = the number of trip productions for a zone.
A = the number of trip attractions for a zone.
T = the travel impedance factor between zones.
i = the production zone.
j = the attraction zone.
z = any zone.
n = the number of zones.
In simple terms this states that the trip productions in zone I will be distributed to each
zone J according to the relative attractiveness of zone J. Each J’s attractiveness is
determined by the product of its attractions and some function of the spatial separation
between I and J. The sum of the these products for all Js (relative to I) is obtained and
often referred to as the accessibility index for I. Each J will then be given a prorata share
of the productions for I based upon its attractiveness relative to the accessibility index for
I.
The function of spatial separation (func(T)) is the indefinite portion of the equation. It is
believed to be best described by an expression of the form of e^bT, where b is the curve
factor, and T is the travel time. Experience has shown that often a single curve does not
suffice, and it difficult to estimate what b should be used. To facilitate application, most
gravity model processes use a lookup function to obtain empirical values for the function
based upon the impedance. These curves are usually called friction factor curves.
Numerous applications have shown that friction factor curves tend to follow the same
patterns for similar conditions. Many agencies share the same curves when their regions
are similar in nature.
To implement the gravity model in Matrix, several guidelines must be followed:
• There must be a set of Ps and As for each purpose to be estimated. They are established
by the presence of a SETPA control statement.

• A mechanism must be established to obtain the travel function. Usually, a level-of-service

matrix is used to obtain the zone-to-zone impedance for I-J, and the travel function value
(friction factor) is obtained by finding the impedance in a LOOKUP table.

• The gravity model equations must be executed in a specific order. At least three
expressions are required. One to compute attractiveness for each J, one to sum them to
form the accessibility index for I, and one to distribute the productions based upon the
values and the accessibility index. Obviously, these expressions must be executed in the
proper order.

As an alternative to complete user definition of the gravity formulation, the GRAVITY

control statements can be used to perform a built in process for a doubly constrained
GRAVITY model. This process is more efficient than complete formulation. A singly
constrained gravity model can be formulated as a destination-choice model with the
CHOICE control statement in Matrix. See “Examples and FAQ” on page 654 under the
Matrix program for an example of a singly constrained gravity model.
Distribution Program > Introduction to the Distribution program > Overview > Example 1

Exam ple 1
/* given:
The impedances are in the first matrix of file: IMP.MAT
The productions and attractions are in file: PA.ZDA
The friction factors are in file: FF.DAT
*/
FILEI MATI[1] = IMP.MAT,
ZDATI[1] = PA.ZDA,Z=#1,P1=#2,A1=#3
FILEO MATO[1] = OUT.MAT, MO=1
LOOKUP NAME=FF,LOOKUP[1]=#2,RESULT=#1,
FILE=FF.DAT, INTERPOLATE=Y
SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1
MW[1] = A[1] * FF(1,MI.1.1), PAF=P[1]/ROWSUM(1), MW[1]=PAF * MW[1]
GRAVITY PURPOSE=1, LOS=MI.1.1, FFACTORS=FF ; faster process
Distribution Program > Introduction to the Distribution program > Convergence: Iteration control

Convergence: Iteration control

The gravity model equation ensures that the correct number of trips will be distributed for
each I zone; the row (production zone) totals for each will always match the number Ps
for the zone. There is no method to guarantee that the correct column totals (number of
attractions) will be obtained for each J zone. In all likelihood, the estimated column
values will not match the desired number of As input for each zone. This problem is
alleviated by iterating the model. An iteration is a complete pass for all I zones. At the
end of each iteration, the estimated column totals are compared to the input As, and,
based upon the comparison, the process is repeated with an adjustment in the data.
The adjustment is based upon the closeness for each zone. The iteration process is
repeated until it is decided that the results are close enough, or that a maximum number
of iterations have been performed. Following is small example of this process:
Prior to the first iteration the desired totals are:
Zone 1 2 3 Total
1 -- -- -- 100
2 -- -- -- 200
3 -- -- -- 300
Total 240 200 160 600

There really is no matrix yet. The totals are the values as obtained from the SETPA
control statements. The model goal is to fill in the matrix with values so that the totals will
match the totals shown. The row totals shown are the Desired Ps for each zone, and the
column totals are the Desired As. A set of A values internally named Used are set equal
to the Desired values. An iteration is performed and the Estimated results appear as:
After Iteration 1:
Zone 1 2 3 Total
1 57 24 19 100
2 64 106 30 200
3 102 61 137 300
Total 223 191 186 600
Use2 258 210 138

As dictated by the formulation, the row totals are correct. But, the Estimated column
totals do not quite match the Desired. The As for each zone are adjusted by a factor that
is computed as: Desired * Used / Estimated. Another iteration is performed, and the
results appear as:
After Iteration 2:
Zone 1 2 3 Total
1 60 24 16 100
2 67 108 25 200
3 113 66 121 300
Total 240 198 162 600
Use3 258 212 136

The Estimated column totals are still not exactly what is desired, so adjustments are
made to the used As, and another iteration is performed.
After Iteration 3:
Zone 1 2 3 Total
1 60 24 16 100
2 66 109 25 200
3 114 67 119 300
Total 240 200 160 600

Now the Estimated totals and the Desired totals match for all zones. The model is
completed. Further iterations would be useless; nothing would change.
In the real world, with many zones, it is not likely that all the Estimated totals would match
exactly with the Desired totals. As a matter of fact, in this simple three zone problem, the
totals did not match exactly (there were some slight differences in the decimal places).
But, the floating point values were close enough to be accepted as having matched.
How does the program decide when it should stop? There are two parameters that can
be used for controlling cutoff: MAXITERS and MAXRMSE.
MAXITERS specifies that no more than a specified number of iterations are to be
performed. The default is MAXITERS=3; this is usually sufficient for most gravity model
applications. Additionally, the program computes the root mean square error of the
differences in Estimated vs. Desired attractions (sqrt (Sum(diff^2) / (n-1)). If the
computed RMSE is less than MAXRMSE, a completion flag is set. The default is
MAXRMSE=10, but that may not always be a good choice for certain applications. In
the sample three zone problem the RMSEs for each iteration were computed as: 22.78,
2.08, and 0.26. The final value of 0.26 indicates that there were still some slight
differences in the Estimated and Desired, but as noted above, they were insignificant. If
the default MAXRMSE value had been used, the process would have cutoff after two
iterations.
Distribution Program > Introduction to the Distribution program > Multiple purposes

Multiple purposes
Usually a given application will consist of more than one purpose. Traditionally, at least
three internal purposes are estimated, with the most commonly used purposes being:
Home Based Work (HBW), Home Based Other (HBO), and Non Home Based (NHB).
There are other popular purpose stratification, but these are the most commonly used.
Often Internal-External and External-Internal and truck and taxi purposes are also
estimated; some analysts prefer to estimate them in a separate application, and some
prefer to do them all at once. With the Cube Voyager process, all the purposes can be
estimated in one application because the user has the ability to specify different gravity
equations for each of the purposes. Each purpose can have its own impedance matrix
and different formulation (functions, expressions, friction factors, etc.). The Ps and As
and lookup functions can be obtained from different sources.
There is one caveat: If convergence has not been reached for any purpose, and
MAXITERS has not been reached, another iteration will be processed with adjusted As
for all purposes. That is no concern; the results will not get worse. The MAXRMSE
parameter applies to the highest RMSE of all purposes. MATO files are written only on
the last iteration. If the iteration number is equal to the PARAMETERS MAXITERS
value, the program knows when the last iteration is being processed. But, convergence
could be obtained at some lower iteration. In that case the program will perform another
iteration, similar to the one just completed, but this time writing the MATO files. In other
words, if convergence is reached before MAXITERS, an additional iteration will be
performed in order to obtain the matrices. The use of PARAMETERS MATOEVERY will
preclude an additional iteration, but at the cost of additional time to write matrices during
each iteration.
The number of purposes is determined by the highest P[] or A[] index established via
the SETPA control statement. The program assumes that there will be purposes from
one, monotonically, through that highest index. Other COMP MW[]= statements may be
specified, but they will not be involved in any internal purpose editing. If the estimates
follow the same formulation, the set up is only slightly different from what is depicted,
above. Example 2 illustrates a typical setup for a three purpose application.
Distribution Program > Introduction to the Distribution program > Multiple purposes > Example 2: Three purpose - same P/A
and FF file for all purposes

Exam ple 2: Three purpo se - sam e P/A and FF file fo r all purpo ses
LOOKUP FILE=FF.DAT, INTERPOLATE=Y, NAME=FF,
LOOKUP[1]=1,RESULT=2,
LOOKUP[2]=1,RESULT=3,
LOOKUP[3]=1,RESULT=4
SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1,
P[2]=ZI.1.P2, A[2]=ZI.1.A2,
P[3]=ZI.1.P3, A[3]=ZI.1.A3
LOOP PURP=1,3
MW[PURP] = A[PURP] * FF(PURP,MI.1.1)
PAF=P[PURP]/ROWSUM(PURP)
MW[PURP]=PAF*MW[PURP]
ENDLOOP

In Example 3, purposes 1-3 are the same as in Example 2, and two internal-external
purposes (with entirely different formulation) are to also be included. Purpose 4 uses an
equation for distribution, and purpose 5 uses a simple lookup curve, with only three
points in it.
Distribution Program > Introduction to the Distribution program > Multiple purposes > Example 3

Exam ple 3
LOOKUP FILE=FF.DAT, INTERPOLATE=Y, FAIL=12000,1,0, NAME=FF,
LOOKUP[1]=1,RESULT=2,
LOOKUP[2]=1,RESULT=3,
LOOKUP[3]=1,RESULT=4
LOOKUP NAME=XIFF, FAIL=500,100,
R= '500 1-20', ; read the data directly
'400 20-30',
'300 30-40',
'200 40-50'
SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1,
P[2]=ZI.1.P2, A[2]=ZI.1.A2,
P[3]=ZI.1.P3, A[3]=ZI.1.A3
SETPA P[4]=ZI.2.PI, A[4]=ZI.3.STACNT_OB,
P[5]=ZI.2.AI, A[5]=ZI.3.STACNT_IB
LOOP PURP=1,3
IF (PURP <= 3)
MW[PURP] = A[PURP] * FF(PURP,MI.1.1)
ELSEIF (PURP==4)
JLOOP INCLUDE=1-500
IMP = MI.2.IMPEDNACE
IF (MI.2.DISTANCE < 3) IMP = MI.2.SHORTIMP
MW[4] = A[4]*EXP(-B * IMP)
ENDJLOOP
ELSE
MW[5] = A[5] * XIFF(MI.2.IMPEDANCE) INCLUDE=501-535
ENDIF
PAF=P[PURP] / ROWSUM(PURP),
MW[PURP]=PAF*MW[PURP]
ENDLOOP

Of course, there are different ways that this distribution could have been written. Most
likely, the purpose 4 and 5 Ps and As would not sum to the same total because they
were derived from separate sources. If there is a difference in the totals for a purpose,
the program issues a message and adjusts the As to match the P total. Differences in
the totals would preclude convergence via RMSE calculations because there would
always be differences.
Distribution Program > Introduction to the Distribution program > Referencing productions and attractions

Referencing productions and attractions

Productions and attractions are referenced by using array notation for P and A. P and A
are doubly dimensioned arrays, where the first index references the purpose number,
and the second index references the zone number. Since most users may not wish to
always code a zone index (it is more intuitive to reference the arrays with just purpose
number), the zone index need not be supplied; it will be automatically provided.
However, the zone index has different meanings for P and A. For P, the default zone
index is I and for A, it is J. If a different index is required, it may be explicitly provided.
Most times an invalid index will cause a fatal termination. Purpose 0 and Zone 0 are
valid, but may not always be predictable. Zone 0 should always contain the total for the
purpose. The lower bounds for both indices are zero, and the upper bounds are
“number of purposes” and zones, respectively.
P and A are protected variables; they may not be the result of COMP expressions,
except on SETPA statements.
Distribution Program > Introduction to the Distribution program > Travel function values: Friction factors

Travel function values: Friction factors

If friction factors are to be used in the distribution process, they are normally input to the
program from an external lookup file. The lookup file is usually formatted as a series of
curves – one curve for each trip purpose. The curves are organized vertically on the
records of the file. A typical file would appear as:
1 9000 8000 7000
2 8000 7000 6000
3 7000 6300 5200
:
:
50 1 1 1
51 0 0 0

This file would be described with a LOOKUP statement such as:

LOOKUP FILE=FF_FILE, NAME=FF,
LOOKUP[1]=1, RESULT=2,
LOOKUP[2]=1. RESULT=3,
LOOKUP[3]=1, RESULT=4

This statement indicates that the first four values from each record will be used. Field 1
will be the travel time value, and fields 2, 3, and 4 are the values for purpose 1, 2, and 3,
respectively. The friction factor for purpose 1 for 1 minute would be 9000, and the friction
factor for purpose 2 would be 8000. The friction factor for purpose 1 for a time value of
1.5 could be either 9000 or 8500, depending upon the options specified on the
LOOKUP statement. If SETUPPER=T is specified, the friction factor will be 9000, and if
SETUPPER=F and INTERPOLATE=T, the friction will be 8500. This capability allows
for compatibility with other model systems.
In this example, a time value of 0.5 will result in the value 9000, because there is no
explicit FAIL[1] specified. The friction for any value greater than 51 will be 0; no
distribution. If the record for 51 were not in the file, the friction factor for any time greater
than 50 would be 1. However, if FAIL[2]=0 were used, any time greater than 50 would
be 0. It is recommended that a final value of 0 be used to preclude distribution to zones
where the I-J time exceeds a certain value. This can also be controlled by use of the
LOSRANGE keyword on the GRAVITY statement.
Distribution Program > Control statements

Control statements
Most of the standard Matrix program statements are valid in the Distribution program,
and a few additional ones are available.
Since the Distribution program is a subset of the Matrix program, it is assumed that the
user is familiar with the Matrix-program control statement set. Only the differences
between the Matrix and Distribution control statements are included in this section. For
descriptions of other control statements see “Control statements” on page 545 under the
Matrix program.
Matrix program statements no t allowed in the Distribution program:
• RENUMBER

Distribution program statements no t in the Matrix program:

• SETPA

• GRAVITY

Distribution program keywords no t in the Matrix program:

• PARAMETERS MAXITERS = MAXRMSE=

• REPORT ACOMP=
Distribution Program > Control statements > GRAVITY

GRAVITY
Performs a standard gravity model. Keywords include:
• FFA CT OR S

• KFA CT OR S

• LOS

• LOS R A N GE

• P U R P OS E

This statement is used to have the program compute a distribution based upon
traditional gravity model formulation for a single purpose. It is more efficient than using
multiple COMP statements to formulate the same process.
GR A V IT Y k e y wo rd s

Ke y wo rd D e s c rip tio n

FFACTORS |SN| Specifies the expression that results in

the friction factor that a gravity equation
expects. Normally, this would be the
name of the lookup table that contains
the friction factors that correspond to the
values that are to be extracted from LOS.
In this statement, no arguments should be
used with the lookup name. The lookup
table is expected to be in the form shown
in the Examples. The lookup arguments
will be automatically set to the value from
the LOS matrix and the PURPOSE
number. See “LOOKUP” on page 57 for
hints about using Lookups to obtain
friction factors.

KFACTORS |S| Specifies the matrix that contains the K-

factor values for each I-J distribution. The
value MUST be either a MW[#] or an
MI.#.name/#.

LOS |S| Specifies the matrix that contains the

level-of-service values for each I-J
distribution. The value MUST be either a
MW[#] or an MI.#.name/#.

LOSRANGE [R] Optional. Specifies the range of LOS

values that are valid for use in the
distribution process. If an I-J values is
less than the first value or greater than the
second value, there will be no distribution
between for I-J. This keyword must be
followed by a pair of numbers separated
by a dash. The first number must be 0, or
greater, and the second value must be
greater than the first. Default range is
0 ‑ 999999.
PURPOSE |I| Specifies which purpose this is
calculation to: the results will be stored in
MW[PURPOSE].

PURPOSE, LOS, and FFACTORS must be specified.

Distribution Program > Control statements > GRAVITY > Example

Exam ple
lookup fail=12000,1,0, list=n, file=tstff1, name=ff,
lookup[1]=1,result=2,
lookup[2]=1,result=3,
lookup[3]=1,result=4,
lookup[4]=1,result=5,
lookup[5]=1,result=6,
interpolate=y,setupper=n
gravity purpose=1, los=mw[11], ffactors=ff
gravity purpose=2, los=mw[11], ffactors=ff, losrange=11-48
gravity purpose=3, los=mw[11], ffactors=ff
gravity purpose=4, los=mw[11], ffactors=ff
gravity purpose=5, los=mw[11], ffactors=ff, Kfactors=MI.1.K5
Distribution Program > Control statements > PARAMETERS

PARAMETERS
Sets general parameters. Keywords include:
• MA T OE V E R Y

• MA XIT E R S

• MA XR MS E

• ZON E S

In addition to the standard Matrix-program parameters, the parameters described here

may also be specified.
P A R A ME T E R S k e y wo rd

Ke y wo rd D e s c rip tio n

MATOEVERY |K?| Switch that can be used to force the

program to write output matrices for every
iteration, instead of waiting until the last
iteration. This causes the program to run
somewhat longer for each iteration, but
may preclude the program from having to
run another iteration to obtain the output
matrices once convergence is reached.
Since the program does not know that a
particular iteration will be the final one
until after it completes the iteration, it
normally does not write matrices for the
iteration. This saves a considerable
amount of computer time for larger
systems. But, it does force another
processing iteration to write the matrices
once it has determined that this is the last
iteration. If it is anticipated that there will
be many iterations to reach
convergence, it is probably better to set
this switch false. If it is anticipated that the
process will involve only a few iterations,
it is probably better to set this switch true.

MAXITERS |KI| Specifies the maximum number of

iterations to perform. If the MAXRMSE
criterion is met, the number of iterations
actually performed could be less than
this value. The default is 3, and the max is
99. If the model converges in fewer
iterations, one more iteration will be run
(with the same values as the converging
iteration) so that the MATO matrices will
be written.

MAXRMSE |KR| Specifies the cutoff criteria. If the highest

RMSE (for any purpose) exceeds this
value, automatic cutoff is not triggered.
Conversely, if all the purpose RMSEs are
less than this value, automatic cutoff is
triggered. The default is 10, and the
 minimum is 0.0001.

ZONES |KI| Specifies the highest zone number to

process. If the number of zones can not
be ascertained from the project file or
from any binary input matrices, ZONES
must be provided, or the value will default
to 100. If present, this value controls the
application. Normally, there will be an
input matrix file, so this keyword should
not be required.
Distribution Program > Control statements > REPORT

REPORT
Specifies Matrix program reports. Keywords and subkeywords include:
• A COMP
m ITERATIONS

R E P OR T k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ACOMP |KIP| Requests that the comparison of

Estimated vs. Desired attractions be
reported for the specified purposes. The
report is in a format that is similar the
MARGINS report. The values are
reported as nearest integers (without
decimal places). Only the purposes
specified by the keyword are reported. If
the values for ACOMP are followed by
ITERATIONS, then those ACOMP
purposes will be printed only during the
iterations specified. If there are no
ITERATIONS specified, the report will
be printed for every iteration (could be
quite voluminous). In ACOMP reports,
zero values are printed with – and a
printed value of “0” means there is a
fractional value present for the cell (the
fractions are not printed in the report).

ACOMP ITERATIONS |IP| Specifies the iterations for which the

prior ACOMP purposes reports are to
be printed. If no ITERATIONS follow
ACOMP values, the reports will be
printed for all iterations. If at least one
value is equal to, or exceeds, the
PARAMETERS MAXITERS, the reports
will be printed for the last iteration (no
matter how it is determined: parameter
or convergence).
Distribution Program > Control statements > REPORT > Example

Exam ple
REPORT ACOMP=1-3,5 ITERATIONS=5,10,99 ; specified purposes and iterations
REPORT ACOMP=6 ; for all iterations
Distribution Program > Control statements > SETPA

SETPA
Establishes base productions and attractions. Keywords include:
• A

• E XCLU D E

• IN CLU D E

• P

The SETPA statement is required; if it is not included, the program will fatally terminate.
The statement defines to the program how the desired productions and attractions are to
be obtained, and how many purposes are to be processed. There should be a P[]= and
A[]= expression for every purpose beginning with 1 and continuing, monotonically, until
all purposes are defined. The highest index encountered establishes the number of
purposes.
If there are any holes in the purpose scheme, the program will issue a warning
statement. The total of the As should match the total of the Ps for each purpose. If the
totals differ by more than five percent of the P total, a message is issued. If the totals
differ by any amount, the As are scaled so that the A total will match the P total.
The Ps and As are computed from the expressions that are supplied. In most cases, the
expression will simply point to a ZDATI file variable. Complex expressions are allowed,
but the use of any variables in the expression could cause unpredictable results. In a
purpose where the Ps and As are the same for each zone, (NonHomeBased is a typical
example), it is acceptable to set the Ps, and then set the As equal to the Ps. The
SETPA expressions are computed in the order in which they appear in the control
stream, and they are computed only one time -- prior to the first iteration. For each array,
the expression is solved in a loop of J=1-Zones, and the results are stored in the A[n][J]
or P[n][J] cells. A and P may not have a zone index in the SETPA statement.
If the same purpose is referenced more than one time (this is acceptable), the
subsequent values will replace the prior values. Duplication of purposes might be helpful
if values for different zones for a purpose are to be obtained from different sources, or if
different INCLUDE/EXCLUDE filters are to be used (separate SETPA statements must be
used for different filters).
S E T P A k e y wo rd s

Ke y wo rd D e s c rip tio n

A |NV| Expression that is solved to set the

attractions for the indexed purpose.

EXCLUDE |IP| Processed the same as EXCLUDE on

COMP statements. If it is used, the loop will
 not be processed for any zones in the list.
EXCLUDE filtering follows any INCLUDE
filtering.

INCLUDE |IP| Processed the same as INCLUDE on

COMP statements. If it is used, the loop will
not be processed for any zones not in the
list. INCLUDE filtering precedes any
EXCLUDE zones.

P |NV| Expression that is solved to set the

productions for the indexed purpose.
Distribution Program > Control statements > SETPA > Example

Exam ple
SETPA INCLUDE=1-500, ; internal zone data only
P[1]=zi.1.p1, A[1]=zi.1.a1,
P[2]=zi.1.p2, A[2]=zi.1.a2,
P[3]=zi.1.nhb, A[3]=P[3],
P[4]=zi.2.cnt, A[4]=10 ; equal attraction for all zones
SETPA EXCLUDE=1-500, ; get only external data
P[1]=zi.1.p1, A[1]=zi.2.cnt, ; merges with prior SETPA
P[5]=sqrt(A[3]), A[5]=A[1]+A[2]+A[3] ; weird, but will work
Distribution Program > Examples and FAQ

Examples and FAQ

This section contains examples of the Distribution program, along with a link to FAQ
topics:
• Example 1

• Example 2

• Distribution example 3 - HBW gravity model using gamma impedance function

•
Distribution Program > Examples and FAQ > Example 1

Example 1
RUN PGM=DISTRIBUTION
REPORT ZDAT=Y
ZDATI[1] = TSTPA1,Z=#1,P1=2,P2=3,P3=4,P4=5,P5=6,A1=7,A2=8,A3=9,A4=10,A5=11
MATI = IMPEDE.MAT
MATO = GMTRIPS, MO=1-5, NAME=HBW, HBO, NHB, IX, XI
LOOKUP FAIL=12000,1,0, LIST=N, FILE=TSTFF1, NAME=FF,
LOOKUP[1]=1, RESULT=2,
LOOKUP[2]=1, RESULT=3,
LOOKUP[3]=1, RESULT=4,
LOOKUP[4]=1, RESULT=5,
LOOKUP[5]=1, RESULT=6,
INTERPOLATE=N, SETUPPER=Y
MAXITERS=3 MAXRMSE=10
SETPA P[1]=ZI.1.P1 P[2]=ZI.1.P2 P[3]=ZI.1.P3 P[4]=ZI.1.P4 P[5]=ZI.1.P5
SETPA A[1]=ZI.1.A1 A[2]=ZI.1.A2 A[3]=ZI.1.A3 A[4]=ZI.1.A4 A[5]=ZI.1.A5
LOOP PURP=1,5 ;DO PURPOSES 1-5
MW[PURP] = A[PURP][J] * FF(PURP,MI.1.1)
SUMAF = ROWSUM(PURP)
IF (SUMAF > 0) MW[PURP] = P[PURP]/SUMAF * MW[PURP]
ENDLOOP
ENDRUN
Distribution Program > Examples and FAQ > Example 2

Example 2
This is Gravity application illustrating several ways to do a gravity model.
RUN PGM=DISTRIBUTION
REPORT ZDAT=Y
ZDATI[1]=TSTPA1,Z=#1,
P1=2, P2=3, P3=4, P4=5, P5=6,
A1=7, A2=8, A3=9, A4=10, A5=11
MATI[1]=C:\DEMO\DEMO11.DAT
SETPA P[1]=P1 P[2]=P2 P[3]=P3 P[4]=P4 P[5]=P5
SETPA A[1]=A1 A[2]=A2 A[3]=A3 A[4]=A4 A[5]=A5
LOOKUP FAIL=12000,1,0, LIST=N, FILE=TSTFF1, NAME=FF,
LOOKUP[1]=1, RESULT=2,
LOOKUP[2]=1, RESULT=3,
LOOKUP[3]=1, RESULT=4,
LOOKUP[4]=1, RESULT=5,
LOOKUP[5]=1, RESULT=6,
INTERPOLATE=Y, SETUPPER=N
MAXITERS=20 MAXRMSE=35
MW[11]=MI.1.1
LOOP PURP=1,5 ; distribute with user equation (Results in MW[6-10])
PP = PURP+5
MW[PP] = A[PURP][J]*FF(PURP,MW[11])
SUMAF = P[PURP]/ROWSUM(PP)
MW[PP] = SUMAF*MW[PP]
ENDLOOP
/* Now do same distribution with gravity statements(more efficient) */
GRAVITY PURPOSE=1, LOS=MW[11], FFACTORS=FF
GRAVITY PURPOSE=2, LOS=MW[11], FFACTORS=FF
GRAVITY PURPOSE=3, LOS=MW[11], FFACTORS=FF
GRAVITY PURPOSE=4, LOS=MW[11], FFACTORS=FF
GRAVITY PURPOSE=5, LOS=MW[11], FFACTORS=FF
ENDRUN
Distribution Program > Examples and FAQ > Distribution example 3 - HBW gravity model using gamma impedance function

Distribution example 3 - HBW gravity model using

gamma impedance function
This script reads the composite time skim table created from the AM peak period
highway and transit skims.
This script then performs the gravity model using the estimated friction factors along with
the P's & A's in order to generate a trip table.
Finally, a trip length frequency is performed for the new trip table.
run pgm=distribution
zdati[1]=hbwpa.txt,z=#1,p1=2,p2=3,p3=4,p4=5,a1=6,a2=7,a3=8,a4=9
mati=SKIM.MAT
mato=hbwgm.mat, mo=1-4, name=Income1,Income2,Income3,Income4
PAR maxiters=20 maxrmse=10
setpa p[1]=zi.1.p1 p[2]=zi.1.p2,
p[3]=zi.1.p3 p[4]=zi.1.p4,
a[1]=zi.1.a1 a[2]=zi.1.a2,
a[3]=zi.1.a3 a[4]=zi.1.a4 ; Set P and A Fields
; ======================LOOKUP FUNCTION=====================
LOOKUP NAME=_FFParms,; Gamma Function Parameters
LOOKUP[1]=1, RESULT=2, ; ALPHA VALUE
LOOKUP[2]=1, RESULT=3, ; BETA VALUE
INTERPOLATE=N, ; No Interpolation needed on income class
R=' 1 -0.020 -0.123', ; Income Class 1, Alpha, Beta
' 2 -0.020 -0.123', ; Income Class 2, Alpha, Beta
' 3 -0.020 -0.123', ; Income Class 3, Alpha, Beta
' 4 -0.020 -0.123' ; Income Class 4, Alpha, Beta
; ==============Put TIME VALUES IN WORKING MATRICES===========
mw[11]=mi.1.1 ; time for income class 1
mw[12]=mi.1.2 ; time for income class 2
mw[13]=mi.1.3 ; time for income class 3
mw[14]=mi.1.4 ; time for income class 4
; ======CREATE GAMMA VALUE MATRICES FOR EACH INCOME CLASS=====
LOOP Inc=1,4
_b=_FFParms(1,Inc)
_c=_FFParms(2,Inc)
TSKIM=INC+10 ; Input Time Skim to MW[11] to MW[14]
GSKIM=INC+20 ; Output Gamma Skim
; PUT GAMMA MATRICES IN MW[21]-MW[24]
mw[GSKIM]=(mw[TSKIM]^_b)*exp(_c*mw[TSKIM])
ENDLOOP
; =================PERFORM TRIP DISTRIBUTION=================
LOOP PURP=1,4 ; creates MW[1] to MW[4]
PAF=0
MW[PURP] = A[PURP] * MW[PURP+20]
ATTRSUM=ROWSUM(PURP)
IF (ATTRSUM>0) PAF=P[PURP]/ATTRSUM
MW[PURP]=PAF * MW[PURP]
ENDLOOP
; ========GENERATE FREQUENCY REPORTS BASED ON TIME============
FREQUENCY VALUEMW=1 BASEMW=11, RANGE=1-140,
TITLE='** HBW Income Class 1 Travel Time Frequency **'
FREQUENCY VALUEMW=2 BASEMW=12, RANGE=1-140,
TITLE='** HBW Income Class 2 Travel Time Frequency **'
FREQUENCY VALUEMW=3 BASEMW=13, RANGE=1-140,
TITLE='** HBW Income Class 3 Travel Time Frequency **'
FREQUENCY VALUEMW=4 BASEMW=14, RANGE=1-140,
TITLE='** HBW Income Class 4 Travel Time Frequency **'
endrun
Distribution Program > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see Matrix & Distribution in Chapter 17, “Frequently Asked Questions.”
Generation Program > Introduction to Generation program

Introduction to Generation program

The Generation program processes zonal data according to specified expressions, and
generates arrays of productions and attractions for up to twenty purposes. There are no
default processes; it is your responsibility to specify what is to be accomplished. Usually,
you use the Generation program to produce trip end data files (productions and
attractions) for use in a trip distribution model.
Generation is a direct application of Matrix. There are a few control statements and
keywords in the Matrix control set that are not valid in a Generation application. It is the
user’s responsibility to program the logic, computations, and output; very little is
assumed by the program. However, the capability is nearly open-ended. There may be
up to twenty trip purposes estimated in a single application.
The program processes within an overall origin zone loop controlled by the variable
named I. To make things a little more meaningful to some users, I may alternatively be
referenced as Z. (A companion variable Z is set to I every time I is changed internally; I
and Z can not be revised by the user). The Generation program has two processing
phases and stacks: the normal stack (ILOOP) that begins with the first stack statement,
and an optional ADJUST stack, which begins with the statements following the
PHASE=ADJUST statement. The I-loop processes only the normal stack statements; it
does not proceed beyond the PHASE=ADJUST statement. The ADJUST stack is
processed one time only -- after the I-loop is completed. Its purpose is to provide
capabilities to adjust and/or balance final production and attraction totals.
Productions and attractions are to be computed for each zone; they are referred to as P
and A, respectively. There may be up to twenty Ps and twenty As for each zone. The
computed Ps and As are stored into arrays and must be referenced with array notation.
The arrays are doubly dimensioned. Only the first index (purpose) is required; the
second index (zone) is optional. The zonal index will be set to I if it is not specified.
There is very little need to use a JLOOP, but if one is used, it is suggested that P and A
references within the JLOOP contain both indices. Any attempt to use an invalid index
will result in a fatal message. The lower limit for each index is 0; the upper limits are
MAXPURPS and ZONES. P[1]=ZI.1.POP indicates that the productions for purpose 1
for the current I zone are to be obtained from the ZDATI[1] array named POP. A more
detailed expression would be P[1][I] = ZI.1.POP[I], but such detail is not necessary.
When the ILOOP phase is completed, the program fills in the [0] row and [0] columns for
the P and A arrays; row and column 0 cells are set to the marginal values. The
statements in the ADJUST stack can reference index [0] to obtain row and/or column
totals. The COMP functions, PTOT(#) and ATOT(#) can also be used at any time to
compute the totals for purpose #. There is a significant difference when referencing P
and A in COMP statements in the ADJUST stack. In ILOOP, COMP P and A is
processed for a single zone index (I); in ADJUST, a COMP P and A causes processing
for all zones in that P or A. This is to simplify the final adjusting process. However,
double indexing on the right side of the equal sign can set the process to compute for
only that specific zone.
It should be noted that IF/ENDIF, LOOP/ENDLOOP, and JLOOP/ENDJOOP blocks
and any GOTOs may not span a PHASE. The program will treat such conditions as
errors.
Generation Program > Introduction to Generation program > Example

Exam ple
A[1] = 1 ; sets only 1 cell
P[1] = A[1] ; sets only 1 cell
/* Adjustment Phase — Set A[1] to total to P[1] total
Move A[1] to P[1] (maybe NHB)
fac = ptot(1) / atot(1) a[1]=fac * a[1] ; would be the same
*/
PHASE=ADJUST
A[1] = P[1][0] / A[1][0] * A[1]
P[1] = A[1]

The FILEO PAO keyword is used to write the computed P and A values to file records.
Generation Program > Control statements

Control statements
Most of the standard Matrix program statements are valid in the Generation program,
and a few additional ones are available. Since the Generation program is a subset of the
Matrix program, it is assumed that the user is familiar with the Matrix control statement
set. Only the differences between the Matrix and Generation control statements are
included in this section. For descriptions of other control statements see “Control
statements” on page 545.
Matrix statements no t allowed in Generation:
• FREQUENCY

• PRINTROW

• RENUMBER

Matrix keywords no t allowed in Generation:

• FILEI MATI=

• FILEO MATO=

• COMP MW=

• PARAMETERS MAXMW=

• REPORT MARGINS = MARGINREC=

Generation statements no t in Matrix:

• PROCESS ... ENDPROCESS PHASE=

• BALANCE A2P= P2A= NHB=

Generation keywords no t in Matrix:

• FILEO PAO=

• COMP A= P=

• PARAMETERS MAXPURPS =

• REPORT PC= AC= P= A=

Generation Program > Control statements > BALANCE

BALANCE
This statement is used to specify how the trip ends are to be adjusted in the
Phase=Adjust process. Keywords include:
• A 2P =list

• N H B =list

• P 2A =list

This statement makes the adjustment process much simpler. Typically, most users
adjust the Attraction totals to match the Production Totals.
B A LA N CE k e y wo rd s

Ke y wo rd D e s c rip tio n

A2P |IP| Specifies the purposes whose attraction

totals are to be set to the production totals for
that purpose.

NHB |IP| Specifies the purposes whose attraction

totals are to be set to the production totals for
that purpose, and then the productions are
set equal to the attractions for each zone.

P2A |IP| Specifies the purposes whose production

totals are to be set to the attraction totals for
that purpose.
Generation Program > Control statements > BALANCE > Example

Exam ple
BALANCE A2P=1,2,4-7 NHB=3
Generation Program > Control statements > COMP

COMP
Computes a variable, P/A row, or P/A row element. Keywords include:
• V A R =expression (see Matrix “COMP ” o n p a g e 576)

• A[n][I]=expression

• P[n][I]=expression

• IN CLU D E (see Matrix “COMP ” o n p a g e 576)

• E XCLU D E (see Matrix “COMP ” o n p a g e 576)

The COMP statement is probably the most important of all the statements in the program.
It is used to compute variable and P and A array values. The reader is advised to read
“Introduction to Generation program” on page 689 for information concerning the
differences in array computation within the ILOOP and ADJUST phases. The major
difference between the Generation and Matrix programs for COMP statements is in the
use of P/A[] and MW[]. First of all, MW[] is not valid in the Generation program.
Secondly, COMP P[]=, A[]=, and MW[]= expressions automatically imply a loop based
upon J from 1 to zones in the Matrix program. While in the Generation program, when
P[]= or A[]= is specified in the ILOOP phase, the J loops from I to I (a single iteration).
Within the ADJUST phase, the J loops from 1 to zones. See “COMP” on page 576 for
details of COMP statements.
The COMP statement may contain INCLUDE and EXCLUDE to cause selective processing.
COMP k e y wo rd s

Ke y wo rd D e s c rip tio n

A[n][I] |N| Causes the program to solve the

expression for each value of J. The
result is stored in A[n][I]. If the second
[] is not specified, it will default to I.

P[n][I] |N| Causes the program to solve the

expression for each value of J. The
result is stored in P[n][I]. If the second
[] is not specified, it will default to I.

Expressions may contain the functions ATOT (#) and PTOT (#), which return the attraction
and production totals for purpose #.
Generation Program > Control statements > COMP > Example

Exam ple
COMP P[1]= ZI.1.P1
COMP A[2]=0.90*ahbo
IF (I=38-49) P[1]=ZI.4.SPECIAL
Generation Program > Control statements > FILEO

FILEO
Generates trip-end records. Keywords and subkeywords include:
• PAO
m CFORM
m DBF
m FORM
m LIST
m NAMES
m PRINT

The PAO keyword is used to request that a file containing trip end records be written at
the end of all stack processing. There may be multiple PAO specifications; each one
should reference a different file. They will be processed in the order in which they appear
in the input stream. The flexibility of the statement can allow records to be written in
almost any format that other software systems might require. Within Cube Voyager, the
most likely place where this data would be read would be in any program that accepts
ZDATI files; usually it should be written in a format such that the Distribution process can
read it as the distribution trip ends. Although other data can be placed on these records,
normally, the records should contain only the zone number (I), and the various trip ends
such as P[1], a[1], etc.
For consistency, the PAO processing uses the Cube Voyager General PRINT control
statement processor. The PRINT processor is called one time for each zone in a loop
where Z=1-Zones. The major difference between PAO and PRINT statement is that
PAO specifies the output file by definition, and the FILE keyword is not allowed. Full
documentation about the sub-keywords can be found in “PRINT” on page 69.
PAO can be optionally written as a DBF by setting DBF=T or to an MDB by designating
the output MDB file name followed by a backslash and the element name.
FILE O k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

PAO |KF10| Name of a file where the

formatted records are to be
written.

PAO CFORM |S| Format for following string list

items. Normally, text variables will
not be written to a PAO file.

PAO DBF |?| Indicates if the output records are

to written as a DBF file. This is off,
unless turned on. If DBF=T is
 specified, the user may optionally
name the variables to be written
to the DBF records with the
NAMES subkeyword. A maximum
of 100 variables may be
designated for single DBF.
If the PAO keyword specifies an
MDB file for the output, then DBF
subkeyword should either not be
specified or set to T. If DBF=F and
PAO specifies an MDB file the
program will fail.

PAO FORM |S| Format for following numerical list

items. FORM=20.2SLR is
recommended if the Distribution
program is going to read the file.

PAO LIST |S| List of items to be formatted into

the output buffer. P and A must be
indexed; the zone index is
automatically supplied as Z. In
most cases, the only variables in
the list will be Z, and expressions
of P[n] and A[n] values. If any
expressions are used, they
should be enclosed within
parenthesis, and should not
contain any spaces or commas.

PAO NAMES |S| Names to be assigned to the

DBF variables. The names are
positional (their indices refer to
the positional location of the
variables in the LIST). For
example:
LIST=z,p1,p2,p3,a1,a2,a3,
DBF=T,NAMES=TAZ,
WORKPROD,
OTHERPROD,NHBPROD
would set the names in the DBF
for z,p1,p2,p3, respectively.
Likewise:
NAMES[5]=WORKATTR,
OTHERATTR, NHBATTR
would set the names for a1,a2,a3.
A name may not exceed 10
characters; it will be truncated, if
designated as longer than 10.
The routine does not check for
duplicate names. Extraneous
NAMES (that is, NAMES[11] in this
example), are ignored. If there is
no name specified for a variable,
the program will use the variable
name directly. If the LIST field is
an expression, the program will
use the first 10 alphanumeric
digits, ignoring other characters.
For example
(VAR1+VAR2+VAR3) will be
named VAR1VAR2VA.
PAO PRINT |?| Indicates if the output records are
to also be listed to the standard
output. This is off, unless turned
on.
Generation Program > Control statements > FILEO > Example

Exam ple
PAO = OUTPUT.DAT, FORM=8.0,
LIST = Z(2) P[1] P[2] P[3] P[4] P[5] A[1] A[2] A[3] A[4] A[5] PRINT=N
PAO[2] = OUTPUT2.DAT, FORM=SL, Z P[1] A[1] P[2] A[2] (P[3]+P[4]) (A[3]+A[4])
Generation Program > Control statements > PARAMETERS

PARAMETERS
Set general parameters. Keywords include:
• MA XP U R P S

• ZON E S

P A R A ME T E R S k e y wo rd s

Ke y wo rd D e s c rip tio n

MAXPURPS |I| Sets the number of P and A arrays to be

allocated, and establishes an index
boundary for P and A in COMP statements.
The maximum value is 20, which the
program defaults to, if the keyword is not
specified. Setting this to a more realistic
value will cause a less drain on computer
memory.

ZONES |I| Establishes the number of zones to

process. If ZONES is not specified, and the
program has no other way to identify the
appropriate number of zones, it will be set
to 100.
Generation Program > Control statements > PARAMETERS > Example

Exam ple
ZONES=3000 MAXPURPS=5
Generation Program > Control statements > PROCESS ... ENDPROCESS

PROCESS ... ENDPROCESS

Establishes phase blocks. Keywords include:
• PHASE

• ENDPHASE

A user process phase stack is defined by a PROCESS statement that designates its
beginning and an ENDPROCESS statement that designates its ending. To simplify coding,
the PROCESS control word is not necessary; PHASE=name may be used directly. And, to
further simplify coding, the ENDPROCESS statement is not necessary; the occurrence of
another PROCESS statement acts as the ENDPROCESS statement. If ENDPROCESS is used, it
may be coded as either ENDPROCESS or ENDPHASE. In the Generation program, normally,
only the PHASE=ADJUST statement is all that is needed to differentiate between the normal
ILOOP statements and the ADJUST statements that are used to balance the final Ps and
As.
P R OCE S S k e y wo rd s

Ke y wo rd D e s c rip tio n

PHASE |KS| Names the phase stack. The control

statements that follow it, until an
ENDPROCESS statement or another
PROCESS statement is encountered, will
be executed when the phase is internally
executed. Exception: Static statements,
such as PARAMETERS, FILEI, FILEO,
LOOKUP, are not processed as stack
statements, even if they are located
within a phase block. The following
PHASE names may be specified:
• ILOOP
• ADJUST

ENDPHASE |K| Defines the end of the user control

statements for a stack.
Generation Program > Control statements > PROCESS ... ENDPROCESS > Example

Exam ple
RUN PGM=GENERATION
.
P[1]=….
.
.
PHASE=ADJUST
; the following statements are used to balance Ps and As
RUN PGM=GENERATION
.
PHASE=ILOOP
P[1]=….
.
PHASE=ADJUST
; the following statements are used to balance Ps and As
Generation Program > Control statements > REPORT

REPORT
Requests reports and establishes tracing. Keywords include:
• AC

• A

• PC

• P

• T R A CE

R E P OR T k e y wo rd s

Ke y wo rd D e s c rip tio n

AC |?| Requests that the computed attractions be

reported. This report precedes ADJUST
processing.

A |?| Requests that the final attractions be

reported. This report follows any ADJUST
processing.

PC |?| Requests that the computed productions be

reported. This report precedes ADJUST
processing.

P |?| Requests that the final productions be

reported. This report follows any ADJUST
processing.

TRACE |K?| Controls the listing of the stack statements as

they are processed.
Generation Program > Control statements > REPORT > Example

Exam ple
REPORT AC=y A=y P=y
Generation Program > Examples and FAQ

Examples and FAQ

This section contains examples of the Generation program, along with a link to the
Voyager FAQ chapter.
• Example 1

• Example 2

• Frequently asked questions

Generation Program > Examples and FAQ > Example 1

Example 1
RUN PGM=GENERATION
ID=DEMO TRIP GENERATION
pagewidth=80
zones=19
zdati[1]=c:\demo\demo08.dat,z=#2,select=1-1,
hh1=#3,hh2=#4,hh3=#5,hh4=#6,hh5=#7,hh6=#8,hh7=#9,
hh8=10,hh9=11,hh10=12,hh11=#13,hh12=#14,hh13=#15
zdati[2]=c:\demo\demo08.dat,z=#2, select=2-1, emp1=3,emp2=4
zdati[3]=c:\demo\demo08.dat,z=2-4,select=3-1, p3a=21-25,p4a=31-35
zdati[4]=c:\demo\demo08.dat,z=2-4,select=4-1, xicnt=6-10,ixcnt=11-15
report zdat=y
tothh = zi.1.hh1 + zi.1.hh2 + zi.1.hh3 + zi.1.hh4 + zi.1.hh5 + zi.1.hh6 +
zi.1.hh7 + zi.1.hh8 + zi.1.hh9 + zi.1.hh10 + zi.1.hh11 + zi.1.hh12 +
zi.1.hh13
totemp = zi.2.emp1 + zi.2.emp2
phbw = .21 * 4.5 * zi.1.hh1 + .21 * 6.8 * zi.1.hh2 +
.18 * 8.4 * zi.1.hh3 +
.18 * 10.2 * zi.1.hh4 + .18 * 11.9 * zi.1.hh5 +
.16 * 13.2 * zi.1.hh6 + .16 * 14.4 * zi.1.hh7 +
.16 * 15.1 * zi.1.hh8 + .15 * 16.4 * zi.1.hh9 +
.14 * 17.7 * zi.1.hh10 + .13 * 18.0 * zi.1.hh11 +
.13 * 19.0 * zi.1.hh12 + .13 * 19.2 * zi.1.hh13
phbo = .57 * 4.5 * zi.1.hh1 + .57 * 6.8 * zi.1.hh2 +
.57 * 8.4 * zi.1.hh3 + .59 * 10.2 * zi.1.hh4 +
.59 * 11.9 * zi.1.hh5 + .61 * 13.2 * zi.1.hh6 +
.61 * 14.4 * zi.1.hh7 + .68 * 15.1 * zi.1.hh8 +
.62 * 16.4 * zi.1.hh9 + .62 * 17.7 * zi.1.hh10 +
.62 * 18.0 * zi.1.hh11 + .62 * 19.0 * zi.1.hh12 +
.62 * 19.2 * zi.1.hh13
pnhb = .22 * 4.5 * zi.1.hh1 + .22 * 6.8 * zi.1.hh2 +
.22 * 8.4 * zi.1.hh3 + .23 * 10.2 * zi.1.hh4 +
.23 * 11.9 * zi.1.hh5 + .23 * 13.2 * zi.1.hh6 +
.23 * 14.4 * zi.1.hh7 + .23 * 15.1 * zi.1.hh8 +
.23 * 16.4 * zi.1.hh9 + .24 * 17.7 * zi.1.hh10 +
.25 * 18.0 * zi.1.hh11 + .25 * 19.0 * zi.1.hh12 +
.25 * 19.2 * zi.1.hh13
pix = 0.03 * 1.03 * (phbw+phbo+pnhb)
pxi = zi.4.xicnt
ahbw = 1.81 * ( 1.7 * totemp)
ahbo = 1.90 * (10.0 * zi.2.emp1 + 0.5 * zi.2.emp2 + tothh)
anhb = 1.49 * ( 2.0 * zi.2.emp1 + 2.5 * zi.2.emp2 + 0.5*tothh)
axi = 0.08*ahbw + 0.10*ahbo + 0.03*anhb
aix = zi.4.ixcnt
p[1]=phbw, p[2]=phbo, p[3]=pnhb, p[4]=pix, p[5]=pxi
a[1]=0.92*ahbw a[2]=0.90*ahbo a[3]=0.97*anhb a[4]=aix, a[5]=axi
phase=adjust
a[1] = p[1][0] / a[1][0] * a[1]
a[2] = p[2][0] / a[2][0] * a[2]
a[3] = p[3][0] / a[3][0] * a[3]
p[3] = a[3]
a[4] = p[4][0] / a[4][0] * a[4]
p[5] = a[5][0] / p[5][0] * p[5]
pao=out.dat,form=8.0 list=z(2),p[1],p[2],p[3],p[4],p[5],a[1],a[2],a[3],a[4],a[5]
ENDRUN
Generation Program > Examples and FAQ > Example 2

Example 2
RUN PGM=GENERATION
FILEI ZDATI[1]=zonedata.dbf ; dbf data structure is Z, V1, V2,...., V254
FILEI ZDATI[2]=zonedata.dbf ; External PA file. dbf data structure is Z,
; Xprod1,Xprod2,Xprod3,Xattr1,Xattr2,Xattr3 for example
; These fields could also be fields on your zone data
file
; ZDATI[1] as well.
FILEO PAO[1] = "TRIPENDS.DBF",
FORM=6.0, DBF=T, LIST=Z, P[1] P[2] P[3] A[1] A[2] A[3]
; lets say system has 1000 zones with 901-1000 being the externals
; and we have 3 trip purposes
PARAMETERS ZONES=1000
PROCESS PHASE=ILOOP
; define trip rates by purposes
; purpose = home based
hbp_p = 0.2 ; production trip rate per person (population) per day
hbp_ia = 0.5 ; production trip rate per industry/agricultural worker per day
hbp_s = 0.6 ; production trip rate per service worker per day
hbp_r = 40.0 ; production trip rate per retail worker per day (incl shoppers)
hbp_sc = 0.1 ; production trip rate per pupil/student per day
hba_p = 1.8 ; attraction trip rate per person (population) per day
hba_ia = 0.6 ; attraction trip rate per industry/agricultural worker per day
hba_s = 0.6 ; attraction trip rate per service worker per day
hba_r = 45.0 ; attraction trip rate per retail worker per day (incl shoppers)
hba_sc = 0.1 ; attraction trip rate per pupil/student per day
; purpose = non-home based
nhbp_p = 1.5 ; production trip rate per person (population) per day
nhbp_ia = 0.3 ; production trip rate per industry/agricultural worker per day
nhbp_s = 0.25 ; production trip rate per service worker per day
nhbp_r = 12 ; production trip rate per retail worker per day (incl shoppers)
nhbp_sc = 0.1 ; production trip rate per pupil/student per day
nhba_p = 1.3 ; attraction trip rate per person (population) per day
nhba_ia = 0.3 ; attraction trip rate per industry/agricultural worker per day
nhba_s = 0.3 ; attraction trip rate per service worker per day
nhba_r = 14.0 ; attraction trip rate per retail worker per day (incl shoppers)
nhba_sc = 0.1 ; attraction trip rate per pupil/student per day
; purpose = school
schp_p = 0.15 ; production trip rate per person (population) per day
schp_ia = 0 ; production trip rate per industry/agricultural worker per day
schp_s = 0.005 ; production trip rate per service worker per day
schp_r = 0.005 ; production trip rate per retail worker per day
schp_sc = 0.95 ; production trip rate per pupil/student per day
scha_p = 0.15 ; attraction trip rate per person (population) per day
scha_ia = 0 ; attraction trip rate per industry/agricultural worker per day
scha_s = 0.005 ; attraction trip rate per service worker per day
scha_r = 0.005 ; attraction trip rate per retail worker per day
scha_sc = 0.95 ; attraction trip rate per pupil/student per day
IF (I<=900) ; define P/A functions for internal zones
; ----- calculate productions per day by purpose
; zi.1.vnames are just the filed names in the dbf file
P[1] = (hbp_p*zi.1.pop_2002 + hbp_ia*zi.1.inag_2002 + hbp_s*zi.1.serv_2002 +
hbp_r*zi.1.ret_2002 + hbp_sc*zi.1.sch_2002)
P[2] = (nhbp_p*zi.1.pop_2002+ nhbp_ia*zi.1.inag_2002+ nhbp_s*zi.1.serv_2002+
nhbp_r*zi.1.ret_2002+ nhbp_sc*zi.1.sch_2002)
P[3] = (schp_p*zi.1.pop_2002+ schp_ia*zi.1.inag_2002+ schp_s*zi.1.serv_2002+
schp_r*zi.1.ret_2002+ schp_sc*zi.1.sch_2002)
; ----- calculate attractions per day by purpose
; zi.1.vnames are just the filed names in the dbf file
A[1] = (hba_p*zi.1.pop_2002 + hba_ia*zi.1.inag_2002 + hba_s*zi.1.serv_2002 +
hba_r*zi.1.ret_2002 + hba_sc*zi.1.sch_2002)
A[2] = (nhba_p*zi.1.pop_2002+ nhba_ia*zi.1.inag_2002+ nhba_s*zi.1.serv_2002+
nhba_r*zi.1.ret_2002+ nhba_sc*zi.1.sch_2002)
A[3] = (scha_p*zi.1.pop_2002+ scha_ia*zi.1.inag_2002+ scha_s*zi.1.serv_2002+
scha_r*zi.1.ret_2002+ scha_sc*zi.1.sch_2002)
ELSE ; define P/A for external zones
P[1]=zi.2.Xprod1
P[2]=zi.2.Xprod2
P[3]=zi.2.Xprod3
A[1]=zi.2.Xattr1
A[2]=zi.2.Xattr2
A[3]=zi.2.Xattr3
ENDIF
PROCESS PHASE=ADJUST
; adjust zonal attractions so total attractions match total productions
BALANCE A2P=1,3 NHB=2 ; balance attrs to prods for purposes 1, 3
; prods set to attrs for purpose 2
ENDPHASE
ENDRUN
Generation Program > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see Generation in Chapter 17, “Frequently Asked Questions.”
Public Transport Program > Overview

Overview
The Public Transport program is the Cube Voyager program that lets you prepare public
transport data and model public transport systems. This section provides an overview of
the Public Transport program, listing the program’s primary capabilities, required inputs
and generated outputs, and discussing how you can use the program to prepare data
and model public transport systems. This section also discusses terminology used
within this document.
Topics include:
• Summary of facts

• Preparing data

• Modeling

• Heuristic Process

• Terminology
Public Transport Program > Overview > Summary of facts

Summary of facts
The Public Transport program offers:
• User control over all aspects of the Public Transport model

• True multirouting between zone pairs, or alternatively single best-path routes may be used

• Demand stratification by user class with variations in the behavior of classes represented
by different cost functions

• Comprehensive fares modeling

• Preparation of a public transport network for Public Transport’s modeling functionality

• Generation of the nontransit element of the public transport network (that is, access,
egress, transfer and park and ride legs)

• Skimming, network-wide and mode specific, composite and average travel costs, and
components of costs

• Two methods (service-frequency and service-frequency-and-cost) for loading demand on

to transit choices at stops

• Analyses of loaded trips—transfers between modes, operators, lines, a variety of stop-to-

stop movements, select-link/line outputs

• Reporting of input data, model infrastructure, multiple routes with probability of use, line
and link loads, secondary analyses

The Public Transport program requires as input:

• A highway or public transport network

• Public transport system data

• Line data

• Fare data

• Nontransit legs (developed externally or by Public Transport)

• Generalized cost information

• Demand

The Public Transport program produces:

• Nontransit legs

• Enumerated routes
• Skim and select-link matrices

• Loaded lines and nontransit legs

• Transfer matrices—results of loading analyses

• A variety of reports of input data and model results

• A public transport network that can be displayed by Cube and used as an input network for
further modeling
Public Transport Program > Overview > Preparing data

Preparing data
You can use the Public Transport program to prepare data that supports public transport
modeling. You can prepare:
• A network, produced by Network or Public Transport, containing characteristics of zones,
nodes and links (that is, node coordinates, walk and transit link times, distance, and so
forth), over which the public transport system operates.

• System information used to describe the characteristics of the public transport system such
as modes, operators and wait curves.

• Service or line data, defining the characteristics of the lines and nodes traversed.

• Nontransit legs, presenting opportunities to access the public transport system, egress
from it and transfer between services during the course of a trip. Nontransit legs may be
determined externally and/or generated by Public Transport under user control.

• Control information for route enumeration and evaluation.

Public Transport Program > Overview > Modeling

Modeling
You can use the Public Transport program to model public transport. The model has
several parts:
• Route enumeration and evaluation

• Skimming (levels of service matrices)

• Loading (assignment)

• Reporting
Public Transport Program > Overview > Modeling > Route enumeration and evaluation

Route enumeration and evaluation

During route enumeration and evaluation, the Public Transport model finds “reasonable”
or “attractive” multiple discrete routes between zones, considering:
• Number of transfers

• Spread — the margin of cost over the minimum cost route

• Nontransit and in-vehicle costs

• Boarding and transfer penalties by mode

• Waiting time, derived from the combined frequency of services at stop nodes

• Fares (considered only for evaluation)

Public Transport Program > Overview > Modeling > Skimming (levels of service matrices)

Skimming (levels of service matrices)

During skimming, the Public Transport model skims (extracts) the costs—and the
components of costs—of journeys between zones. These costs are suitable for model
validation, demand modeling, scheme evaluation, loading demand on the network and
producing operational statistics like passenger miles, hours and revenue. The model
can extract the following skims:
• Composite costs

• Value of choice

• Average, perceived, and actual trip costs and components (that is, nontransit, in-vehicle
and wait times, boarding and transfer penalties, fares)

• Best trip cost

The model can extract network-wide trip costs, or the model can stratify them, where
appropriate, by modes.
Public Transport Program > Overview > Modeling > Loading (assignment)

Loading (assignment)
During loading, the Public Transport model loads demand, in the form of trips between
zone pairs. The model uses a series of models at the different decision points in a trip:
• The walk-choice model allocates trips between attractive choices at access, egress, and
transfer points. Where walk and transit choices are available, it also determines the transit
share.

• The service-frequency or the service-frequency-and-cost model allocates the transit share

at a stop between the attractive services available at that stop.

• The alternative-alighting model apportions the share of a service to the attractive

alternative alighting points of that service.

(Strictly, these models determine the probability of use of the alternative routes; trips are
then loaded on the routes based upon these probabilities.)
Two forms of loading are supported, multirouting and best-path. The best-path method
does not use walk or alighting choice models, and loads demand using the service-
frequency model.
Public Transport Program > Overview > Modeling > Reporting

Reporting
During reporting, the Public Transport model produces reports you can use to analyze
different aspects of passenger loadings:
• Passenger transfers between all modes

• Passenger transfers between public transport modes

• Passenger transfers between operators

• A variety of stop-to-stop movements

Public Transport Program > Overview > Heuristic Process

Heuristic Process
The Public Transport modeling algorithm implements a sequence of rules (network
simplification > minimum path > enumeration > evaluation (decision points probabilistic
models > combination of probabilities at the different decision points) / iterative route
evaluation step in case of crowding) to find an "approximate/feasible solution" close to
the optimal solution. This approach can be defined an heuristic process.
It is therefore important that once the model is defined in terms of the system, lines and
parameters, this fundamental structure of the Public Transport model is kept consistent
with the analysis that needs to be undertaken in different scenarios. The results from the
model could be sensitive to major changes in the inputs due to the heuristics in network
simplification, route enumeration and evaluation.
This consistency between the base scenarios and the forecasting scenarios is a general
rule that should be followed, referring to the attributes coded to describe the Public
Transport model (modes numbering system, etc.). In particular, the line ordering should
be defined in the base scenario, and the model should be calibrated accordingly. This
line ordering, consolidated in the base scenario, should be kept consistent in forecasting
scenarios, whilst new lines should be added at the end of the line file or in a new line file.
Public Transport Program > Overview > Terminology

Terminology
This document uses the following sets of terms interchangeably:
• ”transit” and “public transport.” In particular, “transit” is used in this document to describe a
type of link over which a public transport service can run, namely “transit link” as opposed
to “nontransit link.”

• ”lines” and “services”

• ”transfers” and “interchanges”

• ”skims” and “levels of service”

• ”generalized cost” and “generalized time”

• ”origin-destination pairs,” “zone pairs,” “OD pairs,” and “IJ pairs”

• ”nontransit time” and “walk time”

• ”loading” and “assignment”

• ”volume,” “load,” “flow,” and “passenger flow”

Public Transport Program > Processes

Processes
The Public Transport program performs the following processes:
• Network development

• Route enumeration

• Route evaluation

• Skimming (level of service)

• Loading

• Select link

• Loading analyses

• Crowd modeling

Some processes have associated phases which allow you to augment the task with
additional context-sensitive computations.
You control the main processes and their associated phases, within a prescribed
hierarchy.

Public Transpo rt pro gram pro cesses and asso ciated phases

(With multiple user classes, processes in the blue boxes are performed separately for
each class.)
See “Phases” on page 747 for a description of the phases in the Public Transport
program.
You configure the Public Transport program to run through a specific combination of
control statements and phases.
Control statements are either static or dynamic. Static statements may be present
anywhere in the job stream; the program evaluates them once. Dynamic statements
may be present only within phases; the program evaluates them as encountered, during
the execution of the phases.
Only context-sensitive dynamic control statements are available to the phases; the
description of each phase lists valid control statements (see “Phases” on page 747).
Only code phases that contain control statements; do not code empty phases.
Public Transport Program > Processes > Network development

Network development
During network development, the Public Transport program:
• Reads in the input network from FILEI N E T I.

• Processes public transport system data in FILEI S Y S T E MI

• Processes the LINE control statements in FILEI LIN E I

• Processes the FACTORS control statements in FILEI FA CT OR I

• Processes the PARAMETERS control statements in the script file

• Generates and/or reads nontransit legs with the GENERATE statements.

• Develops a comprehensive public transport network from the basic network, public
transport system data, lines, nontransit leg, and control information. This includes stringent
validation and consistency checks to ensure that the different components of the public
transport network are compatible.

The DATAPREP phase is mandatory for public transport network development. The
phase provides the control statements for nontransit leg generation and/or input.
Either the Network program or the Public Transport program can produce the input
network. However, only zone, node, and link information are taken from networks
produce by the Network program; you must provide public transport system, line, and
control data.
The components of the public transport network are common to all user classes, except
for route-enumeration and route-evaluation control information, which may be provided
separately for each class.
See “Public transport network development” on page 1017 for examples of this task.
Inp uts re q uire d fo r P ub lic T ra ns p o rt ne two rk d e v e lo p me nt

• A network, produced by Network or Public Transport, input

with NETI.

• Public transport system data, input with SYSTEMI

• One or more lines files, input with LINEI[#]

• Control information for route enumeration and route

evaluation, input with FACTORI (For multiple user classes:
control information input with FACTORI[#])

• Global parameters input with the PARAMETERS statement

• One or more GENERATE statements and, optionally,

nontransit legs input with NTLEGI[#]
 Outp uts p ro d uc e d b y P ub lic T ra ns p o rt ne two rk
d e v e lo p me nt

• A public transport network, which may be saved with NETO.

• A table of links and their attributes, in DBF format, which may

be saved with LINKO.

• Nontransit legs (generated and input), which may be saved

with NTLEGO. The legs are in the format specified by the NT
control statement. Optional PNR, KNR, and drive access
results are distinguished by respective mode number
specified by user.
• A text version of the lines in the public transport system, which
may be saved with LINEO. The lines are in the format
specified by the LINE control statement.

The Public Transport network is made available to any other processes in the job
stream that require it. If trips are loaded in the run creating the public transport network,
all output files can optionally contain the results of the loading.
The saved Public Transport network may be used in subsequent runs of the Public
Transport program for route enumeration, route evaluation, skimming, loading and
loading analyses. It contains all information required for these processes apart from
fares data which may optionally be read later, so allowing it to vary between program
runs.
You can use Cube to display but not edit the Public Transport network.
Public Transport Program > Processes > Network development > Associated phases

Asso ciated phases

• DATAPREP (mandatory)
Public Transport Program > Processes > Route enumeration

Route enumeration
During route enumeration, the Public Transport program identifies sets of discrete routes
between zone pairs, which have some probability of being used by passengers to travel
between the zones. Route enumeration is a heuristic process, which you control with the
FACTORS statement.

This set of discrete routes may be pruned at the route-evaluation stage, in compliance
with further user specified controls.
A ROUTEO file in the job stream invokes route enumeration. You can save an
enumerated routes file and input the file to a subsequent run with ROUTEI.
When modeling multiple user classes, provide separate FACTORS statements for each
class to produce enumerated route files for each class.
By default, Public Transport enumerates routes for all zone pairs. However, you can use
ROUTEI and ROUTEO statements to select zone pairs separately for route enumeration
and reporting.
See “Route-enumeration process” on page 959 for theory about route enumeration.
Inp uts re q uire d fo r P ub lic T ra ns p o rt ro ute e nume ra tio n

• A public transport network file, produced either by the current

run of the Public Transport program, or produced previously
and input with N E T I.

Outp uts p ro d uc e d b y P ub lic T ra ns p o rt ro ute e nume ra tio n

• An enumerated routes file, ROUTEO. For multiple user

classes, enumerated routes files, ROUTEO[#].

NOTE: Vast quantities of data can be required to define a public transport system. To
improve performance of the main algorithms and minimize memory and temporary disk
storage, the data is organized in a highly compressed form for processing and storing
routes. The line data is converted into transit legs and the network data into nontransit
legs. The simplified network, which is described in “Network simplification” on page 947,
can be examined through a series of reports specified on the REREPORT statement.
Public Transport Program > Processes > Route enumeration > Associated phases

Asso ciated phases

• None
Public Transport Program > Processes > Route evaluation

Route evaluation
During route evaluation, the Public Transport program:
• Examines enumerated routes

• Eliminates any illogical ones that have crept in due to network simplification

• Disaggregates bundled routes, where appropriate

• Identifies routes that have, at the minimum, a user specified probability of use or more, at
every decision point along the route

The route-evaluation process is a prerequisite for the skimming, select-link, loading, and
loading-analyses processes. Selecting one or more of these processes automatically
invokes the route-evaluation process.
This is because only enumerated routes are saved; they are evaluated as required.
(Enumerated routes produced by an earlier run may be input with ROUTEI for evaluation
or generated by specifying a filename with ROUTEO).
Evaluated routes may be reported with ROUTEI and ROUTEO.
See “Route-evaluation process” on page 965 for the theory supporting route evaluation.
Inp uts re q uire d fo r P ub lic T ra ns p o rt ro ute e v a lua tio n

• A public transport network file, produced either by the current

run of the Public Transport program, or produced previously
and input with NETI.

• A route file, produced either by the current run of the Public

Transport program, or produced previously and input with
ROUTEI. (For multiple user classes, enumerated routes files
input with ROUTEI[#]).

• Fares data may be read directly into a route-evaluation run.

NOTE: Any previously built NETI and ROUTEI files that you input must be compatible.

Outp uts p ro d uc e d b y P ub lic T ra ns p o rt ro ute e v a lua tio n 1

• One or more sets of “attractive” or “reasonable” route

bundles
• Their probabilities of use
• The cost of using the routes

1 Produced for each zone pair. Can be reported by zone pair, but not saved.
The skimming, select-link, loading, and loading-analyses processes are performed on
the fly. Indeed, these are by-products of the route-evaluation process, but described
separately, as they report on different aspects of the Public Transport model.
Public Transport Program > Processes > Route evaluation > Associated phases

Asso ciated phases

• MATI

• SELECTIJ
Public Transport Program > Processes > Skimming (level of service)

Skimming (level of service)

The skimming process produces skim (level of service) matrices of total trip costs and
their components, from the information generated by route evaluation. When modeling
multiple user classes, you can produce skims for each class from the individual
enumerated route files.
This section is detailed; you may skip ahead to “Skim functions — quick reference” on
page 732 for a quick reference of the skimming functions.
See also:
• “Skimming process” on page 978 for more information from a theoretical standpoint.

• “Public transport skimming” on page 1022 for a comprehensive example of the skimming
process.

NOTE: All skim matriceshave their intrazonal cells on the diagonal, and the cells for
unconnected IJ pairs, set to zero. These can be reset to large values, either in the
MATO phase or outside the Public Transport program, for modeling demand.

Topics in this section include:

• Skimming overview

• Skimming arguments and syntax

• Wait-time skim functions

• Travel-time skim functions

• Penalty skim functions

• Fare skim functions

• Other skim functions

• Skim functions — quick reference

Public Transport Program > Processes > Skimming (level of service) > Skimming overview

Skimming overview
Inp uts re q uire d fo r P ub lic T ra ns p o rt s k imming

• A public transport network file, either produced by the current

run of the Public Transport program, or produced previously
and input with NETI.

• A route file, produced either by the current run of the Public

Transport program, or produced previously and input with
ROUTEI (for multiple user classes, enumerated routes files
input with ROUTEI[#]).

NOTE: If previously built files are input with NETI and ROUTEI, the files must be
compatible.

Outp uts p ro d uc e d b y P ub lic T ra ns p o rt s k imming

• A matrix file, MATO (for multiple user classes, matrix files,

MATO[#]).

• A table of links and their attributes, in DBF format, which may

be saved in the file designated by LINKO.
Public Transport Program > Processes > Skimming (level of service) > Skimming overview > Associated phases

Asso ciated phases

• SKIMIJ (mandatory)

• MATO
Public Transport Program > Processes > Skimming (level of service) > Skimming arguments and syntax

Skimming arguments and syntax

Skims can be produced for all O-D pairs or a selection and are extracted through a
series of functions or predefined processes. A skim function is accessed once for each
zone pair and returns a numeric value which would generally be saved in a row of a
working matrix.
Each skim function has a name and one, two or no arguments, and is specified as
follows:
• SkimName(Arg1)

• SkimName(Arg1, Arg2)

• SkimName

where:
• SkimName includes an explicit prefix, or a default, that denotes its type:
m
COMP for composite skims
m
CWD for crowded skims
m
BEST for best skims
m
All other skims are average skims

• Arg1 is the route set number and currently supports one route set, or Arg1=0. In this case
the attribute skimmed is the total for the zone pair.
Example 1 : Shows how skims requiring one argument are invoked.
MW[2]=COMPCOST(0)
MW[3]=ValOfChoice(0)
MW[4]=IWAITA(0)

The result is the skim for the route set which is also the overall skim for the OD pair
(route set).
• Arg2 is a list of modes for which the skim is required. For example, Arg2= 3 would provide
a skim for mode 3 while Arg2=1,2,3,4,5 would produce one skim for modes 1 through 5.
This could also be written as 1,-5.
Note that range specification for skim functions is different from the standard
specification for Cube Voyager. The arguments in skim functions are evaluated as
expressions. So, the standard way of specifying ranges, Arg2=1-5 would result in
Arg2=-4. Combinations such as 1,3,-5,7,9,-12 are valid.
Example 2 :
Shows how skim functions requiring two arguments are invoked. The
second argument is a single number or a list of single numbers and pairs specifying
 ranges. MW[7] will contain a DIST skim for mode 1, MW[8] will contain a TIMEA
skim for modes 1,7,8,9,11,31,32,and 33, MW[9] for modes 1,7,8,9,11 which happen
to be the transit modes in the system and MW[10] for modes 31,32,33 which are
nontransit modes.
MW[7] = DIST(0,1)
MW[8] = TIMEA(0,1,7,-9,11,31,-33)
MW[9] = TIMEA(0,1,7,-9,11)
MW[10] = TIMEA(0,31,-33)

If skims are required for all, transit or nontransit modes, an alternative way to specify
Arg2 is ALLMODES, TMODES or NTMODES (case insensitive).
Example 3 :
Shows an alternative method for invoking skim functions requiring two
arguments. Here, Arg2 is text rather than a list; MW[8] will contain a TIMEA skim for
all modes, MW[9] for transit modes and MW[10] for nontransit modes.
MW[11] = TIMEP(0,ALLMODES)
MW[12] = TIMEP(0,TMODES)
MW[13] = TIMEP(0,NTMODES)

• Where a skim requires no arguments, the parenthesis () should not be coded.

Example 4 : Shows how a skim function requiring no arguments is invoked.
MW[14] = BESTJRNY

Subsequent sections describe the types of skims that can be extracted and their
contents.
Public Transport Program > Processes > Skimming (level of service) > Wait-time skim functions

Wait-time skim functions

This section describes wait-time skim functions:
• Actual crowding wait time

• Actual initial wait time

• Actual transfer wait time

• Perceived crowding wait time

• Perceived initial wait time

• Perceived transfer wait time

Public Transport Program > Processes > Skimming (level of service) > Wait-time skim functions > Actual crowding wait
time

Actual cro wding wait tim e

CWDWAITA(RouteSet)

See also: Skimming arguments and syntax

Computes the average additional wait time due to crowding effects incurred at the
transfer points of all “attractive” routes between zones.
The additional wait time occurs when unable to board a service (so needing to wait for
the next one) and at the end of modeled period (where demand exceeds capacity
causing a bottleneck).
Public Transport Program > Processes > Skimming (level of service) > Wait-time skim functions > Actual initial wait time

Actual initial wait tim e

IWAITA(RouteSet)

See also: Skimming arguments and syntax

Computes the average actual wait time incurred at the start of the trip for all “attractive”
routes between zones. It is calculated either from one or more wait curves supplied by
the WAITCRVDEF control statement, assigned to nodes by IW AITCURVE keyword, or, for
nodes that have not been assigned one, from a default wait curve.
Public Transport Program > Processes > Skimming (level of service) > Wait-time skim functions > Actual transfer wait time

Actual transfer wait tim e

XWAITA(RouteSet)

See also: Skimming arguments and syntax

Computes the average actual wait time incurred at the transfer points of all “attractive”
routes between zones. It is calculated either from one or more wait curves supplied by
the WAITCRVDEF control statement, assigned to nodes by the XW AITCURVE keyword, or,
for nodes that have not been assigned one, from a default wait curve.
Public Transport Program > Processes > Skimming (level of service) > Wait-time skim functions > Perceived crowding wait
time

Perceived cro wding wait tim e

CWDWAITP(RouteSet)

See also: Skimming arguments and syntax

Computes the average additional wait time due to crowding effects incurred at the
transfer points of all “attractive” routes between zones, weighted by the W AITFACTOR
keyword.
The additional wait time occurs when unable to board a service (so needing to wait for
the next one) and at the end of modeled period (where demand exceeds capacity
causing a bottleneck).
Public Transport Program > Processes > Skimming (level of service) > Wait-time skim functions > Perceived initial wait
time

Perceived initial wait tim e

IWAITP(RouteSet)

See also: Skimming arguments and syntax

Computes the average actual time incurred at the start of the trip for all “attractive” routes
between zones, weighted by W AITFACTOR . It is calculated either from one or more wait
curves supplied by the WAITCRVDEF control statement, assigned to nodes by IW AITCURVE ,
or, for nodes that have not been assigned one, from a default wait curve.
Public Transport Program > Processes > Skimming (level of service) > Wait-time skim functions > Perceived transfer wait
time

Perceived transfer wait tim e

XWAITP(RouteSet)

See also: Skimming arguments and syntax

Computes the average actual time incurred at the transfer points of all “attractive” routes
between zones, weighted by W AITFACTOR . It is calculated either from one or more wait
curves supplied by the WAITCRVDEF control statement, assigned to nodes by
XW AITCURVE , or, for nodes that have not been assigned one, from a default wait curve.
Public Transport Program > Processes > Skimming (level of service) > Travel-time skim functions

T ravel-time skim functions

This section describes travel-time skim functions:
• Actual travel time

• Perceived crowded link travel time

• Perceived travel time

Public Transport Program > Processes > Skimming (level of service) > Travel-time skim functions > Actual travel time

Actual travel tim e

TIMEA(RouteSet, Mode)

See also: Skimming arguments and syntax

For transit modes, this skim computes the average in-vehicle run time for all “attractive”
routes between zones. It is taken from the network link data, factored by any line specific
factors.
For nontransit modes, this skim computes the average nontransit time (access, egress
and transfer) for all “attractive” routes between zones. It is taken from the nontransit legs
generated or read in by the GENERATE statements.
Public Transport Program > Processes > Skimming (level of service) > Travel-time skim functions > Perceived crowded link
travel time

Perceived cro wded link travel tim e

CWDCOSTP(RouteSet, Mode)

See also: Skimming arguments and syntax

- For transit modes, this skim extracts the average additional in-vehicle run time for all
"attractive" routes between zones. This is the run time that is above the basic calculated
in-vehicle time and arises due to crowding effects and crowd factors greater than 1.0. As
a perceived data skim, it is taken from the network link data and factored by any line
specific factors, RUNFACTOR and Crowding factor.
Public Transport Program > Processes > Skimming (level of service) > Travel-time skim functions > Perceived travel time

Perceived travel tim e

TIMEP(RouteSet, Mode)

See also: Skimming arguments and syntax

- For transit modes, this skim extracts the average in-vehicle run time for all "attractive"
routes between zones. It is taken from the network link data and factored by any line
specific factors, and RUNFACTOR.
For nontransit modes, this skim extracts the average nontransit time (access, egress
and transfer) for all “attractive” routes between zones. It is taken from the nontransit legs
generated or read in by the GENERATE statements and factored by RUNFACTOR .
Public Transport Program > Processes > Skimming (level of service) > Penalty skim functions

Penalty skim functions

This section describes penalty skim functions:
• Actual transfer penalty

• Perceived boarding penalty

• Perceived transfer penalty

Public Transport Program > Processes > Skimming (level of service) > Penalty skim functions > Actual transfer penalty

Actual transfer penalty

XFERPENA(RouteSet, Mode)

See also: Skimming arguments and syntax

Extracts the average actual transfer penalty for all “attractive” routes between zones. It is
taken from XFERPEN .
Public Transport Program > Processes > Skimming (level of service) > Penalty skim functions > Perceived boarding penalty

Perceived bo arding penalty

BRDPEN(RouteSet, Mode)

See also: Skimming arguments and syntax

Counts the boarding penalties associated with transit legs of the trip.
Public Transport Program > Processes > Skimming (level of service) > Penalty skim functions > Perceived transfer penalty

Perceived transfer penalty

XFERPENP(RouteSet, Mode)

See also: Skimming arguments and syntax

This skim is the average perceived transfer penalty for all “attractive” routes between
zones. It is the actual penalty as coded in XFERPEN , weighted by XFERFACTOR with
XFERCONST added.
Public Transport Program > Processes > Skimming (level of service) > Fare skim functions

Fare skim functions

This section describes fare skim functions:
• Monetary units

• Generalized cost units

Public Transport Program > Processes > Skimming (level of service) > Fare skim functions > Monetary units

M o netary units
FAREA(RouteSet, Mode)

See also: Skimming arguments and syntax

Extracts the average fare, in monetary units, for all “attractive” routes between zones. It
is calculated from the fare systems used by the “attractive routes.” Fares are calculated
either by transit leg or for a sequence of legs; in the latter case the fare is apportioned to
the legs in proportion to leg distance.
Public Transport Program > Processes > Skimming (level of service) > Fare skim functions > Generalized cost units

Generalized co st units
FAREP(RouteSet, Mode)

See also: Skimming arguments and syntax

Extracts is the average fare, in generalized cost units, for all “attractive” routes between
zones. The fare is calculated as for skim FAREA, from the fare systems used by the
“attractive routes,” and converted into generalized cost units with mode specific
VALUEOFTIME.
Fares are calculated either by transit leg or for a sequence of legs; in the latter case the
fare is apportioned to the legs in proportion to leg distance.
Public Transport Program > Processes > Skimming (level of service) > Other skim functions

Other skim functions

This section describes other available skim functions:
• Best trip time

• Boardings

• Composite cost

• Distance

• Excess demand

• Excess demand as a proportion

• Value of choice
Public Transport Program > Processes > Skimming (level of service) > Other skim functions > Best trip time

Best trip tim e

BESTJRNY

See also: Skimming arguments and syntax

Extracts the best actual trip time for zone pairs (that is, at each decision point, the best
choice is taken).
The trip time comprises:
• Walk time — taken from input or generated nontransit legs

• Average wait time — actual

• In-vehicle time — actual

• Boarding penalties

• Transfer penalties — actual

NOTE: The
route followed by this best actual trip may differ from that found using
BESTPATHONLY as the latter route is selected on cheapest perceived travel cost.
Public Transport Program > Processes > Skimming (level of service) > Other skim functions > Boardings

Bo ardings
BRDINGS(RouteSet, Mode)

See also: Skimming arguments and syntax

Extracts the average number of boardings used by the “attractive” routes between zone
pairs.
Public Transport Program > Processes > Skimming (level of service) > Other skim functions > Composite cost

Co m po site co st
COMPCOST(RouteSet)

See also: Skimming arguments and syntax

Measures the perceived costs of travelling between zone pairs using all “attractive”
routes. It takes into account all choices available at decision points (for example, walk or
alighting), and is appropriate for use in demand modeling and the evaluation of
schemes. It comprises:
• Walk time

• Wait time (including any crowding wait time)

• Boarding time

• Transfer time

• In-vehicle time (including any link-crowding effects)

• Fares (when PARAMETERS FARE=T)

Public Transport Program > Processes > Skimming (level of service) > Other skim functions > Distance

Distance
DIST(RouteSet, Mode)

See also: Skimming arguments and syntax

Extracts the average distance travelled by the “attractive” routes between zone pairs. It
is taken directly from the network link data.
Public Transport Program > Processes > Skimming (level of service) > Other skim functions > Excess demand

Excess dem and

EXCESSDEMAND

See also: Skimming arguments and syntax

Extracts the number of trips (from the demand matrix) which are unable to readily reach
their destination due to bottleneck points in the network where demand exceeds
capacity, and no viable alternative route is available. It is only available when crowd
modeling is performed, and wait time adjustments are used.
It highlights where the public transport system is unable to satisfy the demand flows
which are being loaded.
Public Transport Program > Processes > Skimming (level of service) > Other skim functions > Excess demand as a
proportion

Excess dem and as a pro po rtio n

EXCESSPROP

See also: Skimming arguments and syntax

Extracts the proportion of trips for each origin-destination pair which are unable to readily
reach their destination due to bottleneck points in the network where demand exceeds
capacity, and no viable alternative route is available. These trips would need to wait till
beyond the modeled period before being able to board their next transit leg.
This skim is only available when crowd modeling is performed, and wait time
adjustments are used.
The EXCESSDEMAND skim only gives cell values where demand exists and
bottlenecks prevent it reaching the destination. The EXCESSPROP skim highlights
movements where the public transport system could well have difficulty in meeting
demand (whether or not any demand exists in the loaded matrices).
Public Transport Program > Processes > Skimming (level of service) > Other skim functions > Value of choice

Value o f cho ice

ValOfChoice(RouteSet)

See also: Skimming arguments and syntax

Indicates level of choice available in the public transport system by computing average
travel cost skim minus the composite travel cost skim.
Sample calculation:
ValOfChoice(0) = ((IWAITP(0)+
XWAITP(0)+
TIMEP(0, ALLMODES)+
BRDPEN(0, ALLMODES)+
XFERPENP(0, ALLMODES))-
COMPCOST(0)
Expression contains additional terms when modeling fares or crowds.
Public Transport Program > Processes > Skimming (level of service) > Skim functions — quick reference

Skim functions — quick reference

This section provides a quick reference to the different types of skims or levels-of-
service matrices that can be extracted from the “attractive” routes between zones.
See also:
• “Skimming (level of service)” on page 720 for an introduction to Public Transport skimming.

• “Skimming arguments and syntax” on page 721 for detailed information on the functions
and syntax.

S umma ry o f s k im func tio ns

Func tio n D e s c rip tio n

BESTJRNY Skims best trip times

BRDINGS(RouteSet, Skims number of boardings

Mode)

BRDPEN(RouteSet, Skims boarding penalty (perceived)

Mode)

COMPCOST(RouteSet) Skims composite costs

CWDCOSTP(RouteSet, Skims crowding link travel times

Mode) (perceived)

CWDWAITA(RouteSet) Skims crowding wait times (actual)

CWDWAITP(RouteSet) Skims crowding wait times

(perceived)

DIST(RouteSet, Mode) Skims distance

EXCESSDEMAND Skims excess demand (where

demand exceeds capacity in
crowding model)

EXCESSPROP Skims excess proportion (where

demand exceeds capacity in
crowding model)

FAREA(RouteSet, Skims fares in monetary units

Mode)

FAREP(RouteSet, Skims fares in generalized time units

Mode)

IWAITA(RouteSet) Skims initial wait times (actual)

IWAITP(RouteSet) Skims initial wait times (perceived)

TIMEA(RouteSet, Skims travel time (actual)

Mode)

TIMEP(RouteSet, Skims travel time (perceived)

Mode)
ValOfChoice(RouteSet) Skims value of choice

XFERPENA(RouteSet, Skims transfer penalty (actual)

Mode)

XFERPENP(RouteSet, Skims transfer penalty (perceived)

Mode)

XWAITA(RouteSet) Skims transfer wait times (actual)

XWAITP(RouteSet) Skims transfer times (perceived)

Public Transport Program > Processes > Loading

Loading
During the loading process, the Public Transport program assigns passenger demand,
in the form of trips, to the attractive routes between zone pairs. These routes have their
probability of use determined by the route evaluation process with a series of models:
• Walk-choice model

• Service-frequency or the service-frequency-and-cost model

• Alternative-alighting model

The model theory is described in “Route-evaluation process” on page 965 and the
loading theory is described in “Loading process” on page 981.
Demand may be stratified by user class and loaded to enumerated routes generated
either by class or for the whole Public Transport network.
Loading is invoked by assigning, either input or generated trip matrices to TRIPSIJ[#], or
trips for individual zone pairs to the variable TRIPSIJ in the SELECTIJ phase.
The results of loading, passenger flows on lines, may be reported with the REPORT
statement. This can be done either in the run in which loading was performed or by
saving the loaded public transport network and reporting the loads in a subsequent run
of the program.
See “Public transport loading” on page 1024 for an example of this function.
Inp uts re q uire d fo r P ub lic T ra ns p o rt lo a d ing

• Public Transport network file, either produced by the current

run of the Public Transport program, or produced previously
and input with NETI.

• Route file, produced either by the current run of the Public

Transport program, or produced previously and input with
ROUTEI (for multiple user classes, enumerated routes files
input with ROUTEI[#]).
NOTE: If previously built NETI and ROUTEI files are input, they
must be compatible.
• Trips for loading onto the routes
These may be input as a trip matrix with MATI, or computed
during the run (for multiple user classes, trip matrix files input
with MATI[#]).

Outp uts p ro d uc e d b y P ub lic T ra ns p o rt lo a d ing

• A loaded Public Transport network with transit and nontransit

loads, which may be saved in the file designated by NETO.
This network may be displayed by Cube but not edited.
• Loaded nontransit legs, in ASCII format, which may be saved
 in the file designated by NTLEGO.

• Loaded lines, in ASCII format, which may be saved in the file

designated by LINEO.

• A table of link and their attributes, including loads, in DBF

format, which may be saved in the file designated by LINKO.
Public Transport Program > Processes > Loading > Associated phases

Asso ciated phases

• MATI
Public Transport Program > Processes > Select link

Select link
During the select-link process, the Public Transport program produces output matrices
of demand matching selection criteria, and can also perform select-link loading.
When you model multiple user classes, this process can produce select link outputs for
each class from the individual enumerated route files.
You can also use Cube Analyst to estimate Public Transport demand matrices. See
INTERCEPTO and SCREENLINEO in “FILEO” on page 825 for more information.

Inp uts re q uire d fo r P ub lic T ra ns p o rt s e le c t link

• A public transport network file, either produced by the current

run of the Public Transport program, or produced previously
and input with NETI.

• A route file, produced either by the current run of the Public

Transport program, or produced previously and input with
ROUTEI (for multiple user classes, enumerated routes files
input with ROUTEI[#])

NOTE: If you input previously built NETI and ROUTEI files, they must be compatible.

Outp uts p ro d uc e d b y P ub lic T ra ns p o rt s e le c t link

• A matrix file, MATO (for multiple user classes, matrix files,

MATO[#])

• Loadings, when only that demand which satisfies a select-

link criterion is loaded
Public Transport Program > Processes > Select link > Associated phases > Associated phases

Asso ciated phases

• SKIMIJ (mandatory)

• MATO
Public Transport Program > Processes > Select link > Select-link functions

Select-link functions
The select-link function provides a range of facilities to identify travel demand using
particular links, lines, or nodes in the network. Lines may be identified explicitly or
selected based on their mode or operator attributes. Throughout this section the
functionality is referred to by the generic term “select link” although in practice it offers a
wider range of selection mechanisms.
The select-link function outputs a matrix, containing that demand which satisfies the
selection criteria. In a run, you may specify a series of selection criteria, each one being
associated for output purposes with a different working matrix. You can save the
resulting matrices to the FILEO MATO[n] where n is the user class being evaluated
(that is, select link results are saved to the same matrix file as skim outputs).
The process normally considers just transit legs using the link/line, or passing the node.
However, if required nontransit legs may be considered, or for nodes the activity may be
restricted to specific movements (for example, boarding a transit line).
The select-link criteria are defined as expressions, which allows compound conditions
(using and / or / not operations) to be specified.
You may specify additional keywords in the expression to obtain either percentage or
proportion of demand (rather than actual demand flow) satisfying the criteria. These
allow you to obtain results when demand flows for an I-J pair are zero.
The demand flows loaded onto the network may be restricted to just that demand which
meets the selection criteria. This permits the display of demand and loadings which use
the selected link. Where several select link functions are used in a run only one of them
may contain the keyword which triggers select-link based loading.
The general form of the select-link function is:
SELECTLINK (expression)

where the expression defines the selection criteria. This general form typically appears
on the right hand side of a COMP (compute) statement which sets the value of cells in a
particular working matrix, for example:
MW[MatrixNumber] = SELECTLINK (expression)

The compute command is coded as part of the SKIMIJ phase.

Where no route is found for an I-J pair all select link functions will return zero values.
As a general rule, working variables or results of COMP commands may not be used to
specify values which form part of a selection expression. The values required by the
user must be specified directly in the script, or obtained from scenario keys (by
substitution into the script).
This topic discusses:
• Selection for particular links

• Select line

• Select node

• Select mode

• Select operator

• Combining selection criteria together

• Using simultaneous selection criteria

• Use of the “not” and “not equals” operators

• Selecting particular types of movement

• Obtaining matrices of proportion or percentage of demand meeting a criterion

• Loading the select link demand

Public Transport Program > Processes > Select link > Select-link functions > Selection for particular links

Selectio n fo r particular links

To select demand traversing a link, the expression takes the form

L = ANode-BNode

This identifies all demand traversing the link in the direction from the given A-node to the
B-node. To identify demand in either direction along the link a “*” is appended to the
specification:
L = ANode-BNode*

Examples:
MW[1] = SELECTLINK(L=1023-1027)

selects demand traversing the link 1023 to 1027 in that direction, whereas:
MW[2] = SELECTLINK(L=1025-1028*)

selects demand traveling along the link in either direction.

The expression used may contain a list of link specifications, which are separated by
commas (or alternatively spaces). If a list is defined, using any one of the links turns the
selection criterion to “true.” For example:
MW[3] = SELECTLINK(L=101-102, 104-105*, 107-109)

selects demand if one of the links 101 to 102, 104 to 105, 105 to 104 or 107 to 109 is on
the path. The use of comma between link specifications is optional, and may be
replaced by a space character.
Selection criteria which require the use of two or more links are described below.
Public Transport Program > Processes > Select link > Select-link functions > Select line

Select line

To select demand using a particular line, the expression takes the form:
LINE = LineName

Use of two or more line names in a list is permitted, and when used the selection criteria
is true if any one of the listed lines is used.
Line names may contain masks of a single trailing “*” or one or more trailing “?.” The
leading nonmasked portions will then be compared for selection purposes. Use the “*”
for multiple columns. For example:
LINE = MUNI*

matches line names such as MUNI, MUNICENTRAL, and MUNINORTH. Use the “?” for
single characters. For example:
LINE = MUNI-??

would match line names MUNI-01 and MUNI-02.

Examples:
MW[1] = SELECTLINK(LINE=RED1)

selects demand using the line which has name RED1.

MW[2] = SELECTLINK(LINE=A*, B*)

selects lines with names beginning with either A or B.

Public Transport Program > Processes > Select link > Select-link functions > Select node

Select no de

To select demand passing through a particular node, the expression takes the form:
N=NodeNumber

Lists of nodes may be used, and ranges of nodes may be specified using ‘-‘.
Examples:
MW[1] = SELECTLINK(N=107,200-208)

selects demand which passes through node 107 or any of the nodes in the range 200 to
208. The selection considers transit legs which start at, pass through, or finish at the
specified node(s).
Public Transport Program > Processes > Select link > Select-link functions > Select mode

Select m o de

To select demand which uses a particular mode, the expression takes the form:
MODE = ModeNumber

The mode number may be a transit mode (in which case demand using lines of that
mode are selected) or can be a nontransit mode. Lists and ranges may be used when
specifying the required modes. Tests using not equals (!= or <>) are permitted with
mode conditions.
For example:
MW[5] = SELECTLINK(MODE=3,5,7-9)

selects demand which uses any of modes 3,5,7,8 or 9.

Public Transport Program > Processes > Select link > Select-link functions > Select operator

Select o perato r

To select demand which uses lines from a particular operator, the expression takes the
form:
OPERATOR = Number

Lists and ranges of numbers may be used when specifying the required operators.
Tests using not equals (!= or <>) are permitted with operator conditions.
Example:
MW[7] = SELECTLINK(OPERATOR=3)

selects all demand on lines run by the operator having an identification number of 3.
Public Transport Program > Processes > Select link > Select-link functions > Combining selection criteria together

Co m bining selectio n criteria to gether

You can combine two or more select-link criteria to form compound conditions. Use the
“and” operator (& or &&) and “or” operator (| or ||) to combine simple conditions.
The use of | (or) operators may sometimes be avoided when the same data type is
referred to in both tests. The example:
MW[5] = SELECTLINK(L=401-402 | L=421-422)

gives exactly the same results as:

MW[5] = SELECTLINK(L=401-402, 421-422)

Two tests based on link-selection criteria may readily be combined using the “and”
operator. For example:
MW[3] = SELECTLINK(L=101-103 & L=108-109)

selects demand which travels along both link 101 to 103 and 108 to 109. In evaluating
this test it does not matter which of the links is traversed first; it is use of both of them
which sets the selection to “on.”
In a similar manner:
MW[4] = SELECTLINK(LINE=RED2 & LINE=BLUE7)

selects demand which uses both line RED2 and also line BLUE7. Again, which is used
first does not matter.
When combining tests using two data types it is also necessary to consider how the
conditions interrelate. As an example, consider how you might combine a test on a link
with a test on a line. You might wish to specify that the link was used (somewhere in the
trip) and that the line was also used (at some point in the trip). These conditions are
independent of each other. Alternatively the requirement may be that the line was used
to traverse the specified link; this is a “simultaneous condition” where two or more
conditions must all apply at one point in the trip, and such conditions are considered in
the following section.
Where the selection criteria are independent, use of the “and” operator is appropriate.
For example:
MW[6] = SELECTLINK(L=211-234 & LINE=GREEN)

treats the two conditions as independent tests, so that demand is selected if the link 211
to 234 is traversed and also (but not necessarily at the same time) the GREEN line is
used.
Public Transport Program > Processes > Select link > Select-link functions > Using simultaneous selection criteria

Using sim ultaneo us selectio n criteria

Where two conditions apply simultaneously the operator, use “+” to combine them.
Such simultaneous conditions are combined together before any “&” and “|” operators
are evaluated.
For example:
MW[2] = SELECTLINK((L=101-102 + LINE=RED) &
(L=201-202 + LINE=BLACK))

selects demand which uses line RED on link 101 to 102 and also uses line BLACK on
link 201 to 202. The use of brackets around each simultaneous condition is optional;
brackets ease reading of the condition groups, and may be omitted without affecting the
results.
The “+” operator is typically used to combine:
• Link conditions with line, mode, or operator conditions

• Node conditions with line, mode, or operator conditions

• Any condition with criteria determining type of movement or leg considered (as described
below)
Public Transport Program > Processes > Select link > Select-link functions > Use of the “not” and “not equals” operators

Use o f the “no t” and “no t equals” o perato rs

Use care with negated conditions. The “not equals” operator (!= or <>) is not permitted
in link or node expressions (that is, L or N expressions).
When using negated tests with line conditions, it is often appropriate to use an
expression of the form !(LINE=RED) which means “did not use line RED.”
Use of “not equals” may give results which do not exactly match your intentions. For
example, the condition LINE != RED means “used lines other than RED.” If considering a
two-leg trip where line RED used on the first leg, then this condition would be true as
some line other than RED is used on the second leg.
Public Transport Program > Processes > Select link > Select-link functions > Selecting particular types of movement

Selecting particular types o f m o vem ent

The normal operation of select link considers transit legs (passing along a link or at a
node), unless mode selection criteria have been specified. You can amend this default
behavior, allowing the selection criteria to consider particular types of movement. These
are specified in the select link expression by a TYPE keyword (which is usually part of a
simultaneous condition, linked by “+” operator to the associated link or node condition).
For conditions using link selection (that is, L= conditions) the TYPE keyword can take
either of the following values.
• NTINCLUDED — To consider transit and nontransit legs traversing the link

• NTONLY — To select just nontransit legs

The link specification will select nontransit legs which either traverse the specified link (if
XN values are available in NTLEG data for intermediate nodes), or when no XN data is
available the start and end points of the nontransit leg correspond to the link
specification. The TYPE keyword may not be followed by a “not-equals” (!= or <>)
operator.
For conditions using node selection (that is, N= conditions) the TYPE keyword can take
the following values
• THRU — To consider transit legs passing through the node

• BOARD — To consider transit legs boarded at the node

• ALIGHT — To consider transit legs alighted from at the node

• NTTHRU — To consider nontransit legs passing through the node. The nontransit legs
selected will be those which have the specified node in their list of XN values.

The condition may use a list of two or more of these settings to select movements where
any of the listed types apply. The TYPE keyword may not be followed by a “not-equals”
(!+ or <>) operator.
The following examples illustrate use of the TYPE keyword:
• MW[1] = SELECTLINK(L=101-102 + TYPE = NTINCLUDED)

Selects all journeys travelling along link 101 to 102, whether using a transit line or
nontransit (for example, walking).
• MW[2] = SELECTLINK((N=123 + TYPE=ALIGHT) &
(N=123 + TYPE=BOARD))

Selects all journeys which both alight and board at node 123 (that is, they make an
interchange between lines at that node).
• MW[2] = SELECTLINK(N=123 + TYPE=ALIGHT)

Selects all journeys which alight at node 123; following that they may board another
line there, walk to another node to board a line, or egress from the public transport
system to reach a destination zone.
• MW[2] = SELECTLINK (N=123 + LINE = X + TYPE = BOARD)

Selects just the demand boarding line X at node 123.

• MW[5] = SELECTLINK(N=579 + TYPE = THRU,ALIGHT)

Selects all transit demand arriving at node 579 (whether they alight or continue on the
line).
Public Transport Program > Processes > Select link > Select-link functions > Obtaining matrices of proportion or
percentage of demand meeting a criterion

Obtaining m atrices o f pro po rtio n o r percentage o f dem and m eeting a criterio n

The select process typically returns the demand for an I-J pair which satisfies a
selection criterion. The proportion of demand meeting the criterion may be obtained by
including the PROBABILITY keyword in the expression (that is, PROBABILITY=T). Similarly,
percentages may be obtained by using the PERCENT keyword (that is, PERCENT=T). As an
example:
MW[3] = SELECTLINK(LINE=TRAM1, PERCENT=T)

Returns percentage values for each I-J pair which use the line TRAM1.
Public Transport Program > Processes > Select link > Select-link functions > Loading the select link demand

Lo ading the select link dem and

The select-link process may load the portion of total demand meeting a select link
criterion, rather than loading the entire demand as specified by the parameter TRIPSIJ.
This is invoked by including the keyword and setting LOAD=T in the select link expression.
As an example:
MW[2] = SELECTLINK(L=303-307*, LOAD=T)

Although a program run may include several SELECTLINK functions, only one of these
may be used to trigger select-link loading.
Where crowding is modeled, the restriction using selection criteria applies to the last
iteration, so the crowding is based on complete loadings.
If skims are obtained when performing select-link loading, then the skims are obtained
for all evaluated routes (that is, they are not restricted to the subset of routes which
match the select link criteria).
Public Transport Program > Processes > Loading analyses

Loading analyses
During the loading-analyses process, the Public Transport program presents further
reports of transit and nontransit passenger loadings than those performed during the
loading process. Any request for loading analyses automatically invokes a loading
process.
As with the loading process, demand stratified by user class produces loading analyses
for each class.
Loading analyses are associated with the MATI phase.
The analyses currently available are:
• Transfers between modes

• Transfers between operators

• Stop-to-stop movements
Public Transport Program > Processes > Loading analyses > Transfers between modes

Transfers between m o des

Reports produced if loading is performed and output to the main print file:
• Passenger transfers between transit and nontransit modes

• Passenger transfers between transit modes

Public Transport Program > Processes > Loading analyses > Transfers between operators

Transfers between o perato rs

Report produced if loading is performed and output to the main print file:
• Passenger transfers between transit and nontransit modes
Public Transport Program > Processes > Loading analyses > Stop-to-stop movements

Sto p-to -sto p m o vem ents

Several types of stop-to-stop movements may be extracted, either for a selection of

stops, or groups of stops:
• First entry/last exit

• Adjacent

• All on/off combinations

The first two can be obtained by mode or for all modes. You can save this analysis to a
DBF file with FILEO STOP2STOPO .
Public Transport Program > Processes > Crowd modeling

Crowd modeling
During the crowd-modeling process, the Public Transport program iteratively balances
loaded demand against capacity. At each iteration, the program completes the route-
evaluation and loading processes, which are repeated for all user classes, and then
adjusts the costs in the model to reflect the assigned loads. The iterative process may
use either, or both, of the crowd modeling procedures:
• Link travel time adjustment

• Wait time adjustment

See “Crowding” on page 996 for information about the theory of crowding models.
When crowd modeling is performed, the results obtained from the last iteration (in the
form of loaded flows, printed reports, and skims) provide the model outputs.
Public Transport Program > Phases

Phases
The Public Transport program executes its main processes—data processing and
modeling—within a series of phases. You control all the phases and can initiate
additional, context-sensitive computations within them.
The phases, presented in the order they would normally be implemented, are:
• NODEREAD — Computes node based variables.

• LINKREAD — Computes link based variables.

• DATAPREP — Prepares the public transport network for modeling.

• MATI — Computes trips for loading.

• SELECTIJ

• SKIMIJ — Extracts skims and select link results, saving them, generally in working matrices.

• MATO — Manipulates and reports skim, select-link, and loading-analyses matrices.

The NODEREAD, LINKREAD, MATI, and MATO phases provide data manipulation
facilities, and are secondary to the main functions of the Public Transport program. They
are optional.
You specify the exact configuration for the Public Transport program to run through a
combination of phases and control statements.
Control statements provide information and instructions to the program. In the Public
Transport program, control statements are either static or dynamic. Static statements
may be present anywhere in the job stream; the program evaluates them once. Dynamic
statements may be present only within phases; the program evaluates them as
encountered, during the execution of the phases.
Only context-sensitive dynamic control statements are available to the phases; a list of
valid statements is provided with the description of each phase. See “Control
statements” on page 759 for more information.
You only must code phases that contain control statements; you need not code empty
or null phases.
Specify phases in a script as follows:
PHASE=DATAPREP
;Generate access/egress legs
GENERATE
...
...
 ;End of GENERATE
ENDPHASE

Regardless of the functionality selected for any run of the Public Transport program, a
requirement is that a network, basic or public transport, is always input. This is read and
set up at the start of each run; no user intervention is required.
A diagram showing how the phases would be used in a typical public transport model
follows:
Public Transport Program > Phases > NODEREAD

NODEREAD
In the NODEREAD phase, you can compute node-based information from the input
network’s node attributes with NETI. This information is for use primarily in the
DATAPREP phase but is available in later phases if the DATAPREP phase is active.
The control statements within the NODEREAD phase are executed once per node. Only
one NODEREAD phase is permitted per run.
The computed variables may be scalars or vectored by node. The use of a vectored
variable produces an array containing a computed value for each node. Vectored
variables have the case insensitive prefix “nw.”
The evaluated expression may contain any valid variables, numeric or string, and node
based variables from the input network. Input node variable names must have the case
insensitive prefix “ni.”
An example of a computed node variable is:
NW.XplusY = NI.X + NI.Y

Computed variables are available for the duration of the run but not saved back to the
network.
See “Example 2: Preparing a public transport network from TRIPS link data” on
page 1019 for an example of this phase.
Public Transport Program > Phases > NODEREAD > Control statements available in this phase

Co ntro l statem ents available in this phase

ABORT
BREAK
COMP

CONTINUE
EXIT
GOTO
IF... ELSEIF ... ELSE ... ENDIF
LOOP ... ENDLOOP
PRINT
Public Transport Program > Phases > NODEREAD > Public Transport variables available in this phase

Public Transpo rt variables available in this phase

ZONES
Public Transport Program > Phases > LINKREAD

LINKREAD
In the LINKREAD phase, you can compute link-based information from the input
network’s link attributes with NETI. This information is for use primarily in the DATAPREP
phase but is available in later phases if the DATAPREP phase is active.
The control statements within the LINKREAD phase are executed once per link. Only
one LINKREAD phase is permitted per run.
The computed variables may be scalars or vectored by link. The use of a vectored
variable produces an array containing a computed value for each link. Vectored
variables have the case insensitive prefix “lw.”
The evaluated expression may contain any valid variables, numeric or string, and node
based variables from the input network. Input link variable names must have the case
insensitive prefix “li.”
An example of a computed link variable is:
LW.GCTime = LI.Time * 1.5

Computed variables are available for the duration of the run but not saved back to the
network.
See “Example 2: Preparing a public transport network from TRIPS link data” on
page 1019 for an example of this phase.
Public Transport Program > Phases > LINKREAD > Control statements available in this phase

Co ntro l statem ents available in this phase

ABORT
BREAK
COMP

CONTINUE
EXIT
GOTO
IF... ELSEIF ... ELSE ... ENDIF
LOOP ... ENDLOOP
PRINT
Public Transport Program > Phases > LINKREAD > Public Transport variables available in this phase

Public Transpo rt variables available in this phase

ZONES
LINKNO
Public Transport Program > Phases > DATAPREP

DATAPREP
The DATAPREP phase invokes the Public Transport network development process
and provides the mechanism for generating and/or reading nontransit legs.
You can develop nontransit legs with one or more GENERATE control statements, or you
can produce them externally to the Public Transport program and input them in this
phase.
You can compute data for nontransit leg generation from the input network with the COMP
statement.
See “Public transport network development” on page 1017 for examples of this phase.
Public Transport Program > Phases > DATAPREP > Control statements available in this phase

Co ntro l statem ents available in this phase

ABORT
BREAK
COMP

CONTINUE
EXIT
GENERATE
GOTO
IF... ELSEIF ... ELSE ... ENDIF

LINKLOOP ... ENDLINKLOOP

LOOP ... ENDLOOP
PRINT
Public Transport Program > Phases > DATAPREP > Public Transport variables available in this phase

Public Transpo rt variables available in this phase

ZONES
Public Transport Program > Phases > MATI

MATI
The MATI phase produces working matrices, (MW[#]), from FILEI MATI matrices
(MI.#.name), although COMP statements can also compute working matrices.
The MATI phase is executed for each origin zone, I, before the route evaluation,
skimming, loading, and loading analyses processes are done for each zone pair, I-J.
This phase provides a flexible mechanism for generating and manipulating one row of a
matrix at a time. You might use this phase to:
• Examine the matrix input with FILEI MA T I, one row at a time, and determine if there is
anything specific about zone I that could affect further processing for that zone. For
example, if MA T I points to a highway network matrix, and the matrix indicates that there is
no highway access for zone I, you might set a variable for zone I and test in the SELECTIJ
phase.

• Compute a row of trips, from an origin zone (I) to all zones (J), using the COMP statement
and the built-in ROW functions, and save the trips in a working matrix, MW [#], for subsequent
loading. You can also do this in the SELECTIJ phase, but for a zone pair at a time. The
working matrix is designated for loading with PARAMETERS TRIPSIJ[userclass].

• Input matrices external to the Public Transport program with FILEI MA T I, and then
manipulate, report, and save those matrices with FILEO MA T O . You can merge highway skims
with skims extracted in the Public Transport program run.

The working matrix may be reported with the PRINTROW statement. With the BREAK
statement, you can use the MATI phase to select zones for processing.
See “Public transport loading” on page 1024 for an example of this phase.
Public Transport Program > Phases > MATI > Control statements available in this phase

Co ntro l statem ents available in this phase

ABORT
BREAK
COMP

CONTINUE
EXIT
GOTO
IF... ELSEIF ... ELSE ... ENDIF
JLOOP ... ENDJLOOP

LOOP ... ENDLOOP

PRINT
PRINTROW
Public Transport Program > Phases > MATI > Public Transport variables available in this phase

Public Transpo rt variables available in this phase

ZONES
USERCLASS
I
J
Public Transport Program > Phases > SELECTIJ

SELECTIJ
The SELECTIJ phase selects pairs of zones, I-J, for bypassing the route-evaluation
process.
The ROUTEI and ROUTEO subkeywords I, J, and SELECTBYMAT provide the first line of
selection but they do not control specific I-J combinations. The SELECTIJ phase allows
a finer selection of specific I-J combinations, although if the I-J combination is precluded
by the values on the ROUTEI and ROUTEO, that I-J pair is not available to this phase.
The Public Transport program executes the SELECTIJ phase prior to the route-
evaluation process for the I-J pair. (Route evaluation is a time consuming process,
therefore judicious use of this phase can have a significant impact on overall processing
time.)
Only zone pairs for evaluated routes are available for the skimming, loading, and loading
analyses processes.
This phase can compute the trips to be loaded for each I-J pair. For example:
PHASE=SELECTIJ
if(I < 10) CONTINUE
if(J > 10) BREAK
TRIPSIJ=MI.1.1 * 0.75
PRINT LIST=I,J,TRIPSIJ
ENDPHASE

In this fragment of code, the I-J pairs loaded range from I=10‑ZONES to J=1-9. The trips
to be loaded are computed from the input trip matrix and reported.
Public Transport Program > Phases > SELECTIJ > Control statements available in this phase

Co ntro l statem ents available in this phase

ABORT
BREAK
COMP

CONTINUE
EXIT
GOTO
IF... ELSEIF ... ELSE ... ENDIF
PRINT
PRINTROW
Public Transport Program > Phases > SELECTIJ > Public Transport variables available in this phase

Public Transpo rt variables available in this phase

ZONES
USERCLASS
I
J
Public Transport Program > Phases > SKIMIJ

SKIMIJ
The SKIMIJ phase extracts skims and select-link outputs with special functions
described in “Select-link functions” on page 735, then saves them, generally in working
matrices with the COMP M W [#] statement.
The Public Transport program invokes SKIMIJ for each zone pair, I-J, immediately after
route evaluation.
See “Public transport skimming” on page 1022 for an example of this phase.
Public Transport Program > Phases > MATO

MATO
In the MATO phase, the Public Transport program revises, combines, reports and writes
work matrices to the FILEO M ATO files.
The program executes this phase once for each origin zone, I, after completing the route
evaluation, skimming, loading, and loading analyses processes for all destination zones
of that origin zone.
Generally, you use the MATO phase with the matrices produced by the skimming and
loading analyses phases, but you can also process other working matrices similarly.
You can manipulate matrices with the COMP statement and a set of built-in ROW
functions, and create a report with the PRINTROW statement. With the BREAK statement,
you can use the MATO phase to select zones for processing.
See “Public transport skimming” on page 1022 for an example of this phase.
Public Transport Program > Phases > MATO > Control statements available in this phase

Co ntro l statem ents available in this phase

ABORT
BREAK
COMP

CONTINUE
EXIT
GOTO
IF... ELSEIF ... ELSE ... ENDIF
JLOOP ... ENDJLOOP

LOOP ... ENDLOOP

PRINT
PRINTROW
Public Transport Program > Phases > MATO > Public Transport variables available in this phase

Public Transpo rt variables available in this phase

ZONES
USERCLASS
I
J
Public Transport Program > Control statements

Control statements
Control statements provide instructions and information to the Public Transport program.
The Public Transport program has two types of control statements:
• Static — Evaluated only once, at the start of each run, regardless of their location in the
script. Citilabs recommends keeping static control statements together at the beginning of
the script file. Examples of static control statements include FILEI, FILEO, PARAMETERS , and
REREPORT. Some static statements are provided in files, not in the job script (that is, LINE,
MODE, FACTORS ).

• Dynamic — Evaluated as encountered. These may only be present in the processing

phases. Phases only permit context-sensitive control statements; see each phase’s
description in “Phases” on page 747 for a list of valid statements. Examples of dynamic
control statements include LINKLOOP ... ENDLINKLOOP, JLOOP ... ENDJLOOP, PRINT, GENERATE.

The control statements available in the Public Transport program are listed below. Some
are specific to this program while others are available throughout Cube Voyager.

Co ntro l s ta te me nt A v a ila b ility T ype

ABORT Cube Voyager Dynamic

BREAK Cube Voyager Dynamic

COMP Cube Voyager Dynamic

CONTINUE Cube Voyager Dynamic

CROWDCRVDEF

CROWDMODEL Public Static

Transport

EXIT

FACTORS Public Static

Transport

FARESYSTEM Public Static

Transport

FILEI Cube Voyager Static

FILEO Cube Voyager Static

GENERATE Public Dynamic

Transport

GOTO Cube Voyager Dynamic

IF... ELSEIF ... ELSE ... ENDIF Cube Voyager Dynamic

JLOOP ... ENDJLOOP Cube Voyager Dynamic

LINE Public Static
Transport

LINKLOOP ... Public Dynamic

ENDLINKLOOP Transport

LOOP ... ENDLOOP Cube Voyager Dynamic

MODE Public Static

Transport

NT Public Static
Transport

OPERATOR Public Static

Transport

PARAMETERS Public Static

Transport

PRINT Cube Voyager Dynamic

PRINTROW Cube Voyager Dynamic

PTRUN Public Static

Transport

REPORT Cube Voyager Static

REREPORT Public Static

Transport

VEHICLETYPE

WAITCRVDEF Public Static

Transport
Public Transport Program > Control statements > ABORT

ABORT
Terminates a run. Keywords include:
• MS G

Usage is:
ABORT MSG = text

A B OR T k e y wo rd

Ke y wo rd D e s c rip tio n

MSG |S| Optional. Message printed when

the program terminates. For
readability, Citilabs recommends
100 characters or less.
Public Transport Program > Control statements > ABORT > Example

Exam ple

Before generating access and egress legs in the DATAPREP phase, this script checks
that the speed of links that may be used for walking is between 0 and 5 km/h. If the script
finds links outside this range, the script reports the links and aborts the run with an
appropriate message.
PHASE=DATAPREP
LnkCnt = 0
LINKLOOP
if((li.a <=24 || li.b <=24) && (lw.WalkSpeed <= 0 || lw.WalkSpeed > 5.0 ))
LnkCnt=LnkCnt+1
print list=li.a, li.b, lw.WalkSpeed
endif
ENDLINKLOOP
print list= 'Number of access/egress links with invalid walk speeds = ', LnkCnt
if(LnkCnt>0) abort msg = Access/Egress Links with invalid walk speeds
;Generate access legs only if walk costs coded on links
GENERATE......
ENDPHASE
Public Transport Program > Control statements > BREAK

BREAK
Breaks out of a loop.
Upon encountering BREAK, the script immediately passes control to the statement after
the associated loop.
If BREAK is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the
statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP
(J is reset to 1).
If BREAK is not within a LOOP or JLOOP block, the script terminates processing for the I
zone but does not bypass output and zonal reporting statistics.
When used within the Public Transport program’s MATI or MATO phases, BREAK
bypasses any more processing for the relevant I zone, breaks out of the I-loop, and
bypasses end-of-zone processing for zone I.
Public Transport Program > Control statements > BREAK > Example 1

Exam ple 1

Loop terminates if “condition 1” is not met, regardless of the value of L1. When
“condition 2” is met, control passes to the following IF statement and processing for zone
I ceases.
LOOP L1=1,3
IF (condition 1)
statements
ELSE
BREAK
ENDIF
ENDLOOP
IF (condition 2) BREAK
Public Transport Program > Control statements > BREAK > Example 2

Exam ple 2

MATI selects zones 1 to 19 for processing, ignoring all other zones. BREAK terminates
the I-loop at zone 20 for each user class, enabling no further processing. The route-
evaluation, skimming, loading, and loading-analyses processes are completed for loop J
within loop I. Therefore, they would be done only for zones 1-19.
PHASE=MATI
IF(I==20) BREAK
MW[1] = MI.1.1
ENDPHASE
Public Transport Program > Control statements > BREAK > Example 3

Exam ple 3

MATO selects zones 1 to 19 for reporting, manipulating matrices, and saving matrices to
file. BREAK terminates the loop at the 20th zone. Therefore, the route-evaluation,
skimming, loading, and loading-analyses processes effectively stop after the 19th zone
for each user class. (Because MATO follows the processes, the processes will run for
zone 20 but will not save any matrices produced.)
PHASE=MATO
IF(I==20) BREAK
MW[1] = MW[1] * 1.2
ENDPHASE
Public Transport Program > Control statements > COMP

COMP
Computes a variable, matrix, or matrix element from an expression. Keywords and sub-
keywords include:
• MW
m EXCLUDE
m INCLUDE

• VAR

Usage is:
VAR=expression
MW[n]=expression, INCLUDE=list of J zones, EXCLUDE=list of J zones

Expressions are either numeric formulas or selection criteria. See “Expressions” on

page 33 for more details. Numeric expressions can use built-in functions that operate on
numeric, string, or row data and return a value. Built-in functions must be followed by
one, or more, arguments enclosed within parentheses (). The number of arguments
must match the requirements of the function. Built-in functions include:
• Numeric functions (see “Numeric functions” on page 35)

• String functions (see “Character/ String functions” on page 39)

• Row-based functions, which process the cells in a row (see “Matrix function descriptions”
on page 581)

NOTE: You cannot use row-based functions within a J-loop.

• Skimming functions, which produce skim (level of service) matrices of total trip costs and
their components (see “Skimming (level of service)” on page 720)

COMP k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

MW |KD| Optional. Value for a working

matrix. You can specify this
keyword in two formats:
• MW[n] — Defines the index n
of a working matrix. Matrices
can contain up to MAXMW
sub -matrices, as indexed by
n. The index n may be either
a constant or a variable
name.
The program solves the
 expression for all values of J (1
through Zones), filtering values
indicated by any INCLUDE or
EXCLUDE lists on this
statement.
Within a JLOOP statement, the
program only solves the
expression one time only, with
J being the value of the loop’s
current J.
• MW[n][o] — Defines the value
for column o in working matrix
n. The second index, o, must
be between one and Zones.
The program solves the
expression one time only,
with J being the loop’s J if
within a JLOOP, or 1, if not.

MW EXCLUDE |I| Optional. Values of J excluded

when computing the MW[n]
expression. As the program
internally loops on J, the program
compares J to the values in the
EXCLUDE list. If the current J is on
the list, the program does not
evaluate or store the expression for
that J.
Specified values can range from 1
to the highest zone number.
Filter applies to all MW[n] values
on the COMP statement.
Not permitted if COMP statement
within JLOOP ... ENDJLOOP block.
Always processed after INCLUDE
subkeyword.
By default no zones are excluded.

MW INCLUDE |I| Optional. Values of J included

when computing the MW[n]
expression. As the program
internally loops on J, the program
compares J to the values in the
INCLUDE list. If the current J is not
on the list, the program does not
evaluate or store the expression for
that J.
Specified values can range from 1
to the highest zone number.
Filter applies to all MW[n] values
on the COMP statement.
Not permitted if COMP statement
within JLOOP ... ENDJLOOP block.
By default all zones are included.

VAR |K| Optional. Variable that stores result

of an expression.
The program evaluates each
encountered expression (for
example, each node in the
NODEREAD phase or each link in
the LINKREAD phase). If the result
is a character string, the variable
must be a character string variable.
The COMP statement sets a
variable type to the result of the
variable’s first evaluated
expression.
Examples of variables are:
abc = '123'
def = 123
abc = def ;invalid: abc has been
declared a string
abc = abc+'456' ;valid
abc = abc+def ;messy -- do not
mix types
jkl = 1 ;jkl is declared numeric
jkl = xyz ;invalid: xyz is
declared a string (later)
xyz = 'xyz' ;xyz is declared a
string
The program does not always
compute expressions for variables
that are not used as input to some
process. In the above examples,
the statements with jkl= might never
be executed, because jkl is never
used.
Public Transport Program > Control statements > COMP > Examples of computation statements in Public Transport

Exam ples o f co m putatio n statem ents in Public Transpo rt

This example reports the nonzero rows of a selection of skim matrices.

Phase=MATO
if (ROWSUM(2) > 0) PRINTROW MW=2 TITLE='Compcost', BASE1=T, FORM=10.2
if (ROWSUM(3) > 0) PRINTROW MW=3 TITLE='ValOfChoice', BASE1=T, FORM=10.2
if (ROWSUM(4) > 0) PRINTROW MW=4 TITLE='IWAITA', BASE1=T, FORM=10.2
if (ROWSUM(5) > 0) PRINTROW MW=5 TITLE='XWAITA', BASE1=T, FORM=10.2
if (ROWSUM(6) > 0) PRINTROW MW=6 TITLE='IWAITP', BASE1=T, FORM=10.2
Endphase

Compute average perceived trip cost skim from its components.

Phase=SKIMIJ
MW[1]= IWAITP(0)
MW[2]= XWAITP(0)
MW[3]= TIMEP(0,ALLMODES)
MW[4]= BRDPEN(0,ALLMODES)
MW[5]= XFERPENA(0, ALLMODES)
Endphase

Phase=MATO
x=ROWADD(6,1,2,3,4,5)
PRINTROW MW=6 TITLE='AVJRNYCOST', BASE1=T, FORM=10.2
Endphase

Determine the highest node number in the public transport system, using standard
function MAX.
HighestNodeNum = MAX(HighestNodeNum, Anode, Bnode)
Public Transport Program > Control statements > CONTINUE

CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements.
If CONTINUE is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the
appropriate ENDLOOP or ENDJLOOP statement. Otherwise, processing for the I zone is
terminated, but output and zonal reporting statistics will not be bypassed.
Public Transport Program > Control statements > CONTINUE > Example 1

Exam ple 1
LOOP L1=1,3
IF (!(condition 1)) CONTINUE
ENDLOOP

In this user-controlled loop, control is passed to the ENDLOOP when “condition 1” is not
met, bypassing any statements between the IF and ENDLOOP, for that value of L1.
Public Transport Program > Control statements > CONTINUE > Example 2

Exam ple 2
IF (condition) CONTINUE

This statement is used in an explicit or implicit loop over I. If the condition is met, no more
Js will be processed for the I zone, except output and zonal summaries.
Public Transport Program > Control statements > CONTINUE > Example 3

Exam ple 3
LOOP L2=K1,K2,KINC
JLOOP EXCLUDE=25-50,88
IF (condition 1) CONTINUE
....
ENDJLOOP
LOOP L3=L2,L2+5
IF (condition 2) CONTINUE
.....
ENDLOOP
ENDLOOP

JLOOP processing is bypassed for the Js for which “condition 1” is met; similarly, LOOP
processing is bypassed for the L3s for which “condition 2” is met. The outermost LOOP
operates over the full range of L2, from K1 to K2, incrementing in steps of KINC.
Public Transport Program > Control statements > CONTINUE > Example 4

Exam ple 4
PHASE=SELECTIJ
IF(I<403)CONTINUE
IF(I>455)BREAK
IF(J<403)CONTINUE
IF(J>455)BREAK
ENDPHASE

The SELECTIJ phase selects zone pairs, I and J, 403-455 for processing. The first
CONTINUE bypasses origin (I) zones 1-402 and the second one bypasses destination (J)
zones 1-403. The first BREAK stops the I-loop after zone 455 and the second stops each
J-loop after zone 455.
Public Transport Program > Control statements > CROWDCRVDEF

CROWDCRVDEF
Defines crowding curves, used to compute crowded travel time for particular
combinations of transit lines and user-class. Keywords include:
• CU R V E

• LON GN A ME

• N A ME

• N U MB E R

Crowded travel times are behavioral measures which increase the in-vehicle time to
reflect the discomfort of standing or travelling in crowded conditions.
You can define up to 255 wait curves. No default curves are provided. If crowding is not
applied, then either do not code line capacities, or use a flat curve (with y-value set to
1.0 at both x=0 and x=100).
Input CROWDCRVDEF statements must be input in the public transport system data file with
SYSTEM I.

CR OW D CR V D E F k e y wo rd s

Ke y wo rd D e s c rip tio n

CURVE |R| Defines X-Y pairs for the crowding curves used to
compute link travel times under crowded
conditions. Utilization (measured as a
percentage) is the curve’s X-axis and the
crowding factor is the curve’s Y-axis. By default
(UTFLEX=F), the values for utilization vary from 0.0
(where the crowding factor is at least 1.0) to 100.0.
By setting UTFLEX=T the user can specify values
of utilization above 100.0.
Specify the utilization values in ascending order;
the corresponding crowding factor values must
increase, or remain the same, when progressing
from one point to the next.
Each pair of X and Y values may be separated by
a comma or a dash, while the pairs themselves
must be separated by a comma. For example:
CROWDCRVDEF NUMBER=1
LONGNAME="Suburban Rail" NAME="S-
Rail" ,
CURVE= 0,1.0, 20,1.1,
100,1.9
The following rules apply to the
coding/interpreting of crowding curves:
• Values for the first coded Y-value may not
be less than 1.0.
• Crowding factor (Y-axis) may not decrease
as utilization (X-axis) increases.
• There is a linear interpolation between
 coded points.
• When the first coded X-value is greater than
0% utilization, the curve runs from the point
(0-1.0) to the first coded point.

• When the last coded X-value is less than

100%, the curve is extrapolated beyond that
point at the same gradient as applies
immediately below the point.

• If UTFLEX=F the curve is considered

constant for X-values beyond 100%, whilst if
UTFLEX=T, the curve is extrapolated
beyond the last point at the same gradient
as applies immediately below the last point.
Maximum value: 10,000.

LONGNAME |S| Optional. Specifies a second text-string identifier

for a crowding curve. It is in addition to NAME.

NAME |S| Optional. Specifies a text-string identifier for a

crowding curve.

NUMBER |I| Specifies a unique numeric identifier for a

crowding curve.
Must be the first keyword coded on the
CROWDCRVDEF control statement.
Valid values range from 1 to 255.
Public Transport Program > Control statements > CROWDCRVDEF > Example

Exam ple

Defining crowd curve number 1 for rail services.

CROWDCRVDEF NUMBER=1,
NAME="Medium distance Rail",
CURVE= 0-1.0, 37-1.1, 100-1.9
Public Transport Program > Control statements > CROWDMODEL

CROWDMODEL
Specifies the crowding model used in the run of the Public Transport program.
Keywords include:
• A D J U S T LIN K

• A D J U S T W A IT

• A P P LY

• IT E R A T ION S

• LIN KD F

• P E R IOD

• R D IFF

• R D IFFCU T OFF

• R D IFFS T OP

• R E P OR T IJ

• R MS E

• R MS E CU T OFF

• R MS E S T OP

• S KIMS

• S T OP 2S T OP

• SUM

• T R A CE IJ

• U T FLE X

• V OLD F

• W A IT D F

CR OW D MOD E L k e y wo rd s

P o s s ib le
Ke y wo rd D e s c rip tio n V a lue s

ADJUSTLINK |?| Optional. When set to true, invokes link

travel-time adjustment, which reflects
higher behavioral costs associated with
travelling in crowded conditions.
Default value is false.

ADJUSTWAIT |?| Optional. When set to true, invokes the

calculation of additional wait time. Uses
the available capacity of a service (at a
particular boarding point) along with
demand data to establish whether
travellers may board this service, or
must wait for a later service.
Default value is false.
APPLY |?| Optional. When set to true, runs the
crowding model. When set to false, the
crowding model is disabled.
Default value is false.

ITERATIONS |I| Specifies the number of iterations

performed during a crowd-modeling
run. Valid values are 1 to 99.

LIN KD F Optional. Specify the link damping Valid values

factor to update link crowding factors range from 0.0
during the crowd iteration. to 1.0
This keyword works with Default value is
ADJUSTLINK=T. 0.5

PERIOD |I| Length of the modeled period in

minutes. Any demand matrix loaded
during assignment should be
calculated for the model period.
Valid values are 1 to 1440. Default
value is 60.

R D IFF |?| Optional. Flag indicating whether to True - Calculate

calculate the output the Relative the relative
Differences between consecutive difference
iterations. The results are outputted to between
print file. consecutive
Note: This keyword must be used along iterations and
with the SKIMIJ phase output to print
file
e.g.
PHASE=SKIMIJ False - Do not
calculate and
ENDPHASE
output the
relative
difference
between
consecutive
iterations
Default value is
False.

R D IFFCU T OFF Optional. User specified threshold that Default is 0

works together with RDIFFSTOP to set
up a valid stopping criteria.
This keyword is only valid when
CROWDMODEL is applied (APPLY=T).

R D IFFS T OP Optional. Flag indicating whether to stop True - Stop the

the crowding run based on RDIFF crowding run if
values of the last three iterations. the RDIFF
If using RDIFFSTOP=T but RDIFF=F (or values from the
unset), a warning message will be last three
given, and the stopping criteria will not sequential
be applied. iterations are
less than user
If both RMSESTOP and RDIFFSTOP
specified
are set to True, the crowding run will
threshold
stop when either of those two stopping
(RDIFFCUTOFF)
criteria is satisfied.
This keyword is only valid when False - Do not
CROWDMODEL is applied (APPLY=T). stop the
crowding run
based on
RMSE values
 Default is False

R E P OR T IJ |?| Optional. Flag indicating whether to list True - List

the evaluated routes for every iteration. evaluated
The program writes the report to file routes to the
specified with REPORTO. report file
Note: This keyword must be used False - Do not
together with ROUTEI REPORTI and/or list evaluated
REPORTJ, or ROUTEO REPORTI and/or routes to the
REPORTJ report file
Default is False

R MS E |?| Optional. Flag indicating whether to True - Calculate

calculate the output the Root Mean the relative
Square Error between consecutive difference
iterations. The results are outputted to between
print file. consecutive
Note: This keyword must be used along iterations and
with the SKIMIJ phase output to print
file
e.g.
PHASE=SKIMIJ False - Do not
calculate and
ENDPHASE
output the
relative
difference
between
consecutive
iterations
Default value is
False.

R MS E CU T OFF Optional. User specified threshold that Default is 0

works together with RMSESTOP to set
up a valid stopping criteria.
This keyword is only valid when
CROWDMODEL is applied (APPLY=T).

R MS E S T OP Optional. Flag indicating whether to stop True - Stop the

the crowding run based on RMSE crowding run if
values of the last three iterations. the RMSE
If using RMSESTOP=T but RMSE=F (or values from the
unset), a warning message will be last three
given, and the stopping criteria will not sequential
be applied. iterations are
less than user
If both RMSESTOP and RDIFFSTOP
specified
are set to True, the crowding run will
threshold
stop when either of those two stopping
(RMSECUTOFF)
criteria is satisfied.
This keyword is only valid when False - Do not
CROWDMODEL is applied (APPLY=T). stop the
crowding run
based on
RMSE values
Default is False

S KIMS |?| Optional: Flag indicating whether to True - Output

output skim matrices for every iteration. skim analysis
The program writes SKIM MATRICES matrices in
appending the iteration number at the each iteration
 end of the file name. False - Do not
The matrix file name corresponding to output skim
the last iteration does not have the analysis
iteration number appended, but just the matrices in
user defined name. each iteration,
i.e. only output
Note: This keyword must be used
in the final
together with the definition of skim
iteration
matrices within the SKIMIJ phase and
outputs to file specified by FILEO MATO Default value is
False.

S T OP 2S T OP |?| Optional. Flag indicating whether to True - Output

output stop-to-stop analysis results at STOP2STOP
each iteration. The program writes the analysis results
report to file specified with at each
STOP2STOPO appending the iteration iteration
number at the end of the file name. False - Do not
The file name corresponding to the last output
iteration does not the iteration number STOP2STOP
appended, but just the user defined analysis results
name. at each
Note: This keyword must be used iteration, i.e.
together with FILEO STOP2STOPO and only output at
its sub keywords. the final
iteration
Use STOP2STOPO… FORMAT=TXT or
CSV to change the output format in case Default is False.
of very large files.

SUM |RV*| Optional. Specifies the fractions to be

applied when choosing PT Crowding
model’s incremental loading approach.
The sum of all the fractions should be
1.00 (e.g., SUM=0.2,0.2,0.3,0.3); if the
sum is not 1.00, a warning message will
be issued, but this will not preclude the
program from executing.
For each iteration, demand trips will be
factored according to the accumulated
fractions for that iteration.
After the number of iteration reaches the
number of fractions, PT Crowding will
continue to iterate accordingly to the
other keywords usage (i.e., stopping
criteria, smoothing critier, etc.).
Therefore, the number of fractions sets
the minimum number of crowding
iterations. The program will
automatically check the ITERATIONS
setting, i.e., if the ITERATIONS is less
than the # of full incremental loading
fractions, the program will set the
ITERATIONS=# of full incremental
loading and continue the run.
The user should not that the incremental
loading of PT demand updates
crowding factors and corresponding
travel costs at each iteration, and use
these to do ‘incrementally’ demand
loading, avoiding link flow
accumulation.

T R A CE IJ |?| Optional. Flag indicating whether to list True - List

the evaluated routes using tabular- evaluated
 format for every iteration. The program routes to the
writes the report to file specified with report file
REPORTO. False - Do not
Note: This keyword must be used list evaluated
together with ROUTEI TRACEI and/or routes to the
TRACEJ, or ROUTEO TRACEI and/or report file
TRACEJ Default value is
False.

U T FLE X |?| Optional. Flag indicating whether to True – Allow a

enable the crowding curve to accept flexible
values of utilization beyond 100%. crowding curve,
which can
adopt utilization
value beyond
100%
False – Do not
allow a flexible
crowding curve.
The utilization
value cannot
exceed 100%
Default value is
False.

V OLD F Optional. Specify the volume damping Valid values

factor for volume averaging during the range from 0.0
crowd iteration. to 1.0
This keyword works with Default value is
ADJUSTLINK=T. 0.5

W A IT D F Optional. Specify the wait damping Valid values

factor for capacity and demand range from 0.0
averaging during the crowd iteration. to 1.0
This keyword works with Default value is
ADJUSTLINK=T. 0.5
Public Transport Program > Control statements > CROWDMODEL > Example 1

Exam ple 1
CROWDMODEL,
APPLY = T,
ADJUSTWAIT = T,
ITERATIONS = 10

Specifies a run with 10 iterations of crowd modeling, including a wait-time adjustment.

Public Transport Program > Control statements > CROWDMODEL > Example 2

Exam ple 2
Public Transport Program > Control statements > EXIT

EXIT
Terminates loops (implied or explicit). When the program encounters an EXIT statement
within a loop, the program passes control to the end of the loop.
Public Transport Program > Control statements > EXIT > Example

Exam ple
LOOP iter=1,10
.
IF (expression) EXIT
.
ENDLOOP

This loop terminates either when iter=11 or the condition specified by expression is met.
Public Transport Program > Control statements > FACTORS

FACTORS
Specifies the generalized cost factors and control information for the route enumeration
and evaluation processes. Keywords and sub-keywords include:

• A LP H A • MU S T U S E MOD E

• A ON MA XFE R S • P E R IOD

• B E S T P A T H ON LY • QU ICKE S T P A T H
m EVALFARE • QU ICKE S T MU LT I
m ENUMFARE • R E B E S T P A T H COS T

• BEST PAT HS • R E COS T MA X

• BRDPEN • R E FA R E FA CT OR

• CH OICE CU T • R E W A IT MA X

• DAYT YPE • R E W A IT MIN

• D E LA CCE S S MOD E • R U N FA CT OR

• D E LE GR E S S MOD E • S E R V ICE MOD E L

• D E LMOD E • S H OR T E S T W A LK

• E XT R A XFE R S 1 • S P R E A D CON S T

• E XT R A XFE R S 2 • S P R E A D FA CT

• FA R E S Y S T E M • S P R E A D FU N C
m MODE • T IME P OIN T

m OPERATOR • V A LU E OFT IME

• FR E QB Y MOD E • W A IT FA CT OR
m NODES
• IW A IT CU R V E
m NODES • XFE R CON S T
m FROM
• KB E T A
m TO
• KIR CH OFF

• LA MB D A A • XFE R FA CT OR
m FROM
• LA MB D A R

• LA MB D A W m TO

• MA XCOMP D • XFE R P E N

• MA XFE R S m FROM
• MA XW A IT V A R m TO
• MIN XFE R V A R • XW A IT CU R V E
• MU ME XT R A COS T m NODES
FACTORS statements must be input in a separate file with FACTORI keywords on the FILEI
control statement. Each user class that the program references must have FACTORI
keywords defined on a FILEI control statement, although two or more classes may
reference the same file. The index of the FACTORI keyword, #, is the number of the user
class. If there is no index, the program assumes the index is 1. You define user classes
with the USERCLASSES keyword in the PARAMETERS control statement.
Some FACTORS keywords are used for both the route enumeration and evaluation
processes; others apply to one or the other, as noted in the keyword description.
The keywords on this statement are all “trigger” keys; you need not code the control
statement name FACTORS. The values can be input in any order. For most of the
keywords, the program uses the last value specified, if the keyword appears multiple
times.
FA CT OR S k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ALPHA |RK| Optional. Determines the relative

weights for the generalized costs of
the walk leg and the remainder of the
route in walk-choice model.
Valid values range from 0.0 to 1.0. A
value of 1 indicates that the walk and
onward costs have equal weight.
Lower values indicate the walk cost
has more influence than the onward
cost in the traveler’s choice. A
traveler’s willingness to walk might
relate to network familiarity.
Applies only to route evaluation.
Default value is 1.0.

AONMAXFERS |IK| Optional. Maximum permitted

number of transfers on the minimum-
cost, all-or-nothing routes.
The all-or-nothing path building
process (which precedes route
enumeration) identifies the number of
transfers on the minimum-cost route
from an origin to a destination.
Multirouting models only enumerate
the all-or-nothing route if the number
of transfers exceeds MAXFERS.
Only routes with AONMAXFERS (or
fewer) transfers are enumerated to
the routes file. When
BESTPATHONLY=T, only those
routes with MAXFERS or fewer
transfers are enumerated (that is,
AONMAXFERS is not used)
Valid values are 0 to 45. Default
value is 45.

BESTPATHONLY |?K| Optional. When set to true, the

evaluation process identifies a
 single best path, onto which all
demand is loaded, and the
enumeration process changes its
mode of operation: Best paths using
more then MAXFERS transfers are
not enumerated, making higher
MAXFERS settings appropriate. The
best-path-only method cannot be
used with the crowding model, the
service frequency and cost model,
or the timetabling model.
Do not set BESTPATHONLY to true if
PARAMETERS keyword FARE is true
or AONMETHOD has value 3. When
using best-path modeling, the
program ignores settings for the
FACTORS keywords ALPHA,
AONMAXFERS, CHOICECUT,
LAMBDAA, LAMBDAW,
REWAITMAX, and REWAITMIN.
If using best-path modeling with
MUSTUSEMODE set to true, the
program uses the FACTORS
keywords SPREADCONST,
SPREADFACT, and SPREADFUNC;
otherwise the keywords are ignored.
The default value is false.

BESTPATHONLY EVALFARE |?K| Optional. If set to True, we allow fare

to be calculated in the best path
evaluation and skimming process.
Default is False.
See Example 2 — Example of
EVALFARE keyword.

BESTPATHONLY ENUMFARE |?K| Optional. If set to True, we allow a

subset of fare systems to be
considered in the best path
enumeration process. The user may
specify one of two fare systems,
DISTANCE or FLAT. Default is
False.
If ENUMFARE=T and no fare
skimming and route evaluation is
required, EFARE must be set to True
to allow the input descriptions of fare
systems with FILEI FAREI.
See Example 3 — Example of
ENUMFARE keyword and Example
4 — Example of EFARE parameter.

BESTPATHS |K?| When true, enumerates multi-routing

(i.e. multiple paths for each departure
time), then selects the lowest
generalized cost path out of each
"departure time".
Default is false.

The term path is used to mean a

route which is followed using a set of
departure and arrival times at each
stop. If a line runs half-hourly, then
 there would be 2 distinct paths in an
hour from zone I to zone J (where I
and J are linked to that line; there is
however just one underlying route.)

If BESTPATHS is not true, full multi-

routing takes place (i.e. enumerates
multiple paths for each departure
time and each path is included in
evaluation.)

BRDPEN |RKV999*| Optional. Mode-specific boarding

penalty, in minutes. Applied in
addition to the transfer penalty
specified by XFERPEN. Applied only
to transit modes; nonzero values
specified for nontransit modes do not
have any effect.
For example, if BRDPEN=3,3*5,6
then the penalty for boarding any line
on mode 1 is three minutes, the
penalty for boarding any line on
modes 2, 3, and 4 is five minutes and
the penalty for boarding a line on
mode 5 is six minutes.
Valid values range from 0 to 9999.
The default value is 0.

CHOICECUT |RK| Optional. Eliminates alternatives with

low probabilities of use at walk or
alternative-alighting decision points.
If p is the proportion of the demand
that takes the least-cost alternative,
then the program discards
alternatives taking less than
p*CHOICECUT.
This is equivalent to choices being
eliminated if:

where:
λ
Scale parameter that reflects
traveler sensitivity to cost
differences. It takes the
value of LAMBDAW or
LAMBDAA, depending upon
the point in the trip at which it
is applied.
Costi
Cost to destination by choice
i
CostBest
Cost to destination by the
best choice

CHOICECUT applies only to route

evaluation; it is not used when
modeling best path routes.
Valid values range from 0 to 0.2. The
default value is 0.01.
DAYTYPE |KI| The day type number which the
model relates to. This selects the
lines/runs which operate on that day.

DELACCESSMODE |IKV999| Optional. Specifies modes that

cannot be used as access
connectors (from zones to transit
lines) during route enumeration. For
example, when modeling walk and
car connectors, you can use this
keyword to restrict access legs to the
required mode (that is, walk or car)
for a user class.
Valid values range from 0 to 999.
There is no default.

DELEGRESSMODE |IKV999| Optional. Specifies modes that

cannot be used as egress
connectors (from transit lines to
destination zones) during route
enumeration. For example, when
modeling walk and car connectors,
you can use this keyword to restrict
egress legs to the mode (that is, car
or walk) required for a user class.
Valid values range from 0 to 999.
There is no default.

DELMODE |IKV999| Optional. Specifies modes that the

program will not use during route
enumeration. You can use this
keyword to delete particular modes
(transit or nontransit) from the model
for a particular user class.
Valid values range from 0 to 999.
There is no default.

EXTRAXFERS1 |IK| Optional. Number of transfers at

which the program stops exploration
of less direct routes. EXTRAXFERS1
is one of three parameters
controlling the exploration of routes.
EXTRAXFERS1 applies only to route
enumeration. See “Route
generation” on page 802 for more
information.
Valid values range from 0 to 10. The
default value is 3.

EXTRAXFERS2 |IK| Optional. Maximum number of

transfers explored in excess of the
number of transfers required by the
minimum-cost route. An upper bound
on the number of transfers, in excess
of the minimum required, is
controlled by EXTRAXFERS1 and
MAXFERS (see “Route generation”
on page 802.). EXTRAXFERS2 is one
of three parameters controlling the
exploration of routes. EXTRAXFERS2
applies only to route enumeration.
Valid values range from 0 to 10. The
 default value is 2.

FARESYSTEM |IK| Optional. Number of the fare model

that applies to the modes or
operators selected with the
subkeywords MODE or OPERATOR.
The fare model must be one of the
fare systems defined with the
FARESYSTEM control statement in a
FILEI FAREI file.
For example, you might describe a
fare model in the FAREI files as:
FARESYSTEM NUMBER=1,
NAME="Flat",
STRUCTURE=FLAT,
IBOARDFARE=100,
FAREFROMFS=0,30,40
FARESYSTEM NUMBER=2,
NAME="DIST-Journ",
STRUCTURE=DISTANCE,
IBOARDFARE=50, UNITFARE=70,
FAREFROMFS=40,0,50
In the factors file, you can apply that
fare model to a selection of transit
modes:
FARESYSTEM=1, MODE=1-6
FARESYSTEM=2, MODE=7-11
FARESYSTEM applies only to route
evaluation.
Valid values range from 1 to 1999. By
default, none are specified.
NOTE: The MODE and OPERATOR
subkeywords are mutually exclusive,
but you must code one for each
FARESYSTEM. If using multiple fare
models, all FARESYSTEM keywords
must apply to either modes or
operators. The program allocates
fare systems to lines, through their
modes or operators. Mixing the two
could produce ambiguous
allocations.

FARESYSTEM MODE |IVt|1 Optional. List of transit modes that the

fare model specified in
FARESYSTEM applies to. Program
ignores any nontransit modes in the
list.
Valid values range from 1 to 999.
Default value is 0.

FARESYSTEM OPERATOR |IVo|2 Optional. List of operators that the

fare model specified in
FARESYSTEM applies to.
Valid values range from 1 to 99.
Default value is 0.

FREQBYMODE |?K| Optional. Flag that determines wait-

time calculation:
• False — Calculated at the
transit-leg bundle level
 • True — Calculated at the
(lower) mode level
FREQBYMODE is only applicable
when BESTPATHONLY is true. The
default value is true.
FREQBYMODE comes into effect
when a transit-leg bundle (that is,
collection of lines from a boarding
point to an alighting point) on a
“potential best route” is multimodal.
By default the BESTPATHONLY
enhancement identifies the best path
using unimodal transit-leg-bundles. If
modes 1 and 2 form a bundle, then
either you use mode 1 or you use
mode 2 depending on IVT and wait
times in the two cases. The wait
times are based on the headway of
the mode under consideration. This
corresponds to traveler behavior
where a traveler selects a mode of
travel, and then waits for a service of
that mode (ignoring any potentially
useful services in the transit leg
bundle of any other mode).
If FREQBYMODE is false then
multimodal transit leg bundles are
allowed. In this case, the wait time is
based on combined frequency of all
lines in the transit bundle regardless
of mode, and the average IVT is
based on all modes. This gives
lower wait times, and corresponds to
traveler behavior where they “select
the useful service that first arrives at
the boarding point,” and mode does
not affect that boarding pattern.

IWAITCURVE |IK| Optional. Wait curve used to

calculate the initial wait time for trips
starting at nodes specified by
NODES subkeyword.
For example, given
IWAITCURVE=2, NODES=1000-
2000, 2500-2600, the program
uses wait curve number 2 to
calculate the wait time for journeys
starting at nodes 1000 through to
2000 and 2500 to 2600, inclusive.
IWAITCURVE applies only to the
route-evaluation process.
Valid values range from 1 to the
number of wait curves in the network.
The default value is system
generated.

IWAITCURVE NODES |IV10000| List of nodes to which the wait curve

number specified by IWAITCURVE,
applies when they are the initial
boarding points of trips. The
program ignores wait curves
associated with zones or nodes that
 are not stops.
Valid values range from 1 to the
system’s highest node number. This
keyword is required if IWAITCURVE
is specified.

KBETA |KR| Power used in Kirchoff distribution

(coded positive but used as
negative in a similar way to
lambdas); KBETA=2 will calculate
costs raised to the power -2. No
default

KIRCHOFF |K?| When true, uses Kirchoff (power-

function) to determine choices.
Default is false. Requires KBETA
when true.

LAMBDAA |RK| Optional. Scaling factor for the

alternative-alighting node model.
Determines the proportion of trips
allocated to each alighting node,
based on the composite cost
differences between the alternatives.
Applies only to the route-evaluation
process. Not used when modeling
best-path routes.
Valid values range from 0.0001 to
99.0. The default value is the value of
LAMBDAW.

LAMBDAR |KR| Scaling factor for the Logit model for

PT choice. Determines the
proportion of trips allocated to each
route, based on the cost differences
between the alternatives. Valid
values range from 0.0001 to 99.0.
The default value is 0.2.

LAMBDAW |RK| Optional. Scaling factor for the walk-

choice model. This factor
determines the proportion of trips
allocated to each walk choice at a
node, based on the composite cost
differences between alternatives.
When there are transit choices, the
program uses the transit modes’
composite cost to a destination to
determine the transit share.
Subsequently, the service-frequency
model allocates the transit share
among the different transit choices.
LAMBDAW applies only to the route-
evaluation process; the program
does not use this factor when
modeling best-path routes.
Valid values range from 0.0001 to
99.0. The default value is 0.2.

MAXCOMPD |IK| Optional. Number of components

generated during the route-
enumeration process. Used to
dimension arrays that store
 components and their attributes. The
number of components generated
depends upon the number of lines in
the public transport system and the
connectivity of the network; the
default value should work for a
medium-sized network of 400-500
zones.
MAXCOMPD applies only to route
enumeration. The program only
requires MAXCOMPD when using
older algorithms, triggered by the
AONMETHOD keyword on the
PARAMETERS control statement.
Valid values range from 1000 to
1,250,000. The default value is
50,000.

MAXFERS |IK| Optional. Maximum number of

transfers allowed in routes between
origin-destination pairs with more
than one enumerated route. For pairs
with only one enumerated route,
AONMAXFERS sets the maximum
number of transfers.
When an origin-destination pair has
a minimum-cost route with at most
MAXFERS transfers, then the
program enumerates viable routes. If
the transfers exceed the MAXFERS
when using multirouting, then the
program only enumerates the
minimum-cost route (subject to any
constraint imposed by the
AONMAXFERS factor). When
BESTPATHONLY is true, you might
use higher MAXFERS values, as best
routes requiring more transfers are
not enumerated.
When the PARAMETERS keyword
AONMETHOD is set to 3, MAXFERS
is the maximum number of transfers
allowed in route enumeration,
regardless of the number of
enumerated routes (AONMAXFERS
is not used). Routes with more
transfers are not enumerated (which
could lead to loss of connection
between some origin-destination
pairs which have complex journeys
between them).
MAXFERS works with EXTRAXFERS1
and EXTRAXFERS2 to control the
number of routes generated. See
“Route generation” on page 802.
Valid values range from 0 to 10. The
default value is 5.

MAXWAITVAR |KS| Optional. Specifies the name of a

node variable which holds the
maximum wait time which travelers
are prepared to spend waiting at
 each node (excluding the NTLEG, if
applicable). Specifying "varName"
will use "ni.varName" from the input
network.

MINXFERVAR |KS| Optional. Specifies the name of a

node variable which holds the
minimum wait time for transfer at
each node (excluding the NTLEG, if
applicable). When interchanging at a
node, the departure time must be this
much later than the arrival time.
Specifying "varName" will result in
"ni.varName" from the input network.

MUMEXTRACOST |RK| Optional. Additional cost allowed on

enumerated routes of a required
mode (a mode specified in
MUSTUSEMODE).
For example, if the cheapest route for
an origin-destination pair is 23 and
MUMEXTRACOST is 30, the program
will enumerate routes on the required
mode that have a cost of up to 53
(that is, 23+30).
Valid values range from 0.1 to
999,999. The default value is 999,999.

MUSTUSEMODE |IKV999| Optional. Specifies required transit

modes in a route for enumeration or
evaluation. If you specify two or more
values, the program enumerates the
route if any of the modes are used.
Specified modes must be transit
modes.
Valid values range from 0 to 999.

P E R IOD |KRPa| Time-tabling specific: Range of

values each in hhmm format which
specify start and end of modeled
period. E.g. 0930-1030 means
9:30am to 10:30am. There is no
default value.
Either this or TIMEPOINT must be
used in time-tabling runs.

QU ICKE S T P A T H |K?| When true, enumerates a single

path. Default is false.

QU ICKE S T MU LT I |K?| When true, enumerates a single

fastest path for each "departure
time." Default is false.

REBESTPATHCOST |?K| Optional. Flag that sets method for

computing transit costs in route
enumeration:
• True — Computes transit costs
closer to those used in
evaluation. See “Generalized
cost” on page 936 for a
description of costs.
• False — Computes transit
 Cannot be false if BESTPATHONLY is
true. Must be false if program uses
service frequency and cost model.
By default, set to the value of
BESTPATHONLY.

RECOSTMAX |RK| Optional. Upper cost limit that

applies during route enumeration.
The program excludes more
expensive routes from enumeration,
and hence evaluation.
Valid values range from 0.01 to
999,999. Default value is 999,999.

REFAREFACTOR |RKV999*| Optional. Specifies a factor which is

included in calculating the cost for a
transit leg which is then used in
enumeration. This factor is available
in multi-route modelling, and cannot
be used when BESTPATHONLY=T.
Public transport systems often
include a mix of transit modes, and
when fares are modelled faster more
expensive modes compete with
slower cheaper alternatives. The
enumeration process uses the same
perceived travel time as evaluation,
but does not include fares in the cost,
as they may be a function of the
entire route rather than just one transit
leg. Enumeration selects routes
which lie within defined margins of
the best route, as determined by
SPREADCONST and SPREADFACT.
Routes using slower modes may be
outside these margins, and so are
omitted from the route set.
REFAREFACTOR specifies a set of
mode-specific factors which are
multiplied by the perceived transit
leg cost to compensate for
differential fare levels during route
enumeration. With faster modes
having higher factors, their costs are
increased by a higher proportion,
and the enumeration process is
more likely to find routes using
slower modes.
The factors apply to transit modes;
the costs of non-transit legs are left
unchanged. REFAREFACTOR values
are typically >= 1.0 as they inflate the
perceived cost to take account of
fares.

REWAITMAX |RK| Optional. Maximum weighted wait

time for any leg bundle in route
enumeration.
The program computes a leg
bundle’s wait time from the sum of the
frequencies of the bundle’s legs:
(60./Frequency)/2
 For example, if the frequency of a leg
bundle sums to 5 vehicles per hour,
the wait time is 6 minutes.
Setting REWAITMAX to 3.0 ensures
that the maximum wait time at any
transit choice point is 3 minutes
regardless of the frequency of the
services available at that point.
Setting REWAITMAX to 0 excludes
wait time from consideration during
route enumeration.
REWAITMAX applies only to route
enumeration; it is not applicable
when modeling best-path routes.
Valid values range from 0.0 to 200.0.
The default value is 5.0.

REWAITMIN |RK| Optional. Minimum weighted wait

time for a leg bundle during route
enumeration.
The program computes a leg
bundle’s wait time from the sum of the
frequencies in the bundle’s legs:
(60./Frequency)/2
For example, if a leg bundle’s
frequency sums to 60 vehicles per
hour, the wait time is 0.5 minutes.
Setting REWAITMIN to 1.0 ensures
that a minimum wait time is incurred
for all leg bundles regardless of the
frequency of their services.
REWAITMIN applies only to route
enumeration; it is not applicable
when modeling best-path routes.
Valid values range from 0.0 to 30.0.
The default value is 1.0.

RUNFACTOR |RKVm*|3 Optional. Mode-specific weighting

factor applied to transit in-vehicle
times and nontransit leg times.
For example, if you include
RUNFACTOR=1.5,3*1.8,1.9 then
the program multiples run times for
mode 1 by 1.5, run times for modes 2,
3 and 4 by 1.8 and run times for
mode 5 by 1.9.
Values ranging between 0.01 and 3.0
are appropriate for most modeling
requirements. Valid values range
from 0.01 to 10.0. The default value is
1.0.

SERVICEMODEL |S| Optional. When considering

possible transit lines forward from a
boarding stop, the first step is to find
the basic set of lines, which should
be used in loading. This process
adds slower lines into a selected set,
and accepts them for loading/use if
the reduction in wait time outweighs
the increase in average travel time.
The wait time had historically been
 calculated using the formula:
WAITFACTOR * (Half
Headway)
Where the first term is a behavioral
weighting and the second represents
the average wait time.

In the updated version, we allow the

basic set identification to use
general wait curves, rather than
assuming a half-headway form, i.e.
WAITFACTOR *
WaitCurveValue(Cumulated
Headway)

Valid choices are:

• FREQUENCY — Specifies
Service-frequency model
using wait curves to
approximate the wait time
• FREQUENCYCOST —
Specifies Service-frequency-
and-cost model using wait
curves to approximate the wait
time. It cannot be used with
BESTPATHONLY=T.
• FREQUENCYHDW —
Specifies Service-frequency
model using half headway to
approximate the wait time
(consistent with the
FREQUENCY option before
Voyager Version 6.0.0)
• FREQUENCYCOSTHDW —
Specifies Service-frequency-
and-cost model using half
headway to approximate the
wait time (consistent with the
FREQUENCYCOST option
before Voyager Version 6.0.0).
It cannot be used with
BESTPATHONLY=T.
Default value is FREQUENCY.

SHORTESTWALK |?K| Optional. Determines which of a

group of non-transit connectors are
used in a multi-routeing model. The
connectors may be between zones
and stops, or interchange legs
(which may be at or between stops).
The default is unset.
When SHORTESTWALK=T the
selection is based on the lowest cost
connector. Any interchange between
a pair of lines which takes place at a
node will be chosen in preference to
a walk connection.
When SHORTESTWALK=F the
selection is based on travel time
between lines and/or zones. For
 transfers, the time (excluding wait) is
calculated from a point upstream of
the first alighting stop under
consideration on the from-line, to a
point downstream of the latest
boarding stop on the to-line. For
zone-line connectors, a similar
approach is followed, using an
upstream timing point when selecting
for egress, or a downstream timing
point for access.
When SHORTESTWALK is unset the
selection is based on the lowest cost
connector. An error in earlier
versions of Voyager PT means that
in dense urban areas too many
unnecessary (or inappropriate)
transfer connectors were identified
and used in the model. By setting
SHORTESTWALK a smaller set is
used, without any reduction in
connectivity in the network, giving the
benefit of shorter run times.

SPREADCONST |RK| Optional. Constant used in

multirouting function to compute
SPREAD during route enumeration.
Please see “SPREADFUNC” on
page 794.
Valid values range from 0 to 1000.0.
Default value is 5.0.

SPREADFACT |RK| Optional. Multiplicative factor used in

multirouting function to compute
SPREAD during route enumeration.
Please see “SPREADFUNC” on
page 794.
Valid values range from 1 to 10.0.
Typical values range from 1.05 to
1.2, exceeding 2.0 only in rare
circumstances. Default value is 1.2.

SPREADFUNC |IK| Optional. Integer specifying the

function that computes SPREAD
during route enumeration.
SPREAD defines an upper cost limit
for routes between an O-D pair. The
lower limit is the cost of the “minimum
cost” route between the two zones.
SPREADFUNC applies only to route
enumeration. SPREDFUNC is
applied only in the following cases:
• BESTPATHONLY=F (multi
routing)
• BESTPATHONLY=T and
MUSTUSEMODE is used and
spread values are explicitly
coded by the user (not default
value). In this case, PT
generates the best path, with
the MUSTUSEMODE that is
within the spread specified by
 the user. If there are no paths
with the MUSTUSEMODE,
inside the spread, then no
routes will be enumerated.
The program computes the upper
limit based on value of
SPREADFUNC:
• SPREADFUNC=1:
SPREAD =
MAX(GCost(MinRoute)*
SPREADFACT, GCost(MinRoute)
+ SPREADCONST)
• SPREADFUNC=2:
SPREAD = GCost(MinRoute)*
SPREADFACT + SPREADCONST
Where:
• GCost(MinRoute) —
Generalized cost of the
minimum-cost route.
NOTE: This is an estimate. The
generalized cost the route-
evaluation process uses is more
accurate.
• SPREADFACT — Factor that the
minimum generalized cost time
between zone pairs may be
multiplied by.
• SPREADCONST — Time that
may be added to the minimum
generalized cost time between
zone pairs.
The program enumerates routes with
a cost less than or equal to
SPREAD.
NOTE: The parameter applies to
each decision point
(alighting/boarding node) on a route
in addition to the destination.
Default value is 1.

T IME P OIN T |KR| Alternative to PERIOD for time-

tabling. The traveler leaves the
origin at this fixed/defined time
(specified in hhmm format) and
appropriate paths are found and
evaluated. No default.

VALUEOFTIME |RKVt*|1 Optional. Transit-mode-specific

value of time, in monetary units per
hour. Converts monetary fares into
generalized cost. Only code if using
fares.
Applies only to route evaluation.
Does not apply to nontransit modes;
ignored in such cases.
Valid values range from 0.0 to 9999.

WAITFACTOR |RK| Optional. Node-specific wait-time

weighting factor, applied to nodes
 specified with NODES subkeyword.
Valid values range from 0.01 to 10.0.
Typically, sufficient values for most
modeling range from 0.01 to 3.0.
Default value is 1.0.

WAITFACTOR NODES |IV10000| List of nodes that WAITFACTOR

applies to.
Valid values range from 1 to the
system’s highest node number. This
keyword is required if WAITFACTOR
is specified.
For example, consider:
WAITFACTOR=1.5, NODES=1000-
2000, 3000-4500
The wait times for nodes 1000
through 2000 and nodes 3000
through 4000 will be multiplied by 1.5.

XFERCONST |RKVt [t]|1 Optional. Transit-mode-to-transit-

mode constant that can be added to
the weighted transfer penalties
obtained from XFERPEN.
Use FROM and TO to specify the
applicable modes.
For example, consider:
XFERCONST=3, FROM=10, TO=25
For transfers from mode 10 to mode
25, the program will add three
minutes to the transfer penalty
specified by XFERPEN.
Applies only to route evaluation.
Valid values range from 0.0 to 5000.
The default value is 0.0.

XFERCONST FROM |IV100| Integer specifying the “from” mode

for the transfer penalty specified with
XFERCONST.
Valid values range from 1 to the
network’s highest mode number.

XFERCONST TO |IV100| Integer specifying the “to” mode for

the transfer penalty specified with
XFERCONST.
Valid values range from 1 to the
network’s highest mode number.

XFERFACTOR |RKVt [t]|1 Optional. Transit-mode-to-transit-

mode weighting factor for transfer
penalties specified by XFERPEN.
Use the subkeywords FROM and TO
to specify the applicable modes.
For example, consider:
XFERFACTOR=1.5, FROM=10,
TO=25
For transfers from mode 10 to mode
25, the program multiplies the
transfer penalty specified by
XFERPEN by 1.5.
Applies only to route evaluation.
 Valid values range from 0.01 to 10.0.
The default value is 1.0.

XFERFACTOR FROM |IV100| Integer specifying the “from” mode

for the transfer penalty factor
specified with XFERFACTOR.
Valid values range from 1 to the
network’s highest mode number.

XFERFACTOR TO |IV100| Integer specifying the “to” mode for

the transfer penalty factor specified
with XFERFACTOR.
Valid values range from 1 to the
network’s highest mode number.

XFERPEN |RKVt [t]|1 Optional. Transit-mode-to-transit-

mode transfer penalty, in minutes.
Use the subkeywords FROM and TO
to specify the applicable modes.
For example, consider:
XFERPEN=5.5, FROM=10, TO=25
For transfers from mode 10 to mode
25, the program adds 5.5 minutes.
Transfer penalties apply between
the alighting and boarding transit
modes. The program ignores any
nontransit legs traversed between
the two.
The program applies XFERPEN in
addition to BRDPEN. Transfer
penalties may be negative but the
sum of XFERPEN(from mode, to
mode) and BRDPEN(to mode) must
be greater than or equal to zero. Use
negative transfer penalties in
conjunction with boarding penalties
to reflect the relative attractiveness of
transfers between some modes
compared to others.
Code a high penalty to ban transfers
between modes. A high penalty
makes any route with such transfers
“unattractive” to the choice models. In
most cases, a penalty of 999 minutes
is sufficient.
XFERPEN only applies to route
evaluation.
Valid values range from -99 to 9,999.
The default value is 0.

XFERPEN FROM |IV100| Integer specifying “from” mode for

transfer penalty specified with
XFERPEN.
Valid values range from 1 to the
network’s highest mode number.

XFERPEN TO |IV100| Integer specifying “to” mode for

transfer penalty specified with
XFERPEN.
Valid values range from 1 to the
network’s highest mode number.
 XWAITCURVE |IK| Optional. Wait-curve number used to
calculate wait times for trips that
involve transfers to nodes specified
with NODES subkeyword.
For example, consider:
XWAITCURVE=4, NODES=1000-
1500
The program uses wait curve
number 4 to compute the wait time at
nodes 1000 through 1500, when
those nodes form transfer points in a
trip.
XWAITCURVE applies only to route
evaluation.
Valid values range from 1 to the
maximum number of wait curves in
the network. The default is a system-
generated wait curve.

XWAITCURVE NODES |IV10000| List of nodes that the wait curve

specified in XWAITCURVE applies
when they are boarding stops at
transfer points. The program ignores
wait curves associated with zones or
nodes that are not stops.
Valid values range from 1 to the
network’s highest node number.

1 t indicates number of transit modes

2 o indicates number of transit operators

3 m indicates number of modes

Public Transport Program > Control statements > FACTORS > Example 1

Exam ple 1
//Note: Keywords need not be preceded by control statement name FACTORS
//They are directly recognized within context
//Enumeration Controls
MAXFERS=5
EXTRAXFERS1 = 2
EXTRAXFERS2 = 1
SPREADFUNC = 1
SPREADFACT = 1.1
SPREADCONST = 10.0
REWAITMIN = 5
REWAITMAX = 30
//Evaluation Controls
ALPHA = 1.0
LAMBDAW = 0.3
LAMBDAA = 0.3
//Wait time
IWAITCURVE=1, nodes=1300-1400
XWAITCURVE=2, n=150-1600
WAITFACTOR=2.25, n=25-1000
//IVT factor by mode
RUNFACTOR[7] = 1.5, RUNFACTOR[8] = 2, RUNFACTOR[11] = 2.5
//Penalties
BRDPEN[7] = 4*2.5
XFERPEN=3.0, from=7-10, to=8-12,
XFERPEN=2.0, from=11-12, to=7-12,
XFERCONST=5.0, from=7-10, to=7-12,
XFERCONST=2.5, from=11-12, to=7-12,
XFERFACTOR=1.5, from=7-10, to=8-12,
XFERFACTOR=2.0, from=11-12, to=7-12,
Public Transport Program > Control statements > FACTORS > Example 2 — Example of EVALFARE keyword

Exam ple 2 — Exam ple o f EVALFARE keywo rd

The 'EVALFARE =T' can be defined along with the BESTPATHONLY keyword to allow fare to
be calculated in the best path evaluation and skimming process. Note that the
'BESTPATHONLY=T' setting originally doesn't include the fare in calculating the route
cost during evaluating the transit route. Hence, the user can't define 'PARAMETERS
FARE=T' with 'BESTPATHONLY=T' in the PT program, but it would be fine now by
being set with 'EVALFARE=T'. In the tested example below, the cost for route
evaluation is increased from 107.703 to 117.521 because it contains fare. Note that the
routes are still enumerated using the original approach without fare in the cost
computation.
< Settings in Factor & Parameter >
*** INPUT FACTOR FILE ***
;Global Settings ; fare to be calculated in the best
BESTPATHONLY=T, EVALFARE=T ; path evaluation process

*** SCRIPT PROGRAM ***

PARAMETERS FARE=T

*** ORIGINAL FARE FILE ***

FARESYSTEM NUMBER=1 LONGNAME="Local Buses" NAME="LB" STRUCTURE=FLAT SAME=CUMULATIVE,
IBOARDFARE=0.90,FAREFROMFS=0.00,0.00,0.00,0.00,0.00,0.90,0.00

< Comparison of transit route costs for z# 194 -> z# 2204 >
*** ROUTE COST for ORIGINAL ***
REval Route(s) from Origin 194 to Destination 2204

194 -> 32376

32376 -> 22080 -> 2204 lines L8 WB
Cost= 107.703 Probability=1.0000
Fare= 0.90

*** ROUTE COST for TEST 1 ***

REval Route(s) from Origin 194 to Destination 2204

194 -> 32376

32376 -> 22080 -> 2204 lines L8 WB
Cost= 117.521 Probability=1.0000
Fare= 0.90
Public Transport Program > Control statements > FACTORS > Example 3 — Example of ENUMFARE keyword

Exam ple 3 — Exam ple o f ENUM FARE keywo rd

The 'ENUM FARE =T' can be defined along with the BESTPATHONLY keyword to allow fare
to be calculated in the best path enumeration process. However, the 'ENUMFARE=T'
also requires 'EVALFARE =T' to include the fare to the route cost during
enumerating/evaluating the transit routes. Note that 'ENUMFARE=T' cannot be utilized
without 'EVALFARE=T' once 'PARAMETERS FARE=T' is defined. In the tested
example below, the cost for route evaluation is increased from 107.703 to 162.248
because it contains the revised fare increased from $0.9 to $5 in the boarding fare.
Hence, it is confirmed that the fare is added into the route cost.
< Settings in Factor & Parameter >
*** INPUT FACTOR FILE ***
;Global Settings ; to be calculated in the best
BESTPATHONLY=T, EVALFARE=T, ENUMFARE=T ; path enumeration & evaluation

*** SCRIPT PROGRAM ***

PARAMETERS FARE=T

*** REVISED FARE FILE ***

FARESYSTEM NUMBER=1 LONGNAME="Local Buses" NAME="LB" STRUCTURE=FLAT SAME=CUMULATIVE,
IBOARDFARE=5.00,FAREFROMFS=0.00,0.00,0.00,0.00,0.00,0.90,0.00

< Comparison of transit route costs for z# 194 -> z# 2204 >
*** ROUTE COST for TEST 2 ***

194 -> 32376

32376 -> 22080 -> 2204 lines L8 WB
Cost= 162.248 Probability=1.0000
Fare= 5.00
Public Transport Program > Control statements > FACTORS > Example 4 — Example of EFARE parameter

Exam ple 4 — Exam ple o f EFARE param eter

The 'ENUM FARE =T' can be defined along with the BESTPATHONLY keyword to allow fare
to be calculated in the best path enumeration process. In this case, the 'PARAMETERS
EFARE=T' indicates that the fare data would be input through the FAREI file. Since only
the route enumeration is processed by this keyword, the route report doesn't show the
detail information for the selected zonal pair as provided during evaluating the route.
Note that either transit skimming or transit loading process should be implemented
separately in the following step because the 'Parameters EFARE=T' setting doesn't
work with the route evaluation. In the tested example below, the total skimming fares are
changed because the transit routes are different by including the fare for the route
enumeration.
< Settings in Factor & Parameter >
*** INPUT FACTOR FILE ***
;Global Settings ; fare to be calculated in the best
BESTPATHONLY=T, ENUMFARE=T ; path evaluation process

*** SCRIPT PROGRAM ***

PARAMETERS EFARE=T

*** ORIGINAL FARE FILE ***

FARESYSTEM NUMBER=1 LONGNAME="Local Buses" NAME="LB" STRUCTURE=FLAT SAME=CUMULATIVE,
IBOARDFARE=0.90,FAREFROMFS=0.00,0.00,0.00,0.00,0.00,0.90,0.00

< Comparison of transit route costs for z# 194 -> z# 2204 >
*** ROUTE COST for TEST 3 ***

REval Route(s) from Origin 194 to Destination 2204

194 -> 32376

32376 -> 22080 -> 2204 lines L8 WB
Public Transport Program > Control statements > FACTORS > Route generation

Ro ute generatio n

M AXFERS works with EXTRAXFERS1 and EXTRAXFERS2 to control the number of routes
generated.
First, the program generates minimum-cost routes for all O-D pairs and records the
number of transfers required for these routes, MINXOD. Next, the program searches for
“attractive” routes for each O‑D. Attractive routes depend on the number of transfers:
• If the number of transfers equals MINXOD, number of transfers must be no greater than
MAXFERS .

• If number of transfers exceeds MINXOD, number of transfers must be less than or equal to
the minimum of:
m
MINXOD+EXTRAXFERS2
m
EXTRAXFERS1
m
MAXFERS

The search for routes has two stages. First, the program determines the connections
required to transfer between lines. Second, the program explores the connections and
generates routes by progressing through a sequence of lines and connections. The
program ensures that routes do not exceed the specified constraints.
The following table shows the number of transfers that the program explores for various
values of EXTRAXFERS2 if M AXFERS =5 and EXTRAXFERS1 =4 (the default condition).
N umb e r o f tra ns fe rs e xp lo re d

MIN XOD

0 1 2 3 4 5

E XT R A FE R S 2 0 0 1 2 3 4 5

1 1 2 3 4 4 5

2 2 3 4 4 4 5

3 3 4 4 4 4 5

4 4 4 4 4 4 5

For example, suppose MAXFERS=5, EXTRAXFERS1=4 and EXTRAXFERS2=2. If O-D pairs

have minimum-cost routes with 0, 1, or 2 transfers, the program will explore routes with
up to 2, 3, or 4 transfers (the MINXOD+EXTRAXFERS2 constraint applies). If O‑D pairs have
minimum-cost routes with 3 or 4 transfers, the program explores routes with up to 4
transfers (the EXTRAXFERS1 constraint applies). Finally, for O-D pairs that have minimum-
cost routes with 5 transfers, the program explores 5 transfers (the MAXFERS constraint
applies).
Thus, the program explores more routes for directly connected zone pairs than for less
directly connected zone pairs. This is consistent with observed travel patterns: 70-80%
of trips are completed within two transfers or three transit legs. The program expends
more effort where travelers make a greater proportion of tips.
Public Transport Program > Control statements > FARESYSTEM

FARESYSTEM
Defines fare systems that the program uses to calculate trip fares. Keywords and sub-
keywords include:
• FA R E FR OMFS

• FA R E MA T R IX

• FA R E T A B LE
m INTERPOLATE

• FA R E ZON E S

• IB OA R D FA R E

• LON GN A ME

• N A ME

• N U MB E R

• S T R U CT U R E
m SAME

• U N IT FA R E

Use separate FARESYSTEM statements to define multiple fare systems in public transport
network.
You input the FARESYSTEM statements to the Public Transport program with the FILEI
FAREI file. The program uses fare systems for the evaluation, skimming, loading, and
loading-analyses processes. The program does not use fares in enumeration.
The program allocates fare systems to lines, either indirectly through transit modes and
operators with FACTOR FARESYSTEM , or directly with the LINE control statement.
When modeling fares, you must allocate all lines to fare systems; travelers incur fares
when using the lines. You can code a NULL fare system to run lines effectively free.
Fare systems define the cost of:
• Travel on lines

• Boarding the first line of a trip

• Boarding second and subsequent lines

• Transfers between lines with the same or different fare systems

See “Fares” on page 984 for a description of fares modeling.

Public Transport Program > Control statements > FARESYSTEM > Example 1: Distance with IBOARDFARE + UNITFARE +
SAME=SEPARATE

Exam ple 1: Distance with IBOARDFARE + UNITFARE + SAM E=SEPARATE

FARESYSTEM NUMBER=4,
NAME=DISTANCE,
LONGNAME="WITHOUT FAREFROMFS",
STRUCTURE=DISTANCE, SAME=SEPARATE,
IBOARDFARE=1.35,
UNITFARE=0.83
Public Transport Program > Control statements > FARESYSTEM > Example 2: Zone based “FROMTO” fare system with no
FAREFROMFS

Exam ple 2: Zo ne based “FROM TO” fare system with no FAREFROM FS

FARESYSTEM NUMBER=8,
NAME="FAREZONE-FROMTO",
LONGNAME="WITH FROM-TO FARES",
STRUCTURE=FROMTO, SAME=CUMULATIVE,
FAREFROMFS=10*0,
FAREMATRIX=FMI.1.1,
FAREZONES=NI.FAREZONE

FA R E S Y S T E M k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

FA R E FR OMFS |RVn|1 Optional. Fare incurred when transferring from

fare systems defined by other FARESYSTEM
control statements to this fare system. You can
also provide the cost of transferring between
the same fare system, and incentives (that is,
negative fares) between select fare systems.
For example, consider:
FARESYSTEM NUMBER=3
FAREFROMFS=45, 70, 30
The costs of transferring from fare systems 1, 2,
and 3 to fare system 3 are 45, 70, and 30
monetary units, respectively.
You can include boarding fares applicable at
transfers in FAREFROMFS. You must code
FAREFROMFS in monetary units; the program
converts to generalized cost with
VALUEOFTIME.
The default value is 0.

FA R E MA T R IX |S| Optional. Name of the fare matrix for this fare

system. Must be input with FILEI FAREMATI.
FAREMATRIX is required for
STRUCTURE=HILOW or STRUCTURE=FROMTO
statements, and cannot be used for any other
types.
For STRUCTURE=HILOW, the row of the matrix
represents the lowest fare zone traversed, and
the column the highest fare zone traversed.
For STRUCTURE=FROMTO, the row of the matrix
represents the boarding fare zone traversed,
and the column the alighting fare zone
traversed.
The program converts the fare, derived from
FAREMATRIX, into generalized cost with
VALUEOFTIME.
Valid strings are standard matrix names of the
type: FM.#.# or FMI.#.Name.

FA R E T A B LE |RKV32000| Optional. List of X- and Y-coordinates that

define the table used to compute fares for a
trip’s “length” component (rather than boarding
or transfer components). Other mechanisms
 available are UNITFARE and FAREMATRIX.
You can use fare tables when STRUCTURE is
DISTANCE, COUNT, or ACCUMULATE.
In the coordinates, the X-axis represents trip
length and the Y-axis represents the fare, in
monetary units. For example, if STRUCTURE is
DISTANCE, the X-axis represents distance and
the Y-axis represents fare.
Separate each pair of X and Y values with a
comma or hyphen. Separate each pair of
coordinates with a comma.
For example:
FARESYSTEM NUMBER=11,
NAME="FAREZONE-COUNT",
LONGNAME="WITH FARE ZONES",
STRUCTURE=COUNT, SAME=CUMULATIVE,
FAREZONES=NI.FAREZONE,
FARETABLE=1-1.00, 2-1.75, 3-2.85,
4-4.10, 5-5.5
or
FARETABLE=1,1.00, 2,1.75, 3,2.85,
4,4.10, 5,5.5,
When STRUCTURE is DISTANCE, the curve
runs parallel to the X-axis up to the first coded
point and beyond the last. Thus, if the measure
of trip length is less than the first coded value of
X, the fare is the first coded fare. If the measure
of trip length is greater than the last coded
value of X, the fare is the last coded fare. The
fare, Y, must always be greater than zero, and
either stay the same or increase with trip length;
the fare can never decrease.
(continued)

FARETABLE When STRUCTURE is COUNT, X values must

(continued) range from 1 to the number of fare zones and
increase monotonically. The fare, Y, must
always be greater than zero and increase with
trip length.
When STRUCTURE is ACCUMULATE, X values
must range from 1 to the number of fare zones
and increase monotonically. The fare for each
zone must be greater than zero.
The program converts the fare derived from
FARETABLE into generalized cost with
VALUEOFTIME.

FA R E T A B LE IN T E R P OLA T E |?| Optional. Flag that specifies interpolation

between coded points in the fare table. There
are two possible values:
• T — Linear interpolation between coded
points
• F — Step function.
For example, consider:
FARESYSTEM NUMBER=2 LONGNAME="ALL"
NAME="ALL"
STRUCTURE="DISTANCE",SAME=SEPARATE,
FARETABLE=2.5,0.50, 4.0,0.60,
10,1.2,15,1.50 INTERPOLATE=T
The fare would be 0.70 for a 5-km trip, 1.10 for a
 9-km trip, and 1.32 for a 12-km trip. However, if
INTERPOLATE was F, the fare would be 0.60 for
both the 5-km trip and the 9-km trip, and 1.20 for
the 12-km trip.
INTERPOLATE only applies if STRUCTURE is
DISTANCE. If STRUCTURE is COUNT or
ACCUMULATE, the program assume the curve
is a step function.
Default value is F.

FA R E ZON E S |S| Name of node variable in the input network file

that contains the node’s fare zone number.
Required if STRUCTURE is HILOW, COUNT,
FROMTO, or ACCUMULATE.
Fare zones may represent groups of nodes or
single nodes. The technique for grouping
nodes into fare zones depends on the fare
zone system used. If STRUCTURE is HILOW,
you must use an annular grouping. If
STRUCTURE is COUNT, FROMTO, or
ACCUMULATE, you use sequential grouping.
Valid strings are standard names for node
variables of the type: NI.Name.

IB OA R D FA R E |R| Optional. Fare incurred upon boarding the first

transit leg of a trip. A transit leg might take a part
or the entire length of a line. The program uses
the fare system of the line on which the traveler
completes the first leg.
You must code IBOARDFARE in monetary units.
The program converts the fare into generalized
cost with VALUEOFTIME.
The default value is 0.

LON GN A ME |S| Optional. Second unique string identifier for a

user-defined fare system.

N A ME |S| Optional. Unique string identifier for a user-

defined fare system.

N U MB E R |I| Unique numeric identifier for a user-defined fare

system.
NOTE: Must be first keyword in FARESYSTEM
control statement.
Valid values range from 1 to 1999.

S T R U CT U R E |S| Measure unit for trip length, used to compute

fares.
Possible values include:
• FLAT — Trip length is not relevant for this
fare structure. Calculate fare from
IBOARDFARE and FAREFROMFS.

• DISTANCE — Trip length is in-vehicle

distance, measured in user-specified
units (such as miles or kilometers).
• HILOW — Trip length is the difference
between the highest and lowest fare
zones crossed during the trip (an annular
fare zone structure)
• COUNT — Trip length is a measure of the
 number of fare zones crossed (a
sequential fare zone structure).

• FROMTO — Trip length is an attribute of

the boarding and alighting fare zones.

• ACCUMULATE — Trip length is the

number of fare zones crossed. Each fare
zone has an associated fare which is
accumulated as the zone is traversed.
This differs from COUNT, where the fare
is calculated at the end of the leg or trip
from the total number of fare zones
traversed.
• FREE — Defines a NULL fare system;
lines with such systems give free rides.
Use with caution. For this value, do not
code any other FARESYSTEM keywords.
Data requirements of fare systems vary with
STRUCTURE. See “Fares” on page 984.

S T R U CT U R E S A ME |S| Optional. String that indicates how the program

calculates the fare for consecutive legs of a trip
with the same fare system. Possible values:
• CUMULATIVE — Treat consecutive legs
as one leg when calculating fare
• SEPARATE — Calculate the fare for each
leg separately
The default value is CUMULATIVE.

U N IT FA R E |R| Optional. Cost per unit of the measure defined

in STRUCTURE.
For example, if STRUCTURE is DISTANCE, the
trip cost is UNITFARE * trip distance + boarding
and transfer fares.
Code in monetary units. The program converts
to generalized cost with VALUEOFTIME.
Default value is 0.

1 n is number of fare systems

Public Transport Program > Control statements > FILEI

FILEI
NOTE: See “FILEI” on page 50 for general information about FILEI and for important
limitations when using Application Manager.

Specifies files that may be input to the Public Transport program. Keywords and sub-
keywords include:
• FA CT OR I
m LIST
m MAXERRS
m OMITFARES

• FA R E I
m LIST

• FA R E MA T I

• LIN E I
m LIST
m MAXERRS
m SKIPBADLINES

• LOOKU P I

• MA T I

• NET I

• N T LE GI

• R OU T E I
m I
m J
m REPORTI
m REPORTJ
m SELECTBYMAT
m TRACEI
m TRACEJ

• S CR E E N LIN E I

• S Y S T E MI
m LIST

• T URNPENI
m BASEDATA
m LIST
 m MAXLINKDELAY
m MISSINGLINK
m NOTMODES
m SETS

All FILEI keywords are “trigger” keywords and need not be preceded by the control
statement name.

NOTE: The Public Transport program allows certain types of files to have multiple files.
For example LINEI can have up to 32 files. Due to a restriction on the total number of
files, fewer files than permitted for a particular file type may be active in Application
Manager.

FILE I k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

FACTORI |FKVu|1 Optional. Specifies the names of the

input factor files. You must code explicitly
for each user class, though you can
assign the same file to two or more
classes.
You may input up to ten input factor files,
one per user class. Specify an index, [#],
for each, corresponding to the classes
defined by PARAMETERS
USERCLASSES statement. If there is no
index, the program assumes it to be 1.
FACTORI is required for the route-
enumeration, route-evaluation, loading,
and loading-analyses processes.
However, if you input a Public Transport
network with NETI, do not specify
FACTORI because the network contains
FACTOR data.
Example
FACTORI for USERCLASSES=1,3-4.
User class 3 and 4 use the same factors.
FILEI FACTORI[1]=
FACTSUC1.FAC,
FACTORI[3]=FACTSUC3.FAC,
FACTORI[4]=FACTSUC3.FAC
See “FACTORS” on page 776 for a list of
keywords you can use.

FACTORI LIST |?| Optional. Flag that indicates whether to

list the lines file as input.
• Y — List the lines file as input
• N — Do not list the lines file as input
Default value is N.

FACTORI MAXERRS |I| Optional. Maximum number of errors

allowed in the factor file before the
program stops processing factors.
Default value is 0.
FACTORI OMITFARES |?| Optional. Flag that indicates to validate
fare data in the factor file. Possible
values:
• Y — Omit validation of fare-related
data in the factor file. The output
network file may not be suitable for
use with fares in subsequent runs
of the Public Transport program.
• N — Validate fare-related data in
the factor file.
Default value is N.

FA R E I |FK| Optional. Name of input file defining the

fare systems. The file contains one or
more FARESYSTEM control statements.
Required if the program will consider
fares during route-evaluation and
skimming processes.
See “FARESYSTEM” on page 803 for a
list of keywords you can use.

FAREI LIST |?| Optional. Flag that indicates whether the

list the fare systems as input. Possible
values:
• Y — Lists the fare systems as input
• N — Do not list the fare systems as
input

FAREMATI |FKV| Optional. Name of the input file that

contains one or more matrices used for
computing fares.
You may input up to 99 files. Append an
index to each. If you do not specify an
index, the program assumes the index is
1.
Input files may contain either standard
Cube Voyager binary matrices or
records containing matrix data in the
pattern:
M,I, J, f[j],f[j+1]....f[j+n]
where:
M
Either a name or number, depending
upon how you specify FARESYSTEM
FAREMATRIX. If
FAREMATRIX=FMI.x.name, then M
must match name. If
FAREMATRIX=FMI.x.y, then M
must be the table number, y (x
specifies the FAREMATI index.).
I
Row number. There must be a row
for each fare zone that will use the
matrix.
J
Column number for the 1st f[j] that
follows.
f[j]
 Fare for line j, followed by the fare for
line j+1 and so on. There may be
multiple records for a line.
Delimit files with either commas or white
space.

LINEI |FKVf|2 Optional. Name of input file containing

lines. The file can contain lines in Cube
Voyager format (that is, described with
the LINE control statement), or in TP+
format. You must convert any lines files
in TRIPS format to Cube Voyager format.
To input the lines from a Cube
geodatabase stored in an MDB file,
specify the file name followed by a
backslash and the name of the
geodatabase feature class.
You may input up to 32 lines files.
Append an index to each. Without an
index, the program assigns an index of 1.
Therefore, if inputting only one file, you
need not specify an index. Indexes need
not be monotonic or sequential.
LINEI is required for the route-
enumeration, route-evaluation, loading,
and loading-analyses processes.
However, if you input Public Transport
network with NETI, do not specify LINEI
should not be specified because the
network contains line data.
See “LINE” on page 868 for a list of
keywords you can use.
Valid index numbers range from 1 to 32.
NOTE: LINEI can read, at maximum, two
decimal places for input values. If more
decimal places are specified, Cube will
round the outputs. Please see
“Considerations on numeric formats” on
page 850.

LINEI LIST |?| Optional. Flag that indicates whether to

list the lines file as input. Possible
values:
• Y — List the lines file as input
• N — Do not list the lines file as input
Default value is N.

LINEI MAXERRS |I| Optional. Maximum number of errors

permitted in lines files. When errors
exceed this number, the program stops
processing lines.
Default value is 0.

LINEI SKIPBADLINES |?| Optional. Flag that indicates whether to

treat data errors as warning. Possible
values:
• Y — Downgrade data errors found
when reading lines data to data
warnings. The program will be
able to read the entire input file
without termination due to data
 errors.
• N — Treat data errors as errors.
The default value is the value of
PARAMETERS SKIPBADLINES.

LOOKUPI |FKV999| Optional. Name of file containing records

for a lookup function implemented with
the LOOKUP control statement.
Equivalent to the FILE keyword of the
LOOKUP control statement. You must
index LOOKUPI.

MATI |FKVf|2 Optional. Name of an input matrix file.

You can define up to 10 matrix files to
input. If you do not specify an index, the
program assumes the index is 1.
The Public Transport program only
requires trip matrix files for the loading
process. Because the run can compute
trips, you need not input trip matrix files.
Therefore, you can use the MATI
keyword to input any type of matrix data
into working matrices, and then
manipulate, report, and output the data
with MATO.
Index values can range from 1 to 10.
For example:
FILEI MATI[1]= TRIPSUC1.MAT,
MATI[3]=TRIPSUC3.MAT,
MATI[4]=TRIPSUC3.MAT
This statement names the input matrix
files; the PARAMETERS TRIPSIJ
statement specifies which demand
matrix the Public Transport program
loads for each user class.
NOTE: MATI can read, at maximum, two
decimal places for input values. If more
decimal places are specified, Cube will
round the outputs. Please see
“Considerations on numeric formats” on
page 850.

NETI |FK| Name of the input network file.

Files can be produced by the Network
program or a previous run of the Public
Transport program. Files can be a Cube
binary network file or a Cube
geodatabase network store in an MDB
file. If specifying a Cube geodatabase
network, enter the filename followed by a
backslash and the name of the Cube
geodatabase network.
Networks produced by the Network
program contain just the basic public
transport infrastructure, zones, nodes,
stops, and links.
Networks produced by the Public
Transport program are complete public
transport networks. They contain, in
addition to the basic infrastructure, all the
components that make a public transport
 network:
• System data input with SYSTEMI

• Line data, input with LINEI

• Factor data, input with FACTORI

• Nontransit legs, generated with the

GENERATE control statement, input
with NTLEGI, or both
When produced by a Public Transport
run in which trips were loaded, the public
transport network may also contain
nontransit and transit loads.
Thus, if NETI specifies an input network
produced by the Public Transport
program, you need not provide
SYSTEMI, FACTORI, NTLEGI and LINEI
files unless you invoke the Public
Transport Network Development
function. In this case, the program only
takes the basic network infrastructure
from the NETI file; you must supply all
other components.
(continued)

NETI Starting with Cube 6, PT may optionally

(continued) read station information directly from the
network. The station information should
be presented by various fields as below:
• STANUM — Station number, must
be unique
• STAZ — Station zone number
• MAXD — Maximum distance * 100
for each station
• SPACE — Number of parking
spaces
• STACOST_AM — Station parking
cost (AM)

• STACOST_MD — Station parking

cost (MD)
• STAW_PNR — Station terminal
time (PNR)
• STAW_KN — Station terminal time
(KNR)
• TSTYPE — Station type
• STA_NAME — Station name
• N — Station node number (Same
as network node #)

NTLEGI |FKVf|2 Optional. Name of input files containing

nontransit legs.
To input the nontransit legs from a Cube
geodatabase stored in an MDB file,
specify the file name followed by a
backslash and the name of the
geodatabase feature class.
 You can define up to 32 input files.
Append each keyword with an index,
such as NTLEGI[5]. The GENERATE
READNTLEGI statement defines valid
indexes that the program will process.
Indexes need not be monotonic or
sequential. If you do not specify an
index, the program assumes the index is
1.
See “NT” on page 887 for a list of
keywords you can use.
Index values can range from 1 to 32.
NOTE: NTLEGI can read, at maximum,
two decimal places for input values. If
more decimal places are specified,
Cube will round the outputs. Please see
“Considerations on numeric formats” on
page 850.

ROUTEI |FKVu|1 Optional. Name of the input route files.

Explicitly specify a unique file for each
user class.
You can define up to 10 route files to
input, one per user class. Append each
keyword with the index of the user class.
The PARAMETERS USERCLASSES
statement defines user classes. If you do
not specify an index, the program
assumes the index is 1.
When you define an input route file for a
user class, the program bypasses the
route-enumeration process for that user
class. You can define input route files for
some user classes and generate them
for other user classes.
Index values can range from 1 to 10 (the
number of user classes).
For example, consider:
FILEI ROUTEI[1]=
ROUTESUC1.RTE,
ROUTEI[3]=ROUTESUC3.RTE,
ROUTEI[4]=ROUTESUC4.RTE
This statement defines input route files
for user classes 1, 3, and 4; each user
class has its own route file.
NOTE: ROUTEI can read, at maximum,
two decimal places for input values. If
more decimal places are specified,
Cube will round the outputs. Please see
“Considerations on numeric formats” on
page 850.

ROUTEI I |IV1000| Optional. List of origin zones for the

route-evaluation, skimming, loading, and
loading-analyses processes.
Specify origin zones with single numbers
or pairs of numbers separated by a
dash. Use commas to delimit each
number or pair.
Valid values range from 1 to the
network’s highest zone number.
ROUTEI J |IV1000| Optional. List of destination zones for the
route-evaluation, skimming, loading, and
loading-analyses processes.
Specify destination zones with single
numbers or pairs of numbers separated
by a dash. Use commas to delimit each
number or pair.
Valid values range from 1 to the
network’s highest zone number.

ROUTEI REPORTI |IV1000| Optional. List of origin zones for reporting

evaluated routes. The program writes
the report to file specified with REPORTO.
Specify origin zones with single numbers
or pairs of numbers separated by a
dash. Use commas to delimit each
number or pair.
Valid values range from 1 to the
network’s highest zone number. This
keyword requires REPORTJ (see usage
example below).

ROUTEI REPORTJ |IV1000| Optional. List of destination zones for

reporting evaluated routes.
Specify destination zones with single
numbers or pairs of numbers separated
by a dash. Use commas to delimit each
number or pair.
Valid values range from 1 to the
network’s highest zone number. This
keyword requires REPORTI (above). For
example:
FILEO ROUTEO[1] = "
{CATALOG_DIR}\EVALROUTES.RTE",
REPORTI=1-2299, REPORTJ=1-2299
See “Evaluated routes” on page 927 for
an example of the generated report.

ROUTEI SELECTBYMAT |S| Optional. Matrix used to produce I and J

selections such that the program only
performs the evaluation, skimming,
loading, and loading-analyses
processes for Is and Js that have trips
from and to them. Normally, you specify
the trip matrix being loaded. For
example, MI.x.NAME.
You can use another filter so the
program performs the processes only
for the I-J pairs that have trips between
them:
PROCESS PHASE=SELECTIJ
IF(TRIPSIJ==0)CONTINUE
ENDPROCESS
You can use the I, J, and SELECTBYMAT
subkeywords together. The program
merges them to produce the final I and J
lists.

ROUTEI T R A CE I |IV1000| Optional. List of origin zones for printing

evaluated routes. Routes are reported in
the file specified by REPORTO, using the
tabular-format route report.
 Specify origin zones with single numbers
or pairs of numbers separated by a
dash. Use commas to delimit each
number or pair.
Valid values range from 1 to the
network’s highest zone number.

ROUTEI TRACEJ |IV1000| Optional. List of destination zones for

printing evaluated routes using the
tabular-format route report.
Specify destination zones with single
numbers or pairs of numbers separated
by a dash. Use commas to delimit each
number or pair.
Valid values range from 1 to the
network’s highest zone number.

SCREENLINEI |FK| Optional. Name of a screenline file that

produces intercept data for Public
Transport matrix estimation.
You can create the file with Cube or a
text-file editor. The file must use the “link-
count” format used by Cube Analyst’s
Matrix Estimation program; the turns-
count format is not supported. The file
contains the definition of the screenlines
(in terms of constituent links), along with
link count and confidence-interval data.

SYSTEMI |FK| Optional. Name of the input file

containing public transport system data.
This file contains data for modes,
operators, and wait curves, as
described in the MODE, OPERATOR, and
WAITCRVDEF control statements.

SYSTEMI LIST |?| Optional. Flag indicating whether to list

the public transport system file as input.
Possible values:
• Y — List the public transport system
file as input
• N — Do not list the public transport
system file as input
Default value is N.

TURNPENI |FKV2| Optional. Names of one or two turn-

penalty files. Usually written by the
Highway program, these files contain
records detailing turn penalties or
prohibitions.
Turn penalty movement records have
the following format:
A B C Set Penalty
where:
• A is the entry node to the
intersection
• B is the intersection node
• C is the exit node.
• Set is a number in the range 1-8;
 you select which sets the model
uses.
• Penalty is either -1 to indicate a
prohibited turn in the Highway
model or the value of the junction
delay, measured in minutes.
You can enter one set per record.
Separate the data fields in a record with
white space (either a space or a
comma).
Turn penalty movement records cannot
contain function specifications.
Most model runs that incorporate
junction delays require one turn-penalty
input file. However, for forecast years,
model runs require two turn-penalty input
files, one with base-year delays and one
with forecast-year delays. For such runs,
you support an incremental approach for
forecast years by controlling a line’s
travel times with RUNTIME RT or NNTIME.
NOTE:
• As transit vehicles follow user-
defined routes (which can differ
from general traffic), they ignore
banned turns and only use the
junction delay data
• TURNPENI can read, at maximum,
two decimal places for input
values. If more decimal places are
specified, Cube will round the
outputs. Please see
“Considerations on numeric
formats” on page 850.

TURNPENI BASEDATA |?| Optional. Flag indicating whether turn

penalty file contains base-year junction
delays. Possible values:
• T — File contains base-year
junction delays. The program uses
this file to obtain scaling values,
which scale transit-line travel times
to RUNTIME, RT, and NNTIME
values.
• F — File does not contain base-
year junction delays.
Default value is F.
When applying the incremental
approach to junction delays, the
program reads two turn-penalty files. Set
BASEDATA to T for the file containing the
base-year junction delays, and to F for
the other file, which contains forecast-
year turn penalties.

TURNPENI LIST |?| Optional. Flag indicating whether to

generate a report of turn-penalty values.
Possible values:
• T — Program prints a report that
 lists turn-penalty values used.
When the MAXLINKDELAY
subkeyword limits values, the
report lists the value read from the
file and value the model run used.
• F — Program does not print a
report that lists turn-penalty values
used.
Default value is F.

TURNPENI MAXLINKDELAY |SVn|3 Optional. Name of a link variable that

contains the maximum delay values
(measured in minutes) permitted on
each link in the network.
You can reference the variable as
li.VarName or lw.VarName;
alternatively you can have the program
read the variable from the input network
by setting MAXLINKDELAY=MaxDelay.
Use this keyword to limit the junction
delay a transit vehicle experiences at a
particular turn or junction. The Highway
program assumes that all turning
vehicles are equally delayed.
Therefore, use this keyword when
modeling provisions, such as bus-only
lanes, that reduce delays to public transit
vehicles at turns.
The link variable must specify large
values (for example, 999) for links without
bus-only lanes or other delay-reduction
measures; setting its value to zero would
eliminate junction delays for that link.

TURNPENI MISSINGLINK |I| Optional. Integer that specifies the error

handling when the input network does
not contain a link specified in the turn
penalty file. Possible values:
• 0 — Program ignores such errors.

• 1 — Program prints a warning

message.
• 2 — Program generates a fatal
error message.
Default value is 0.

TURNPENI NOTMODES |I| Optional. List of transit modes that do not

have turning penalties. By default, input
turn-penalty values apply to all transit
modes.
Valid values range from 0 to 999. Default
value is 0.

TURNPENI SETS |I| Optional. Set numbers from the turn-

penalty file that the program includes in
the run; the program discards any non-
matching set numbers.
If a turn has several records, the
program selects those matching the
SETS list. The program uses the record
with the highest set number among those
 selected.
When you specify the default value, the
program selects movements from all
sets. When a movement has multiple
records, the program uses the record
with the highest set number.
Valid values range from 0 to 8. The
default value is 0.

1 FILEI u represents user class

2 f represents file number

3 n represents name of link variable

Public Transport Program > Control statements > FILEI > Example

Exam ple
//Some files that may be input to PT
FILEI FACTORI = factor.fac, list=t
LINEI[1] = lines.lin, list=t
NETI = inetwork.net
NTLEGI = geno.ntl
Public Transport Program > Control statements > FILEO

FILEO
Specifies files that the Public Transport program outputs.
All FILEO keywords are “trigger” keywords and need not be preceded by the control
statement name. Keywords and sub-keywords include:

• IN T E R CE P T O • P R IN T O

• LIN E O • R E P OR T O
m BASEGDBNETWORK • R OU T E O
m m
NET I
m m J
VOL

• LIN KO m REPORTI
m BYCLASS m REPORTJ
m DISTDEC m SELECTBYMAT
m FMVOLS m TRACEI
m FORMAT m TRACEJ
m LINES • S CR E E N LIN E O
m m CONFVAR
NTBYLINK
m m COUNTVAR
NTLEGS
m m DEFCONF
ONELINKREC
m m MEUSESNT
ONOFFS
m m
SKIP0 SCREENVAR
m TIMEDEC • S T OP 2S T OP O
m m ACCUMULATE
VOLFIELDS
m DEC
• MA T O
m m GROUPEDMODES
DEC
m m GROUPS
MO
m m LIST
NAME
m m MODES
TYPE
m m NODES
FORMAT

• NET O m STOPGROUP
m DEC

• N T LE GO
m BASEGDBNETWORK
 m NET
m VOL
m XN

NOTE: The Public Transport program allows certain types of files to have multiple files.
For example PRINTO can have up to 99 files. However, Application Manager restricts the
total number of files. Therefore, fewer files than permitted for a particular file type may be
active in Application Manager at any point.

FILE O k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

INTERCEPTO |FKV10| Optional. Name of an output

intercept file. This file details which
origin-destination pairs have
routes that cross the screenlines.
Cube Analyst uses this file along
with its associated screenline file
when estimating matrices.
You can define up to 10 intercept
files to output, one per user class.
Append each keyword with the
index of the user class. The
PARAMETERS USERCLASSES
statement defines user classes. If
you do not specify an index, the
program assumes the index is 1.
Runs that create matrix estimation
intercept data should either read a
single screenline file, which
provides link and count
information for the screenline, or
write one or more screenline files
(one for each user class), which
contain link and count information
obtained from the input network.

LINEO |FK| Optional. Name of the output lines

file. This file lists all the lines in the
public transport system, in the
LINE control statement format.
To output the lines to a Cube
geodatabase stored in an MDB
file, specify the file name followed
by a backslash and the name of
the geodatabase feature class.
Must be the same geodatabase
specified in NETI or
BASEGDBNETWORK.
NOTE: LINEO can save at
maximum two decimals for travel
time values. Please see
“Considerations on numeric
formats” on page 850.

LIN E O B A S E GD B N E T W OR K |S| Optional. Name of the

geodatabase base-highway
network associated with the output
 lines file. This network must be
consistent with the lines data.
Typically, you reference the
network used as input in the step
that produced the lines.
If NETI specifies a geodatabase
network, you need not specify a
value; Cube Voyager uses that
network as the base-highway
network.The value for this
keyword can be a full path to the
location of the highway network or,
just the name of the network, if the
network is located in the same
geo-database as the FILEO
location.

LINEO NET |S| Optional. Specifies whether the

output lines file contains lines from
the output network or the input
network. Possible values:
• I — Program lists lines in the
input network.
• O — Program lists lines from
the output network.
Input and output networks have
identical line attributes and node
lists, but the loads can vary
depending upon the options
selected.
The default value is O.

LINEO VOL |?| Optional. Flag that indicates

whether to include loading results
(that is, boardings, alightings, and
line and link loads). Possible
values:
• Y — Include loading results
with lines data.

• N — Do not include loading

results with lines data.
Default value is Y.

LINKO |FKV4| Optional. Name of output links file.

This file contains all nontransit
legs and transit links. You can
specify a DBF file or an MDB file.
To output the links to a Cube
geodatabase stored in an MDB
file, specify the file name followed
by a backslash and the name of
the geodatabase feature class.
You can specify up to four files.
Each file might contain different
outputs from a single run of the
program.
The standard output contains data
on the following link attributes:
• A-node
• B-node
 • Mode number

• Name of line traversing link

(for nontransit legs, this is the
mode name)

• Distance
• Time
• SEQ — Sequence number of
this line among the lines that
traverse the link; ranges
from 1 to CNT)
• CNT — Number of lines that
traverse this link
• HEADWAY — Headway of
the line in the specified
HDWAYPERIOD
• Load (if the public transport
network contains loads)
When multiple lines traverse a
link, the output contains one
record for each line.
NOTE: LINKO can save at
maximum two decimals for travel
time values. Please see
“Considerations on numeric
formats” on page 850.

LINKO BYCLASS |?| Optional. Flag indicating whether

outputs are summed by user
class in the links file. Possible
values:
• Y — Program writes the run
totals, summed by user
class, and the attributes
used in the run for each user
class. User class–specific
fields have names with
suffixes, like _1 and _2.
• N — Program writes data not
separated by user class
Default value is N.

LIN KO D IS T D E C |I| Optional. Specifies the number of

decimal places to use for the
network link distance in the output
file. This setting does not apply to
non-transit links. Non-transit links
are always rounded to 2 decimal
places.
Values in the range 0-2 are valid.
Default value is 2.

LIN KO FMV OLS |?| Optional. Flag indicating whether

outputs from a crowding run
contain demand volumes or flow-
metered volumes. Possible
values:
• Y — Program writes the flow-
 metered volumes from the
crowding run.
• N — Program writes the
loaded volumes (represents
the demand volumes for
crowding runs).
Default value is N.

LIN KO FOR MA T |S| Sets the file format of LINKO file.

Possible vaules are:
• TXT — Fixed format text file
• DBF — PIndustry-standard
database file
• CSV — Comma separated
values in plain-text form
NOTE: If the output is in GIS
database (.mdb), the FORMAT
value is ignored. If FORMAT is not
specified, the default format will be
DBF.

LINKO LINES |?| Optional. Flag indicating whether

lines data is included in the output
links file. Possible choices:
• Y — Include line per link
data.
• N — Do not include line data.
Default value is Y.

LINKO NTBYLINK |?| Optional. Flag indicating treatment

of nontransit legs in output file.
Possible values:
• Y — Converts records of
nontransit legs to the
corresponding sequence of
underlying links in the
network (as defined by the
XN keyword in the NTLEG
control statement). From the
output, you can obtain true
nontransit loads for walk
links, and so forth.
• N — Does not convert
records of nontransit legs.
Default value is N.

LINKO NTLEGS |?| Optional. Flag indicating whether

to include nontransit legs in output
file. Possible values:
• Y — Include nontransit legs
in output file
• N — Do not include
nontransit legs in output file
Default value is Y.

LINKO ONELINKREC |?| Optional. Flag that indicates

whether the program combines
 transit data per highway link.
Possible choices:
• Y — Output file contains one
record for each highway link.
When multiple transit lines
traverse a single link, the file
summarizes the data,
combining headways and
summing volumes. The
output contains the following
fields:
m DIST — Link length
m LINECNT — Count of
lines traversing the link
m PERHOUR — Total
services traversing the
link per hour in the
specified
HDWAYPERIOD
m TVOL — Transit loading
for the link
m NTVOL — Nontransit
load on the link
With one record for each
highway link, you can easily
merge data into the highway
network for graphic displays.
• N — Output file contains one
record for each transit line
traversing a highway link.
Multiple transit lines
traversing the same
highway link result in
multiple records for a
highway link.
Typically, you use this keyword
when NTBYLINK is set to Y. Do
not use ONELINKREC when
ONOFFS is set to Y.
Default value is N.

LINKO ONOFFS |?| Optional. Flag indicating whether

to include boardings and
alightings. Default value is N.
When set to Y, program includes
boardings and alightings at each
stop in output file. The file format
differs from the standard output,
and instead contains the following
attributes:
• MODE
• OPERATOR
• NAME — Line name
• LONGNAME
• DIST — Link length
 • TIME — Time needed to
traverse the link
• LINKSEQ — Sequence
number of this link within the
route taken by the line
• HEADWAY — Headway of
the line in the specified
HDWAYPERIOD

• STOPA — 1 if the line stops

at the A-node; 0 otherwise.
• STOPB — 1 if the line stops
at the B-node; 0 otherwise
• VOL* — Transit load using
this line on this link.
• ONA* — Boardings at the A-
node

• OFFA* — Alightings at the A-

node
• ONB* — Boardings at the B-
node
• OFFB* — Alightings at the B-
node
• REV_xx* — Link values for
volume, ons, and offs in the
reverse direction of travel.
These are only nonzero
values for lines that have
ONEWAY set to F. In the
reverse direction of travel,
travelers reach the B-node
before the A-node.
*
Only available if the
public transport network
contains loads
The data records are in line-order
(and stop-order within line). Output
may be produced for run totals
and individual user classes in a
run (see “BYCLASS” on
page 830).
Do not use ONOFFS when
ONELINKREC is set to Y.

LINKO SKIP0 |?| Optional. Flag indicating whether

to omit links with zero loads from
output file. Possible values:
• Y — Omit nontransit legs and
lines and links with zero
loads from output file
• N — Include nontransit legs
and lines and links with zero
loads in output file
Default value is N.

LIN KO T IME D E C |I| Optional. Specifies the number of

 decimal places to use for the
network link travel time in the
output file. This setting does not
apply to non-transit links. Non-
transit links are always rounded to
2 decimal places.
Values in the range 0-5 are valid.
Default value is 2

LINKO VOLFIELDS |?| Optional. Flag indicating whether

to include volume fields in output
file. Possible values:
• Y — Include volume fields
associated with total
loadings. If there are no
loadings, then fields contain
zero values.
• N — Omit volume fields from
output files.
Default value is Y.

MATO |FKV10| Optional. Name of an output matrix

file. Explicitly specify a unique file
for each user class.
You can define up to 10 matrix
files to output, one per user class.
Append each keyword with the
index of the user class. The
PARAMETERS USERCLASSES
statement defines user classes. If
you do not specify an index, the
program assumes the index is 1.
The Public Transport program
produces skim and select link-
analysis matrices, but other types
of matrices, either generated or
input with MATI, may be
manipulated and output with
MATO.
For example, consider:
FILEO MATO[1]=
SKIMUC1.MAT,
MATI[3]=SKIMUC3.MAT,
MATI[4]=SKIMUC4.MAT
This statement generates output
matrix files for user classes 1, 3,
and 4.

MATO DEC |SV*255| Optional. String that specifies the

numeric format of the working
matrices written to the output
matrix file. Specify a separate DEC
for each MO. Valid values:
• 0-9 — Convert output matrix
cells to integers, preserving
indicated number of decimal
places.
• S — Store cells in single-
precision floating-point
format.
 • D — Store cells in double-
precision floating-point
format.
Default value is 2.
Please see “Considerations on
numeric formats” on page 850.

MATO MO |IVP255| Lists the working matrices (MWs)

included in the output matrix file.
You may index MO. The highest
implicit or explicit index
determines the number of
matrices included in the file. If you
do not define a value for an index,
the program outputs a dummy
matrix. You may specify the same
working matrix for more than one
index.
The program numbers output
matrices sequentially beginning
with 1.
For example, consider:
MO=1-5,11-15, MO[20]=1,
MO[19]=31
Given this statement, the program
writes 20 matrices. Matrices 11
through 18 will be dummy
matrices, because the statement
defines no working matrix for
these index values.

MATO NAME |SV255| Optional. Name of matrix (for TP+

and Cube Voyager matrices).
Output matrices do not require
names, but including names helps
document the file. Valid matrix
names contain only alphanumeric
characters, spaces, and
underscores (_). Cube Voyager
programs reading the file can
reference the matrices by name
and/or number.

MATO TYPE |S| Optional. String specifying the

or format of the output matrix file.
Possible values:
FORMAT
• TPP — Standard TP+/Cube
Voyager matrices
• MINUTP — Standard
MINUTP matrices
• TRANPLAN — Standard
Tranplan matrices
• TXT — ASCII records of
matrix values
Default value is TPP.

NETO |FK| Name of the output network file, in

the format of Cube binary network
(*.NET).
The Public Transport program
 outputs a complete public
transport network containing the
following components:
• Basic network infrastructure
of zones, nodes, and links,
produced by the Network
program
• System data, input with
SYSTEMI

• Line data, input with LINEI

• Factor data, input with

FACTORI

• Nontransit legs, generated

with the GENERATE control
statement, input with NTLEGI,
or both
If produced by a run of the Public
Transport program in which trips
were loaded, the public transport
network may also contain
nontransit and transit loads.
You can input this network to the
Public Transport program with
NETI, in which case the file does
not require SYSTEMI, FACTORI,
NTLEGI and LINEI files, unless
you invoke the Public Transport
network-development process.

NETO DEC |S| Optional. String that specifies

precision for storing transit and
nontransit loads in the network.
Possible values:
• 0-9 — Convert loads to
integers, preserving at least
the given number of decimal
places

• S — Store cells in single-

precision floating-point
format
• D — Store cells in double-
precision floating-point
format
The value of impacts the space
required to store the output
network. Integer values require the
least space and preserve
precision to the number of
decimal places specified by DEC.
Single-precision values take up
four bytes and retain precision up
to 6 or 7 decimal places. Double-
precision values require eight
bytes and preserve full precision.
Default value is 2.
Please see “Considerations on
numeric formats” on page 850.
NTLEGO |FK| Optional. Name of output
nontransit legs file.
To output the nontransit legs to a
Cube geodatabase stored in an
MDB file, specify the file name
followed by a backslash and the
name of the geodatabase feature
class. Must be the same
geodatabase specified in NETI or
BASEGDBNETWORK.
This file contains all the nontransit
legs in the public transport
system, in the nontransit control-
statement format.
NOTE: NTLEGO can save, at
maximum, two decimal places for
travel time values. Please see
“Considerations on numeric
formats” on page 850.

N T LE GO B A S E GD B N E T W OR K |S| Optional. Name of the

geodatabase base-highway
network associated with the
nontransit legs file. This network
must be consistent with the
nontransit legs data. Typically,
you reference the network used
as input in the step that produced
the legs.
If NETI specifies a geodatabase
network, you need not specify a
value; Cube Voyager uses that
network as the base-highway
network. The value for this
keyword can be a full path to the
location of the highway network or
just the name of the network, if the
network is located in the same
geo-database as the FILEO
location.

NTLEGO NET |S| Optional. String indicating whether

to include nontransit legs from the
output network or input network.
Possible values:
• O — Include nontransit legs
from the output network in
the nontransit legs output
file.
• I — Include nontransit legs
from the input network in the
nontransit legs output file.
Both files contain identical
attributes for nontransit legs, but
the loads might vary, depending
on the options selected.
Default value is O.

NTLEGO VOL |?| Optional. Flag indicating whether

to include loads with nontransit
legs. Possible values:
• Y — Write loads with
 nontransit legs.
• N — Do not write loads with
nontransit legs.
Default value is Y.

NTLEGO XN |?| Optional. Flag indicating whether

to output nodes. Possible values:
• Y — Output any nodes
between the start and end
nodes of nontransit legs.
See XN under “NT” on
page 887.
• N — Do not output nodes
between the start and end
nodes of nontransit legs.
Default value is Y.

PRINTO |FK| Optional. Name of an output file,

which you have defined in a
PRINT FILE control statement.
Use the PRINT control statement
to format data items and write
them as a single line to the
standard printed output, to a file, or
to both the standard output and a
file.

REPORTO |FK| Name of the file to which the

program writes reports from the
route-enumeration and route-
evaluation processes.
All diagnostics from these
processes are output to the
standard Public Transport–
program print file.

R OU T E O |FKVu|1 Optional. Name of output file

containing enumerated routes.
Explicitly specify a unique file for
each user class.
You can define up to 10 output
files, one per user class. Append
each keyword with the index of the
user class. The PARAMETERS
USERCLASSES statement defines
user classes. If you do not specify
an index, the program assumes
the index is 1.
The statement ROUTEO[x]
invokes the route-enumeration
process for user class x. You can
input previously created
enumerated-route files for some
user classes and build files for
other user classes in the same
run.

ROUTEO I |IV1000| Optional. List of origin zones for

which the program enumerates
routes and saves.
Specify the list as a set of single
 numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
Valid values range from 1 to the
network’s highest zone number.
By default, the program
enumerates and saves routes
originating from all zones.

ROUTEO J |IV1000| Optional. List of destination zones

for which the program enumerates
routes and saves.
Specify the list as a set of single
numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
Valid values range from 1 to the
network’s highest zone number.
By default, the program
enumerates and saves routes
bound for all zones.

ROUTEO REPORTI |IV1000| Optional. List of origin zones for

which the program reports
enumerated and evaluated
routes.
Specify the list as a set of single
numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
The program only includes route
evaluations completed by the
skimming, loading, or loading-
analyses processes. The
program reports routes in the file
specified in REPORTO.
Valid values range from 1 to the
network’s highest zone number.

ROUTEO REPORTJ |IV1000| Optional. List of destination zones

for which the program reports
enumerated and evaluated routes
Specify the list as a set of single
numbers or dash-separated pairs
of numbers that specify a range.
Delimit each number or pair with a
comma.
See “Enumerated routes” on
page 926 and “Evaluated routes”
on page 927 for examples of
these reports.
Valid values range from 1 to the
network’s highest zone number.

ROUTEO SELECTBYMAT |S| Optional. Matrix used to produce I

and J selections such that the
program enumerates and saves
routes only for the Is that have
originating trips and the Js that
have terminating trips. Normally,
 specify the trip matrix being
loaded. For example, MI.x.NAME.
For the evaluation, skimming,
loading, and loading-analyses
processes, you can filter to select
only those I-J pairs that have trips
between them:
PROCESS PHASE=SELECTIJ
IF(TRIPSIJ==0)CONTINUE
ENDPROCESS
Together, all three subkeywords
are merged to produce the final I
and J lists.

ROUTEO TRACEI |IV1000| Optional. List of origin zones for

which the program prints
evaluated routes using the
tabular-format route report.
Specify the list as a set of single
numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
The program reports routes in the
file specified in REPORTO.
Valid values range from 1 to the
network’s highest zone number.

ROUTEO TRACEJ |IV1000| Optional. List of destination zones

for which the program prints
evaluated routes using the
tabular-format route report.
Specify the list as a set of single
numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
See “Evaluated routes” on
page 927 for examples of these
reports.
Valid values range from 1 to the
network’s highest zone number.

SCREENLINEO |FKV10| Optional. Name of the screenline

file the program writes from the
network data. Explicitly specify a
unique file for each user class.
The file contains screenline
definitions and count and
confidence-level data. You pass
this file with an associated
intercept file to a Cube Analyst run
to perform matrix estimation tasks.
You can define up to 10 output
files, one per user class. Append
each keyword with the index of the
user class. The PARAMETERS
USERCLASSES statement defines
user classes. If you do not specify
an index, the program assumes
the index is 1.
The program ignores this
 keyword if you specify the
SCREENLINEI keyword. Cube
Analyst will read that file instead.
Use subkeywords to specify the
source or value of the data fields
that the program writes to the file.
You can reference variables, such
as li.varname or lw.varname.
Alternative, you can use a
subkeyword to read a variable
from the input network, such as
CONFAR=varname.

SCREENLINEO CONFVAR |S| Optional. Name of the input

network’s link variable that
contains confidence-level data.
The confidence level is
expressed as an integer value,
ranging from 1 to 10000.
You must define either CONFVAR
or DEFCONF. Use the DEFCONF
keyword when a single
confidence-level value applies to
all links.

SCREENLINEO COUNTVAR |S| Name of the input network’s link

variable that contains the link-
count data.

SCREENLINEO DEFCONF |I| Optional. Confidence level that

applies to all output links.
If confidence levels vary from link
to link (or screenline to
screenline), use the CONFVAR
subkeyword.
Valid values range from 1 to
10,000.

SCREENLINEO MEUSESNT |?| Optional. Flag indicating whether

link use is restricted to transit
modes. Possible values:
• Y — Program creates
intercept data, considering
link use of all modes (that is,
transit and nontransit)
• N — Program restricts link
use to only transit modes.
Default value is taken from
PARAMETERS MEUSESNT, if
specified; otherwise Y.

SCREENLINEO SCREENVAR |S| Name of the input network’s link

variable that contains the
screenline number.
This variable has a value ranging
from 1 to 9999 when a link forms
part of a screenline, and a zero
value for all other links.

STOP2STOPO |FKV4| Optional. Name of file where the

program saves the results of the
stop-to-stop analyses. File is
 either DBF format or MDB format.
To save results in the Cube
geodatabase (in MDB format),
specify the file name followed by
a backslash and the name of the
geodatabase feature class.
You can specify up to four output
files. Therefore, you can output a
number of different analyses from
a single run of the program. Use
subkeywords to select the types
of stop-to-stop movements
captured. The data saved to the
file can relate to a selection of
stop-nodes or groups of stop-
nodes.
NOTE: Citilabs recommends
producing files no larger than 2
GB, the largest size that Cube
Voyager and Cube Base can
properly process.
The saved file contains the
following data fields:
• Origin zone (I)
• Destination zone (J)
• From stop group
(FROMGROUP)
• To stop group (TOGROUP)
• From stop node
(FROMNODE)
• To stop node (TONODE)
• Mode (MODE)
• Movement type (ACCUM)
m 1=FIRSTLAST
m 2=ADJACENT
m 3=ALLONOFFS
m 4=FIRSLASTBYMODE
m 5=ADJACENTBYMODE
• Number of passengers
(VOL)
NOTE: The file contains either
FROMGROUP and TOGROUP or
FROMNODE and TONODE, but
not both. The two sets of data
fields are mutually exclusive.
See “More on stop-to-stop
analysis” on page 851.

STOP2STOPO ACCUMULATE |S| Optional. Specifies types of transit

movements included in the stop-
to-stop analysis. Possible types
include:
• FIRSTLAST — Movements
from a trip’s first node to last
 node.
• ADJACENT — Movements
and corresponding mode
for each leg of a trip.

• ALLONOFFS — Movements
for all on-off combinations.
• FIRSTLASTBYMODE —
Movements from first node
to last node on a particular
mode, regardless of
intervening modes. Must
specify MODES
subkeyword.
• ADJACENTBYMODE —
Through movements from
first node to last node on a
particular mode. Must
specify MODES
subkeyword.
All movement types other than
ADJACENT can contain one or
more transit legs.
See “More on stop-to-stop
analysis” on page 851.
Default value is FIRSTLAST.

STOP2STOPO DEC |I| Specifies the number of decimal

places to use for the passenger
volume values in the output file.
Values in the range 1-5 are valid.
Default value is 2.

STOP2STOPO GROUPEDMODES |IV999| Optional. List of numbers the

program uses to recode the
modes on transit legs before
completing stop-to-stop analysis
on a route. (Relevant when transit
movement type is
ADJACENTBYMODE or
FIRSTLASTBYMODE).
First number is the mode number
assigned during recoding;
subsequent numbers are the
modes recoded. Thus, any transit
legs with modes listed in the
second are subsequent positions
are assigned to the mode listed
first.
For example, consider:
GROUPEDMODES = 3,6,7,8
The program recodes any transit
legs using modes 6, 7, or 8 to
mode 3.
Valid values range from 1 to the
network’s highest mode number.

STOP2STOPO GROUPS |IV9999| List of stop-groups for which the

program extracts stop-to-stop
movements for the ACCUMULATE
subkeyword. Identify stop-groups
 by number.
Stop-groups are either single
stop-nodes or a collection of stop-
nodes, such as platforms within a
station or clusters of bus stops on
either side of a road. You define a
node’s stop-group number on the
input network’s node record in the
variable specified in
STOPGROUP.
Specify the list as a set of single
numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
If you code both GROUPS and
NODES, the program outputs stop-
to-stop movements for the
specified groups that will include
only the specified nodes. Thus,
you can exclude nodes from their
groups. If you do not code NODES,
the program includes all nodes
belonging to the specified groups
in the analysis. Note that the
program does not explicitly report
nodes in the output file.
NOTE: If you code neither NODES
nor GROUPS, the program
generates a fatal error.
Valid values range from 1 to the
network’s highest stop-group.

STOP2STOPO LIST |?| Optional. Flag indicating whether

to list the contents of the DBF file
to the printer file. Possible values:
• Y — List contents of the DBF
file to the printer file
• N — Do not list of contents of
the DBF file to the printer file
Default value is N.

STOP2STOPO MODES |IV999| Optional. List of modes for which

the program accumulates stop-to-
stop movements when
ACCUMULATE is
FIRSTLASTBYMODE or
ADJACENTBYMODE.
Specify the list as a set of single
numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
Valid values range from 1 to the
network’s highest mode. Default
value is all modes.

STOP2STOPO NODES |IV9999| List of stop nodes for which the

program extracts stop-to-stop
movements for the ACCUMULATE
subkeyword.
 Specify the list as a set of single
numbers or dash-separated pairs
of numbers that give a range.
Delimit each number or pair with a
comma.
This subkeyword is required if
GROUPS is not coded.
Valid values range from 1 to the
network’s highest node.

STOP2STOPO STOPGROUP |S| Optional. Name of the node

variable that contains the stop-
group number.
If you code GROUPS, you must
code STOPGROUP.
For example, with
STOPGROUP=SGNAME, then the
node variable NI.SGNAME stores
the stop-group numbers, used in
GROUPS.
When using stop groups, the
program reports on intragroup
movements, but cannot
disaggregate those movements
to the nodes in the group.

1 u represents user class

Public Transport Program > Control statements > FILEO > Example > Example

Exam ple

Some files that may be output by the Public Transport program.

FILEO NETO = onetwork.net
REPORTO = reports.prn
ROUTEO = enumroute.rte, I=1,15,24, J=1,24, REPORTI=1,15,24 REPORTJ=1,9, 15,24
Public Transport Program > Control statements > FILEO > Example > Example of SCREENLINEO & INTERCEPTO

Exam ple o f SCREENLINEO & INTERCEPTO

RUN PGM=PUBLIC TRANSPORT

FILEO REPORTO = "PAPTR00B.PRN"

FILEO ROUTEO[1] = "PAPTR00B.RTE"
FILEO SCREENLINEO = "PT ANALYST EXAMPLE\PAPTR00B.DAT",
SCREENVAR=SCRLNO COUNTVAR=PTCOUNT CONFVAR=PTCONF
FILEO INTERCEPTO = "PAPTR00B.ICP"
FILEI NETI = "PAPTR00D.NET" ; PT network output from PT program

ENDRUN
Public Transport Program > Control statements > FILEO > Considerations on numeric formats

Considerations on numeric formats

Traditionally planners have maintained most transportation planning matrices in integer
format. Advantages included:
• Integer values take less space than floating point values

• Matrix values usually can be represented with numbers where a fixed decimal place can be
assumed.

In the past, computers could process integers much faster than floating point numbers.
However, this is not necessarily true with newer computers.
Single-precision floating point provides only six to seven digits of precision, and cannot
always maintain the precision required for certain types of matrices. Cube Voyager
processes all matrices in double-precision (16 digits) format to accommodate a wider
range of values, and to not lose precision or accuracy when computing. However, writing
double-precision numbers to the matrix files would generate very large files, and in most
cases, only a few decimal places are required for each cell value. Therefore, the Public
Transport program stores matrix values with a special packing routine that tries to
minimize the file’s space requirements.
The Public Transport program tries to convert each number to an integer starting with 0
decimal places and continues with the next power of 10 until it reaches the maximum
level specified. The program uses the lowest level that converts to an integer with no
loss of precision. If a scaled cell value is too large to fit within a 32-bit integer, the
program stores the cell as a double-precision value. If is D or S, the program skips the
integer conversion attempt and stores all cells as either 8-byte double values or 4-byte
single values. If not specified, defaults to 2.
For example, consider a cell computed as 10/3. The result is 3.33333333.... to sixteen
digits. When changed to single precision, the result is accurate to about seven digits,
requiring four bytes to store. If converted to an integer while is 0, the result is 3, and the
cell would require only one byte to store—a significant reduction. However, that might not
be precise enough for the programs that read it. If is 2 for that number, the resulting
integer is 333, requiring two bytes to store. Upon reading, another application will
automatically restore the number to 3.33. If were S, the value would be stored as a 4-
byte single-precision, and if were D, it would be stored as an 8-byte double-precision.
The S and D formats require more storage space.
Public Transport Program > Control statements > FILEO > More on stop-to-stop analysis

More on stop-to-stop analysis

For stop-to-stop analysis, the movement type affects the output records. When the
movement type is 4 or 5 (ACCUMULATE is FIRSTLASTBYMODE or
ADJACENTBYMODE), the program writes output records that reflect the modes used in
the route’s transit legs. The program analyzes a transit route based on the values of
other STOP2STOPO subkeywords, and saves the appropriate records.
Use the GROUPEDMODES subkeyword to recode modes prior to transit-route analysis.
With this keyword, you can group distinct modes of the route together, allowing them to
appear as one mode for analysis and in subsequent data output.
For example, a model might use two or more mode numbers for different types of rail
travel. You might be more interested in transfer to or from rail than in changes between
the different rail modes. By grouping the discrete rail modes together, you eliminate this
detail from the analysis.
Public Transport Program > Control statements > FILEO > More on stop-to-stop analysis > Example of ACCCUMULATE
subkeyword

Exam ple o f ACCCUM ULATE subkeywo rd

Suppose you have a five-leg, two-mode trip:

1. 1-2 on mode 1

2. 3-4 on mode 1

3. 5-6 on mode 2

4. 7-8 on mode 1

5. 9-10 on mode 1

V a lue o f
A CCU MU LA T E Mo v e me nts a na ly ze d

FIRSTLAST 1-10

ADJACENT 1-2, 3-4, 5-6, 7-8, 9-10

ALLONOFFS 1-2, 1-4, 1-6, 1-8, 1-10, 3-4, 3-6, 3-8,

3-10, 5-6, 5-8, 5-10, 7-8, 7-10, 9-10

FIRSLASTBYMODE 1-10 mode 1

5-6 mode 2

ADJACENTBYMODE 1-4 mode 1

5-6 mode 2
7-10 mode 1
Public Transport Program > Control statements > GENERATE

GENERATE
Generates nontransit legs in the public transport network. Keywords include:

• A CCE S S LIN K • MA XCOS T

• COS T • MA XN T LE GS

• D E FD R IV E T IME • MIN COS T

• D IR E CT ION • N T LE GMOD E

• D IR E CT LIN K • ON E W A Y

• E XCLU D E LIN K • P N R MOD E

• E XT R A CT COS T • R E A D N T LE GI

• FR OMN OD E • S LA CK

• IN CLU D E LIN K • T ON OD E

• LIS T • XFE R ME T H OD

You can generate, input, or generate and input nontransit legs.

You can use one or more GENERATE control statements to generate nontransit legs, each
with different criteria. Use the READNTLETI keyword to input previously generated and
validated nontransit legs or externally generated ones.
The Public Transport program maintains one table of nontransit legs. The program
dynamically updates the table while processing GENERATE statements. The program
keeps one leg for each A-node–B-node combination in the table—the leg with the lowest
EXTRACTCOST, followed by the leg with the lowest distance (DIST), and then the leg with
the lowest NTLEGMODE. After processing all GENERATE statements, the program saves the
legs in the table to the Public Transport network file specified by NETO and/or the file
specified by NTLEGO. If you specify neither file, the program discards the legs at the end
of the run.
Use the necessary keywords to control the nontransit link-generating process produced
by the GENERATE statement. With this statement, the program:
• Builds minimum-cost routes between each node specified with FROMNODE to each node
specified with TONODE that is a transit stop. The program ignores nodes specified in TONODE
that are not stop nodes.

• Finds transit modes at each node specified in TONODE, computes the cost to the node, and
compares the cost to the mode’s MAXCOST. If the cost for at least one of the modes is less
than the mode’s MAXCOST and if the specification in DIRECTLINK is satisfied, the program
saves the leg.
• Examines each saved leg, adding acceptable legs to the legs table. The program adds the
best leg for a mode, and legs that service that same mode and whose cost does not
exceed the cost of the best leg for that mode plus the SLACK for that mode. If SLACK is not
specified, the slack for a mode effectively becomes the difference between the best cost
and the MAXCOST for the mode. MAXNTLEGS specifies the maximum number of legs the
program will generate for a mode from a FROMNODE.

• Merges legs using any special transaction codes. For example, you might specify that the
program replace a generated leg with a longer leg. See NTLEGI under “FILEI” on page 811.

None of the GENERATE keywords are “trigger” keys; you must code all keywords on a
GENERATE control statement.

GENERATE statements must be in the DATAPREP phase.

GE N E R A T E k e y wo rd s

Ke y wo rd D e s c rip tio n

A CCE S S LIN K |R| Optional. One or more access links from park-and-
ride facilities to stop nodes.
Specify an access link as:
A-S,cost,distance
where:
• A — Surrogate access point (integer)
• S — Stop node (integer)
• cost — Optional. Cost of using this access link
(real).
• distance — Optional. Distance traveled on this
access link (real).
Separate each access link with a comma.
If the link does not exist in the network, the program
generates the link.
You specify pairs of numbered sets. Paired values
indicate the start of new access links. Enter paired
values in the correct order to avoid generating an
error.
If you specify ACCESSLINK, the program ignores
any TONODE keywords. The program obtains the
cost from the route to the A-node. If ACCESSLINK
provides numeric values for cost and distance, the
program adds them to the link’s cost and distance.
If ACCESSLINK only contains one value, the
program adds that value to the link’s cost.
Valid values for A and S are 1 to the network’s
highest node number.

COS T |N| Expression for computing network link costs. Used

to determine the minimum-cost nontransit legs
between the nodes specified in FROMNODE and
TONODE (or ACCESSLINK). Enclose expressions
in parentheses.
The expression can contain network data items,
such as link distance, time, and speed.
The cost of nontransit legs may be the cost on the
 basis of which they are built or, you can skim the
cost specified by EXTRACTCOST from the network
links underlying the nontransit legs.
For example, consider:
GENERATE,
COST=li.Distance,
EXTRACTCOST=li.Time,
NTLEGMODE=32
This script fragment generates nontransit legs on
the basis of minimum distance, but skims time
along the minimum-distance legs and saves as the
cost.
To obtain the perceived nontransit cost, you can
factor the nontransit leg cost, derived from COST or
EXTRACTCOST, with the FACTORS RUNFACTOR
control statement, which is specified by mode. The
sample script fragment produces nontransit legs
with a mode of 32. You can factor with
RUNFACTOR[32]=x.x.
The route-enumeration and evaluation processes
use perceived (or factored) costs; both actual and
perceived costs may be skimmed.

D E FD R IV E T IME |R| To specify default drive-access time used if time

from matrix is zero (DEF).

D IR E CT ION |I| Optional. Integer indicating direction of the

generated nontransit legs. Possible values:
• 1 — Forward direction, FROMNODE to
TONODE

• 2 — Reverse direction, TONODE to

FROMNODE

• 3 — Both directions, FROMNODE to and from

TONODE
Default value is 3.
NOTE: Forward direction NTlegs are always
generated starting at the FROMNODE(s). The
reverse direction NTlegs from the same
FROMNODE(s) will follow the same links in
opposite order. Be aware that PT will add new
reverse-direction links to the output links (LINKO) as
neccesary to accommodate the NTlegs.

D IR E CT LIN K |I| Optional. Maximum number of network links a

nontransit leg can traverse.
By default, the program applies no limit to number
of links.

E XCLU D E LIN K |N| Optional. Expression that computes the network

links to exclude from the generation of nontransit
legs. Enclose expressions in parentheses.
You may exclude links from the GENERATE process
with network data items, such as link distance, cost,
and classifiers.

E XT R A CT COS T |N| Optional. Expression that computes the network link

costs skimmed from nontransit legs built on the
basis of COST. The skimmed costs become the
costs of the nontransit legs. Enclose expressions in
parentheses.
 The expression can use network data items, such
as link distance, time, and speed, to compute the
cost.
If you do not specify this keyword, the program
derives the cost of nontransit legs from the COST
keyword.
To compute perceived nontransit costs for use in
the enumeration and evaluation processes, you
can factor the nontransit leg-cost derived from
COST or EXTRACTCOST with the FACTORS
RUNFACTOR control statement.

FR OMN OD E |S| Optional. Node or list of nodes that program

generates nontransit legs from.
You may specify nodes as numeric values or
names of variables that store valid numeric values.
For example, you might specify:
FROMNODE=1-NUMZONES
Valid values range from 1 to the network’s highest
node number.

IN CLU D E LIN K |N| Optional. Logical expression (following syntax of

Control fields) that computes network links included
in the generation of nontransit legs. Enclose
expressions in parentheses.
The expression can only use numeric network data
fields, such as link distance, cost, and classifiers, to
determine included links.
For example:
INCLUDELINK = (LI.LINKTYPE=1-32)
INCLUDELINK =
(LW.LTYPE=14,20,23,27,28)
INCLUDELINK = (LI.WALKTIME>0)

LIS T |?| Optional. Flag indicating whether to list nontransit

legs. Possible values:
• T — List each nontransit leg and the network
links traversed.
• F — Do not list nontransit legs.
Default value is F.
See “More on using LIST keyword” on page 862.

MA XCOS T |RVt*|1 Maximum cost allowed for a particular transit mode

to enable generation of nontransit legs. Specify
cost per mode.
The program generates a leg to a TONODE
serviced by a transit mode only when the cost to
that node is less than the MAXCOST for that transit
mode.
You must specify MAXCOST for at least one mode.
The default value is 0. Therefore, the program
generates no trips to nodes serviced by modes
without a MAXCOST specified, unless other non-
zero modes service the node.
When determining the maximum cost for a leg, the
program uses the mode of the TONODE. However,
if the TONODE specifies a zone, the program uses
the mode of the FROMNODE.
The value of SLACK affects the value of
MAXCOST.
 Valid values are 0 to 500 (in the same units
specified in COST).

MA XN T LE GS |IVt|1 Optional. Maximum number of nontransit legs to

generate for a particular transit mode from a
FROMNODE to a TONODE serviced by that mode.
Valid values range from 1 to 999. Default value is 5.
If both FROMNODE and TONODE are zones, the
program ignores MAXNTLEGS.

MIN COS T |RVt*|1 Optional. Minimum cost allowed for a particular

transit mode to enable generation of nontransit
legs. Specify cost per mode.
The program generates a leg to a TONODE
serviced by a transit mode only when the cost to
that node is more than the MINCOST for that transit
mode.
When determining the minimum cost for a leg, the
program uses the mode of the TONODE. However,
if the TONODE specifies a zone, the program uses
the mode of the FROMNODE.
Valid values are 0 to 500 (in the same units
specified in COST). Default value is 0.

N T LE GMOD E |I| Nontransit mode assigned to the generated

nontransit legs.
Valid values range from 1 to 999.
You must specify a value.

ON E W A Y |?| Optional. Flag indicating how to use one-way links

when generating nontransit legs. Possible values:
• F — Permits one-way links to be traversed in
both directions
• T — Restricts one-way links to the coded
direction
Default value is T.

P N R MOD E |I| To allow user specify the mode for PNR

connectors

R E A D N T LE GI |I| Optional. Index number of the input nontransit leg

file. You must code a corresponding FILEI NTLEGI
statement.
When you code READNTLEGI, the program reads
nontransit legs from a file and merges them into the
generated links table. The NT control statement
determines the format of the input records. Delimit
data fields with commas or spaces.
Use FROMNODE and TONODE with READNTLEGI
to filter input records through the from- and to-
nodes. No other keywords are valid with
READNTLEGI.
Use a separate GENERATE statement for each
nontransit leg file input.
Valid values range from 1 to 7.

S LA CK |RVt|1 Optional. Amount added to the best-cost nontransit

leg between the two nodes to determine the
maximum cost of legs saved. Specify per mode.
SLACK provides a secondary control for restricting
 the generation of nontransit legs. MAXCOST
provides the primary control. The program
generates legs from a FROMNODE to a TONODE if
their costs is less than or equal to MAXCOST for the
mode that services the TONODE. With SLACK
specified, the program only generates legs from a
FROMNODE to a TONODE if their costs is also less
than or equal to the best cost between the nodes
plus the SLACK for the mode that services the
TONODE.
For example, consider:
MAXCOST[4]=20, SLACK[4]=8
If the best leg has a generalized cost of 6 minutes,
the program will save legs with a cost up to 14
minutes.
If you do not specify SLACK, the program only uses
MAXCOST to limit nontransit-leg generation. If
SLACK is set to zero, the program only saves the
best-cost legs.
SLACK generally refers to the modes serviced by
the TONODE. However, if the TONODE is a zone,
the program obtains the mode from the
FROMNODE. If both FROMNODE and TONODE are
zones, the program ignores SLACK.
Valid values are 0 to 500 (in the same units
specified in COST). Default value for any mode is
the value of MAXCOST for that mode.

T ON OD E |S| Optional. Node or list of nodes to which the

program generates nontransit legs.
Specify nodes as numeric values or names of
variables that store valid numeric values.
The program ignores TONODE if the GENERATE
control statement contains the ACCESSLINK
keyword.
Valid values range from 1 to the network’s highest
number. By default, set to include all nodes
(number of zones +1 to the network’s highest node
number).

XFE R ME T H OD |I| Optional. Integer that specifies algorithm program

uses to execute GENERATE control statement.
Version 4.1 introduced a new algorithm that creates
nontransit legs between pairs of nodes where a
transit line operates. Earlier versions excluded
such legs, possibly preventing valid routes.
Possible values:
• 0 — Use the latest algorithm (currently, the
algorithm developed with version 4.1). Use
this setting when modeling best-path routes
(that is, when FACTOR BESTPATHONLY=T).

• 1 — Use the algorithm from version 4.0 when

creating nontransit legs.
• 2 — Supplement the version 4.0 algorithm for
generating connectors with the additional
connectors created with the version 4.1
algorithm.
The program creates an initial set of nontransit
legs using keywords such as MAXCOST,
 MAXNTLEGS, and SLACK as in version 4.0.
Next, the program uses the version 4.1
algorithm to create additional legs, using the
maximum costs from the initially-generated
legs as limits. The total number of legs
generated might exceed limits specified in
MAXNTLEGS.
This value is appropriate for models
developed under version 4.0, if you wish to use
newly identified connectors while not losing any
previously generated connectors.
• 3 — Use the algorithm from version 4.1
(currently the same result as setting to 0).
Default value is 0.

1 t indicates number of transit modes

Public Transport Program > Control statements > GENERATE > Example — Access, Egress and Transfer Legs > Example
— Access, Egress and Transfer Legs

Exam ple — Access, Egress and Transfer Legs

The first GENERATE statement produces access legs from zones to the public transport
system and egress legs in the reverse direction. The second GENERATE statement
produces transfer legs between stops.
PHASE=DATAPREP
//Note: the GENERATE command must precede controls
//GENERATE 1: Access and Egress links for zones 1-1272
GENERATE,
NTLEGMODE=100,
MAXCOST=20*20.0,
COST=li.time,
FROMNODE=1-1272,
TONODE=1273-5644,
DIRECTION=3,
INCLUDELINK=(li.LINKTYPE=30-32),
SLACK=20*5.
MAXNTLEGS=20*5,
DIRECLINK=5

//GENERATE 2: Transfer legs for the PT Network

GENERATE,
NTLEGMODE=100,
MAXCOST=20*10.,
COST=LI.Distance*60/4.80,
FROMNODE=1273-5644,
TONODE=1273-5644,
DIRECTION=3,
INCLUDELINK=(li.LINKTYPE=1,4,8-13,20,30-32),
SLACK=20*5.,
MAXNTLEGS=5,
ENDPHASE
Public Transport Program > Control statements > GENERATE > More on using LIST keyword

More on using LIST keyw ord

You may use one or more GENERATE statements to generate nontransit legs. While
processing statements, the program adds legs to a table of nontransit legs. The table
stores exactly one leg for each combination of A-node and B-node—the one with the
lowest EXTRACTCOST, followed by the one with the lowest distance (DIST), followed by the
one with the lowest NTLEGMODE.
If a GENERATE statement has LIST set to T, the program lists the legs in the table when
that statement is processed. Though the program might list a leg during GENERATE, that
leg might not be included in the final table of legs. Similarly, a GENERATE statement might
list one leg, and a later GENERATE statement a different leg, if the later statement revises
the leg.
To view or report the final set of nontransit legs, save them to the file specified with the
FILEO NTLEGO control statement.

The following example illustrates this process:

LIST='GEN1'
GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1,
NTLEGMODE = 36, LIST=T, DIRECTION=3, FROMNODE=1, TONODE=2052

LIST='GEN2'
GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1,
NTLEGMODE = 36, LIST=T, DIRECTION=3, FROMNODE=1, TONODE=2052

LIST='GEN3'
GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1,
NTLEGMODE = 35 LIST=T, DIRECTION=3, FROMNODE=1,TONODE=2052

The printed result of this will be:

GEN1
Link 1 2052 36 0.18 0.36 1 3674
Link 2052 1 36 0.18 0.36 1 3674
GEN2
GEN3
Link 1 2052 35 0.18 0.36 1 3674
Link 2052 1 35 0.18 0.36 1 3674
M(625): 2 Nontransit Legs

The final nontransit legs saved will be: 1 - 2052 - 35 (and reverse)
Public Transport Program > Control statements > GOTO

GOTO
Jumps immediately to a named statement.
GOTO label

When GOTO is processed, flow immediately branches to the target statement, named
“:label.” Each GOTO statement must have an associated :label statement. Use care when
the :label statement is within a different IF or LOOP block. The target statement must begin
with a colon (:).
Public Transport Program > Control statements > GOTO > Example

Exam ple

In this example, the GOTO statement passes control in the forward and backward
directions.
GOTO hwybuild
.....
.....
:hwybuild
IF (expression) GOTO :hwybuild
Public Transport Program > Control statements > IF... ELSEIF ... ELSE ... ENDIF

IF... ELSEIF ... ELSE ... ENDIF

Performs certain operations based on conditions.
There are two forms of this control statement:
• A single statement:
IF (expression) statement

• A block of statements:
IF (expression)
ELSEIF (expression)
ELSE (expression)
ENDIF

You must predefine any expression variables in an earlier COMP VAR statement. (The
program automatically defines any variables not predefined, but with a dot (.) in their
name as numeric variables.)
You may nest but not overlap IF... ELSEIF ... ELSE ... ENDIF blocks. They may not overlap
LOOP ... ENDLOOP blocks.

You may append the following control statements to a single IF statement:

• BREAK

• COMP

• CONTINUE

• EXIT

• GOTO

• PRINT
Public Transport Program > Control statements > IF... ELSEIF ... ELSE ... ENDIF > Example

Exam ple

Two of uses of the single IF statement.

IF (matrix.time_to_bcd > 200000) GOTO :SKIPZONE
IF (expression) EXIT

One example of the IF block statement.

IF((j=3-5,6-30,57 & k=(2*j-4)) || ((J*k) = 14-20,56))
....
ELSEIF (loop_cntr > 10)
....
ELSEIF (loop_cntr > 5 && diff.time < 32)
....
ELSE
....
ENDIF
Public Transport Program > Control statements > JLOOP ... ENDJLOOP

JLOOP ... ENDJLOOP

Controls a loop over the column cells (J) of the current row (I) in a matrix. Keywords
include:
• J

Each row represents an origin (I) zone and each column represents a destination (J)
zone. Typically, you use JLOOP ... ENDJLOOP blocks for matrix computations that you
cannot complete with a single COMP M W control statement.
JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks.
J LOOP k e y wo rd s

Ke y wo rd D e s c rip tio n

J |I| Optional. List of up to three integers that define the value of

the loop control variable. You may define each integer with
an expression. Specify as:
J=Jbeg, Jend, Jinc
where:
• Jbeg defines the initial value of the loop’s control
variable, J. Default value is 1. If you do not define
Jbeg, you cannot define Jend or Jinc. In that case,
Jend defaults to the number of zones in the network,
and Jinc defaults to 1.
• Jend defines the terminal value of the loop’s control
variable, J. Valid values range from 1 to the network’s
maximum number of zones. If not specified, Jend
defaults to Jbeg, and Jinc defaults to 1.
• Jinc defines the increment for the loop’s control
variable, J. If not specified, set to 1 or -1, depending
on the direction from Jbeg to Jend.
Because the list of values for J can be expressions, you
must separate the values with commas. Enclose
expressions containing commas in parentheses.

A JLOOP block causes the program to loop between the JLOOP statement and its
ENDJLOOP statement, moving J from Jbeg to Jend in increments of Jinc. The logic for
JLOOP and ENDJLOOP processing is:

• At JLOOP:
m
If J is specified, establish values for Jend and Jinc.
m
Else set J=1, Jend=Zones, Jinc=1.
m
If (J < 1 or J > Zones or Jend <1 or Jend > Zones), terminate fatally.
m
Process statements within JLOOP.
• At ENDJLOOP:
m
Add Jinc to J.
m
If (Jinc > 0 and J <= Jend) go to statement following JLOOP.
m
If (Jinc < 0 and J >= Jend) go to statement following JLOOP.
m
Control passes to statement following ENDJLOOP.

The program processes all statements between the JLOOP and ENDJLOOP statements,
including COMP MW statements, with the current value of J.
The following statements are valid within a JLOOP block:
• BREAK

• COMP

• CONTINUE

• EXIT

• GOTO (:la b e l statement must be inside current JLOOP)

• IF... ELSEIF ... ELSE ... ENDIF

• PRINT

JLOOP processing varies by phase.

P ha s e J LOOP p ro c e s s ing

NODEREAD Program executes JLOOP for each node or link

and processed.
LINKREAD 1

DATAPREP1 Program executes JLOOP once.

MATI and Program executes JLOOP once per matrix row (or
MATO origin zone). You may use J keyword to select
destination zones.

SELECTIJ JLOOP is invalid (the phase is executed once per

and SKIMIJ I-J pair)

1 Program performs no matrix processing during these phases. Therefore, there is no destination zone.
However, JLOOP statements are valid, and will act as a zonal loop.
Public Transport Program > Control statements > JLOOP ... ENDJLOOP > Example 1

Exam ple 1

Compute the sum of each row for two matrices.

ROWSUM1 = 0
ROWSUM3=0
JLOOP
ROWSUM1 = ROWSUM1 + MW[1]
ROWSUM3 = ROWSUM3 + MW[3]
ENDJLOOP
Public Transport Program > Control statements > JLOOP ... ENDJLOOP > Example 2

Exam ple 2

Print the first ten cells of each row.

JLOOP J=1,25
TRIPSIJ=MI.1.1 * 0.75
IF(J > 10) BREAK
PRINT LIST=I, J, TRIPSIJ
ENDJLOOP
Public Transport Program > Control statements > LINE

LINE
Describes the attributes of public transport lines, including the nodes the line traverses
and attributes of those nodes. Keywords and sub-keywords include:

• A LLS T OP S • ON E W A Y

• CIR CU LA R • OP E R A T OR

• COLOR • R U N IN T E R V A L

• CR OW D CU R V E • R U N T IME

• CR U S H CA P • S E A T CA P

• DAYT YPE • S H OR T N A ME

• FA R E S Y S T E M • S T A R T T IME S

• FMCA P A CIT Y • T IME FA C

• HEADW AY • U S E R A 1, U S E R A 2,
U S E R A 3, U S E R A 4,
• H E A D W A Y _R USERA5
• LOA D D IS T FA C • U S E R N 1, U S E R N 2,
U S E R N 3, U S E R N 4,
• LON GN A ME
USERN5
• MOD E
• V E H ICLE T Y P E
• N A ME
• XY S P E E D
• N OD E S o r N
m ACCESS
m ACCESS_C
m DELAY
m DELAY_C
m DWELL
m DWELL_C
m FMOFF
m NNTIME

m OFF1

m ON 1
m RT
m SPEED
m TF
m TIME

m VOL1
 m XYSPD

LINEkeywords describe the line’s attributes. Some are required; some are optional.
None are “trigger” keys; you must code all keywords on a LINE control statement.
You may input lines to the Public Transport program in ASCII format, in up to seven files
with FILEI LINEI, or in the Public Transport network file with FILEI NETI.
The Public Transport program outputs lines to the binary Public Transport network
defined by FILEO NETO and to the ASCII file defined by FILEO LINEO .
When crowding is used, the Public Transport program’s Loading Models append results
of a crowd run to the output LINE data with the FM CAPACITY keyword.
Lines traverse two or more nodes, which you define with the NODES keyword. Nodes
have their own attributes, defined with subkeywords (ACCESS , ACCESS_C , DELAY,
DELAY_C , NNTIM E , RT , SPEED , TF , TIM E , and XYSPD ). The Public Transport program’s
loading models append the results of the loading process to line nodes, using the
keywords FM OFF , FM ON , FM VOL , OFF 1 , ON 1 , and VOL 1 . These data items form part of an
output FILEO LINEO file, but the program does not read this data when processing a
FILEI LINEI file.
Several of the LINE keywords and NODES subkeywords adjust network link times by line.
See “Calculation of line/link times” on page 883 for an explanation of how they interact
with each other to produce the adjusted link times.
LIN E k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

ALLSTOPS |?| Optional. Flag indicating whether all

nodes in the line are stop nodes.
Possible values:
• T — Program makes all the line’s
nodes into stop nodes, even those
explicitly designated as nonstop
nodes.
• F — Program uses node
designation.
Default value is F.

CIRCULAR |?| Optional. Flag indicating whether a line

is circular or linear. Possible values:
• T — Indicates line is circular.
• F — Indicates line is linear.
Default value is F.
The first and last node of a circular line
must be the same node and both
boarding and alighting can take place at
this node. A route can go through this
node without incurring any boarding and
transfer penalties or waiting time.
 Linear lines may also have the same
first and last nodes but passengers must
incur a boarding— that is, boarding and
transfer penalties plus wait time— for
routes passing this node.

COLOR |I| Color that Cube Base uses to display

the line.

CROWDCURVE |IV10| Optional. Crowd curve used to adjust link

travel times for a modeled user class.
You may code CROWDCURVE in
conjunction with the VEHICLETYPE
keyword to override crowd-curve values
specified on the VEHICLETYPE control
statement and provide line-specific
curves instead.
Valid values range from 1 to 255. Default
values are those specified in the
VEHICLETYPE control statement.

CRUSHCAP |I| Optional. Crush capacity (that is, sum of

seated and maximum-standing
capacities) of vehicles operating on this
line. Must be greater than or equal to any
specified seating capacity.
You may code in conjunction with the
VEHICLETYPE keyword to override the
crush-capacity value specified with the
VEHICLETYPE control statement and
provide a line-specific capacity instead.
Valid values range from 1 to 20,000.
Default values are those specified in the
VEHICLETYPE control statement.

DAYT YPE |IPa*| List of day types on which line operates.

List required and no default provided.

FARESYSTEM |I| Optional. Line’s fare-system number.

Overrides value provided by FACTORS
FARESYSTEM control statement, and
applies for all user classes. The value
specified with the FACTORS control
statement may vary by user class.
The FARESYSTEM control statement
defines fare systems (see
“FARESYSTEM” on page 803), which
form part of a FILEI FAREI file. Fare
systems entered with this keyword must
be defined in a FILEI FAREI file.
Valid values range from 1 to 1999.

FMCAPACITY |R| Optional. Line’s capacity when the

program runs a crowding model and
writes the resulting line data file. The
program does not read in or store this
value when processing a FILEI LINEI file
containing this data.
Valid values range from 1 to 20,000.

HEADWAY |RV5| Interval, in minutes, between two

vehicles on a line. You can code up to
five different headways for a line.
 The program selects the headway for a
run from PARAMETERS HDWAYPERIOD,
which defaults to 1 or the value
associated with a FILEI ROUTEI file.
If coding only one headway value, you
may enter either HEADWAY=x or
HEADWAY[1]=x. If entering multiple
headways, you must enter each index
separately, such as HEADWAY[1]=10,
HEADWAY[2]=20, HEADWAY[3]=30.
You cannot enter HEADWAY=10,20,30.
Valid values range from 0 to 2000.
NOTE: HEADWAY inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

HEADWAY_R |RV5| Optional. Interval, in minutes, between

two vehicles on a line in the reverse
direction of a two-way line. You can
code up to five different headways for a
line.
The program selects the headway for a
run from PARAMETERS
HDWAYPERIOD, which defaults to 1 or
the value associated with a FILEI
ROUTEI file.
If coding only one headway value, you
may enter either HEADWAY_R=x or
HEADWAY_R[1]=x. If entering multiple
headways, you must enter each index
separately, such as
HEADWAY_R[1]=10,
HEADWAY_R[2]=20,
HEADWAY_R[3]=30. You cannot enter
HEADWAY_R=10,20,30.
Valid values range from 0 to 2000. The
default value is the value of HEADWAY
(the value in the forward direction).
NOTE: HEADWAY_R inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

LOADDISTFAC |R| Optional. Load distribution factor— the

percentage of seats occupied when
standing first occurs. At this seat-
occupancy point, passengers begin
experiencing increases in perceived
travel time due to crowding.
You may code in conjunction with the
VEHICLETYPE keyword to override the
load-distribution factor specified with the
VEHICLETYPE control statement and
provide a line-specific factor instead.
Valid values range from 0.0 to 100.0. The
default value is the value specified with
the VEHICLETYPE keyword.
LONGNAME |S| Optional. Second unique string identifier
for a transit line, in addition to NAME.
Up to 50 characters are allowed; any
additional text will be discarded by the
program.

MODE |I| Integer indicating mode of the transit line.

Valid values range from 1 to 999.

NAME |S| Unique string identifier for a transit line.

NAME must be the first keyword in a LINE
control statement. Up to 28 characters
are allowed; exceeding this will cause
an script error.

NODES |I| List of nodes that the transit line

or traverses. Use negative node numbers
to indicate nonstopping nodes. You
N
must specify at least two stop-nodes for
a line.
If two consecutive nodes do not map to
a link in the underlying Public Transport
network, the program generates a link,
calculating the link’s distance from the
node coordinates and taking the speed
from XYSPEED or XYSPD.
Separate node numbers with spaces,
commas, or dashes. Citilabs suggests
coding the NODES keyword as the line’s
last keyword. If you code the NODES
keyword multiple times for a line, the
program joins the last node of the
previous node list and the first node of
the next node list to form a link.
If you insert a subkeyword in the list of
nodes, you must enter the NODES
keyword again, following the
subkeyword value. To ease the coding
in such cases, you may use N as an
alias for NODES.
Valid values range from 1 to the
network’s highest node number.

NODES ACCESS |I| Optional. Integer indicating whether a

stop node is for access only, exit only, or
access and exit. Valid values are:
• 0 — Stop for access and exit
• 1 — Stop for access only
• 2 — Stop for exit only
Default value is 0.
The program inverts the access
restriction for the line’s reverse direction.

NODES ACCESS_C |I| Optional. Integer indicating ACCESS

value for a stop node and all
subsequent stop nodes until you specify
the next ACCESS or ACCESS_C keyword.
When using ACCESS_C, you must check
that the line’s last node allows exiting
(that is, that node’s value must be 0 or 2),
 otherwise passengers cannot ride to the
end of the line.
Valid values are 0, 1, or 2. Default value
is 0.

NODES DELAY |R| Optional. Additional time delay added to

the link time. Code between the two
nodes that compose the link.
Valid values are any number greater
than or equal to 1.
NOTE: DELAY inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

NODES DELAY_C |R| Optional. Additional time delay added to

the link time and all subsequent link
times until you specify the next DELAY_C
or DELAY keyword.
Valid values are any number greater
than or equal to 1.
NOTE: DELAY_C inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

NODES DWELL |I| Optional. Dwell time, in minutes, the line

spends at the preceding stop node.
Valid values range from 0 to 999. Default
value is 0.
NOTE: DWELL inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

NODES DWELL_C |I| Optional. Dwell time, in minutes, the line

spends at the preceding stop node and
all subsequent stop nodes until you
specify another DWELL or DWELL_C
subkeyword.
Valid values range from 0 to 999. Default
value is 0.
NOTE: DWELL_C inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

NODES FMOFF1 |R| Optional. Flow-metered number of

passengers alighting from the line at the
preceding node. This is the result from
running a crowding model, which
accounts for bottlenecks in the public
transport system when loading demand
data (see “Crowd modeling” on
page 746).
Valid values are numbers greater than
or equal to 0.
NODES FMON |R| Optional. Flow-metered number of
1 passengers boarding the line at the
preceding node. This is the result from
running a crowding model, which
accounts for bottlenecks in the public
transport network when loading demand
data (see “Crowd modeling” on
page 746).
Valid values are numbers greater than
or equal to 0.

NODES FMVOL |R| Optional. Flow-metered number of

1 passengers the loading models (with
crowding) assign to the link connecting
the preceding node and the next node.
This is the result from running a crowding
model, which accounts for bottlenecks in
the public transport network when
loading demand data (see “Crowd
modeling” on page 746).
Valid values are numbers greater than
or equal to 0.

NODES NNTIME |R| Optional. Travel time, in minutes,

between the most recent node and the
node preceding the last NNTIME
keyword.
The PARAMETERS keyword TRANTIME
sets the expression for computing base
transit travel time for links in the highway
network. The LINE keyword XYSPEED
and subkeyword XYSPD set speeds for
links not in the highway network. The
program adjusts (that is, overrides) the
computed link and delay times between
the nodes to reflect the NNTIME value.
NOTE: NNTIME inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.
Statements that set NNTIME to -1 (or to 0)
start the time counter from the last node
listed. The program does not set travel
time between nodes to zero; the
program retains the computed travel
time.
Statements that set NNTIME to a non-
zero, positive value set the travel time
between the last node listed and the
previous node where the time counter
started, and restart the time counter at
the last node listed.
The program automatically starts the
time counter at a line’s first node.
For example:
NODES=1,2,3,4, NNTIME=10
Sets the time from node 1 to node 4 to
ten minutes.
NODES=1,2,3,4, NNTIME=10,
NODES=5,6,7, NNTIME=15
 Sets the time from node 1 to node 4 to
ten minutes, and sets the time from node
4 to node 7 to fifteen minutes.
(continued)

NODES NNTIME NODES=1,2,3,4, NNTIME=-1,

NODES=5,6,7, NNTIME=5
(continued)
Sets the time from node 4 to node 7 to
five minutes.
NODES=1,2,3,4, NNTIME=-1,
NODES=5,6,7, NNTIME=5,
NODES=8,9, NNTIME=10
Sets the time from node 4 to node 7 to
five minutes, and the time from node 7 to
node 9 to ten minutes.
NODES=1,2,3,4, NNTIME=10,
NNTIME=-1, NODES=5,6,7,
NNTIME=6
Sets the time from node 1 to node 4 to
ten minutes, and the time from node 4 to
node 7 to six minutes. In this case, the
NNTIME=-1 is unnecessary.
NOTE: Do not use NNTIME for two-way
lines; doing so produces an error.

NODES OFF1 |R| Optional. Number of passengers

alighting from the line at the preceding
node. This is the result of a loading
operation performed by the load
models.
Valid values are numbers greater than
or equal to 0.

NODES ON1 |R| Optional. Number of passengers

boarding the line at the preceding node.
This is the result of a loading operation
performed by the load models.
Valid values are numbers greater than
or equal to 0.

NODES RT |R| Optional. Intermediate run time from the

line’s first node to the most recently
coded node.
The program adjusts the accumulated
time to the most recent node to match
the specified value, and adjusts
accumulated times to downstream
nodes.
If you code more than one RT
subkeyword, the program makes
subsequent adjustments from the node
of prior adjustment.
Do not code RT at the first node; the
program implicitly sets to zero. If coding
multiple RT subkeywords, the values
must increase.
RT and keyword RUNTIME are mutually
exclusive.
Valid values are numbers greater than
or equal to 1.
NOTE: RT inputs support two decimal
 places. More may be specified, but only
two will be saved in the output lines file.
Please see “Considerations on numeric
formats” on page 850.

NODES SPEED |R| Optional. Speed for all current link and
subsequent links in the line, until the next
SPEED or TF subkeyword.
SPEED overrides the TIMEFAC keyword
value. The program uses TIMEFAC for
links the line traverses until encountering
SPEED or TF, and then uses that value.
Valid values are numbers greater than
or equal to 1.

NODES TF |R| Optional. Time factor applied to the

current link and subsequent links until
encountering another TF subkeyword or
SPEED subkeyword. Overrides the value
specified in TIMEFAC, and any previous
TF or SPEED subkeywords.
Valid values are numbers greater than
or equal to 1.
NOTE: TF inputs support two decimal
places. More may be specified, but only
two will be saved in the output lines file.
Please see “Considerations on numeric
formats” on page 850.

NODES TIME |R| Optional. Time to traverse the link that

connects that last node specified with
the next node specified. Replaces link
time computed using coordinates and
XYSPD or XYSPEED.
For example:
N=100,101,102, TIME=5, N=103
Sets the time for link 102-103 to five
minutes. The link time is subject to
adjustment by NNTIME, RT, or RUNTIME.
Valid values are numbers greater than
or equal to 1.
NOTE: TIME inputs support two decimal
places. More may be specified, but only
two will be saved in the output lines file.
Please see “Considerations on numeric
formats” on page 850.

NODES VOL1 |R| Optional. Number of passengers the

loading models assign to the link from
the preceding node to the next node.
Valid values are numbers greater than
or equal to 0.

NODES XYSPD |R| Optional. Sets the line’s speed for the
current link and any subsequent links not
in the input network until encountering the
next XYSPD subkeyword. Overrides the
value of XYSPEED.
Do not code XYSPD for two-way lines.
Doing so produces an error.
Valid values are numbers greater than
 or equal to 1.
NOTE: XYSPD inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

ONEWAY |?| Optional. Flag indicating whether line is

one way. Possible values:
• T — Coded line is a one-way line.
• F — Coded line is a two-way line.
The reverse direction is treated as
a separate line for processing.
Default value is T.

OPERATOR |I| Optional. Integer indicating operator of

the transit line. You can define public
transit operators with the OPERATOR
control statement.
Valid values range from 1 to 999.

RUNINTERVAL |Rc| Defined headway between departures

from starting node when an interval is
specified in STARTTIMES. Specified in
minutes; use is only necessary when
start times have ranges.
NOTE: RUNINTERVAL inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

RUNTIME |R| Optional. Line’s scheduled time, in

minutes, from the first node to the last
node.
When you specify RUNTIME, the
program adjusts the time on all of the
line’s links so that the time sums to this
value. The program only scales the
link’s travel time and DELAY and
DELAY_C components. The program
retains the original values of dwell times
and intersection delays.
If you set PARAMETERS
EXTENDRUNTIMES to true and the total
time calculated from link times, delays,
dwell times, and intersection delays
exceeds the specified value, then the
program increases the value of
RUNTIME to this total.
Valid values range from 1 to 30,000
minutes.
NOTE: RUNTIME inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

SEATCAP |I| Optional. Seating capacity of vehicles

operating on this line.
You may code in conjunction with the
 VEHICLETYPE keyword. Use the
VEHICLETYPE keyword to override the
seating capacity value with a line-
specific capacity.
Valid values range from 1 to 10,000.
Defaults to value specified with
VEHICLETYPE.

SHORTNAME |S| Optional. An abbreviated name for the

line. Up to 50 characters are allowed;
any additional text will be discarded by
the program.
USERA5 maps to this keyword and
cannot be used at the same time.

STARTTIMES |RPa| A list of departure times of runs from the

first/starting node. Values are in hhmm
format, and ranges of values (e.g. 0700-
0900) may be specified. Ranges are
"expanded" into discrete runs using the
interval value immediately preceding
the start times.

TIMEFAC |R| Optional. Time factor applied to the

travel time of all links the line traverses.
The program applies this factor until
encountering a NODES TF keyword or
NODES SPEED keyword.
Valid values are numbers greater than
or equal to 1.
NOTE: TIMEFAC inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

USERA1 |S| Optional. User-defined string. Up to 50

characters are allowed; any additional
text will be discarded by the program.

USERA2 |S| Optional. User-defined string. Up to 50

characters are allowed; any additional
text will be discarded by the program.

USERA3 |S| Optional. User-defined string. Up to 50

characters are allowed; any additional
text will be discarded by the program.

USERA4 |S| Optional. User-defined string. Up to 50

characters are allowed; any additional
text will be discarded by the program.

USERA5 |S| Optional. User-defined string. Up to 50

characters are allowed; any additional
text will be discarded by the program.
Same as SHORTNAME.

USERN1 |R| Optional. User-defined number. This

attribute is displayed as WAITCURVE in
the network editing window.

USERN2 |R| Optional. User-defined number.

USERN3 |R| Optional. User-defined number.

 USERN4 |R| Optional. User-defined number.

USERN5 |R| Optional. User-defined number.

VEHICLETYPE |I| Optional. Integer indicating vehicle type

operating on this transit line.
When including crowd modeling, you
can code the vehicle type or its
attributes in the LINE statement. If you
code both the vehicle type and the
attributes of the vehicle type, the
program obtains default information from
the vehicle type and overrides that
information with attribute data.
Valid values range from 1 to 255.

XYSPEED |R| Optional. Speed on qualified links in this

transit line. Qualified links do not exist in
the input network, and both nodes in the
link have valid coordinates, enabling
distance computation.
Valid values range from 1 to 300.
NOTE: XYSPEED inputs support two
decimal places. More may be specified,
but only two will be saved in the output
lines file. Please see “Considerations on
numeric formats” on page 850.

1 The Public Transport program saves the results of a loading operation to this NODES subkeyword.
Public Transport Program > Control statements > LINE > Example > Example

Exam ple
LINE NAME="GMB1-24M", MODE=7, OPERATOR=11, ONEWAY=T, CIRCULAR=F, HEADWAY=12,
N=778, -777, 776, 773, 774, 765, 3674, 764, -763, 759, 760, -3673, -756, 752
Public Transport Program > Control statements > LINE > Calculation of line/link times

Calculation of line/link times

You can adjust the time to lines use to traverse links with several LINE keywords and
NODES subkeywords. The program uses a two-part approach to process the keywords
and obtain a line’s final link times:
1. Establish the base time for each link:
m
If the link exists in the network:
• Set link time to the link variable defined by PARAMETERS TRANTIME.
• Adjust link time using the prevailing value of T IME FA C , S P E E D , or T F .
m
If the link does not exist in network, but both nodes have coordinates and either
XY S P E E D or XY S P D is coded:

• Set link time to the computed X-Y distance divided by either XYSPEED or XYSPD, as
appropriate.
• Set link time to T IME if specified.
• Add D E LA Y or D E LA Y _C to link time, if specified.
• Add turn penalties to the approach link of the modelled intersection.

2. Adjust link times based on applicable keywords:

m
NODES N N T IME
m
NODES R T
m
R U N T IME

The program applies scaling to link travel time, DELAY and DELAY_C values. The program
does not scale dwell times and junction delays, but retains their original settings.
If you set PARAMETERS EXTENDRUNTIMES to true and the total time calculated from link
times, delays, dwell times, and intersection delays exceeds the specified value, then the
program increases the NNTIME, RT, or RUNTIME value to this total.
Public Transport Program > Control statements > LINKLOOP ... ENDLINKLOOP

LINKLOOP ... ENDLINKLOOP

Controls a loop for processing link records.
By default, the LINKLOOP statement processes all link records with a loop increment of
one. You can use LINKNO, the default loop index, to reference the current link number.
The program supplies all link arrays in a LINKLOOP block with the number-of-links
dimension.
You can only use LINKLOOP in the DATAPREP phase.

NOTE: You can nest LINKLOOP blocks within other blocks such as IF or LOOP, but not
another LINKLOOP.
Public Transport Program > Control statements > LINKLOOP ... ENDLINKLOOP > Example

Exam ple

Double LW.VAR for even number zones

IF (I%2==0)
LINKLOOP
LW.VAR=LW.VAR*2 ; no [LINKNO] subscript needed
ENDLINKLOOP
ENDIF
Public Transport Program > Control statements > LOOP ... ENDLOOP

LOOP ... ENDLOOP

Initializes a variable, compares the variable to a constant, and branches to the statement
following the LOOP block if the comparison fails.
LOOP blocks may be nested, but they may not overlap other LOOP blocks or IF blocks.
LOOP Var = Begin, End, Incr
Statement set
ENDLOOP

where:
• Var is the required user-specified name of the loop-control variable. The program does not
protect the value of Var during the loop; computation, program, and other LOOP statements
may alter the value of Var.

• Begin is the constant value to which the program initializes Var. You must specify a value.

• End is the constant value that the program compares Var to when processing the ENDLOOP
statement. You must specify a value.

• Incr is the constant the program adds to Var before processing the ENDLOOP statement.
If the result of the comparison is true, the program branches back to the statement
following the LOOP statement. If it is false, control is passed to the statement following
ENDLOOP.
Processing of the ENDLOOP statement depends on the value of Incr:
• If Incr is positive, when the value of Var is less than or equal to End, the program goes to
the statement following LOOP, otherwise the program goes to the statement following
ENDLOOP.

• If Incr is negative, when the value of Var is greater than or equal to End, the program goes
to the statement following LOOP otherwise the program goes to the statement following
ENDLOOP.

The program tests the ENDLOOP condition (without incrementing the variable value) when
initializing the loop-control variable. If the test fails, the program does not perform any
statements within the LOOP block.
Public Transport Program > Control statements > LOOP ... ENDLOOP > Example 1

Exam ple 1

Executes the code within the LOOP block 10 times.

LOOP iter=1,10
.
.
ENDLOOP
Public Transport Program > Control statements > LOOP ... ENDLOOP > Example 2

Exam ple 2

A nested loop, with the innermost loop executing twice for each value of variable xyz:
10,8,6,4,2.
LOOP xyz=10,1,-2
LOOP abc=1,2
.
.
ENDLOOP
ENDLOOP
Public Transport Program > Control statements > MODE

MODE
Defines the transit and nontransit modes that the public transport system uses.
Keywords include:
• LON GN A ME

• N A ME

• N U MB E R

All nontransit legs and transit lines belong to modes and refer to them by their numeric
identifiers. The MODE statement associates descriptive names with each mode. You can
include descriptive names in reports and graphics. Although not mandatory, Citilabs
recommends that you define the modes in use with the MODE statement.
Input MODE statements in the public transport system data file, specified with SYSTEM I.
MOD E k e y wo rd s

Ke y wo rd D e s c rip tio n

LON GN A ME |S| Optional. Second unique string identifier

for a mode. Use to supplement NAME.

N A ME |S| Optional. Unique string identifier for a

mode.

N U MB E R |I| Unique numeric identifier for a mode.

NUMBER must be the first keyword on
the MODE control statement.
Valid values range from 1 to 999.
Public Transport Program > Control statements > NT

NT
Specifies the format of nontransit legs in the Public Transport network. Keywords
include:
• LE G

• A CT ION

• COS T

• D IS T

• FMV OL

• FMV OLT

• MOD E

• ON E W A Y

• SPEED

• V OL

• V OLT

• XN

Passengers use nontransit legs to:

• Access the public transport system

• Egress from the public transport system

• Transfer between lines

You can generate nontransit legs with GENERATE statements or produce them with a
process external to the Public Transport program.
The program saves nontransit legs with the public transport network when processing a
NETO statement. You can use the output for modeling, reporting, and displaying. You
can feed the saved nontransit legs back to the modeling process when inputting the
public transport network with a NETI statement.
You can also save nontransit legs in the file specified with the NTLEGO statement. You
can use this format for reviewing and editing. You can feed these saved nontransit legs
back to the modeling process with a NTLEGI statement.
N T k e y wo rd s

Ke y wo rd D e s c rip tio n

LE G |S| Nodes defining a nontransit leg. Specify the

starting node number followed by the
ending node number, separated by a
hyphen.
 Only one leg can connect any two nodes.
NOTE: LEG must be the first keyword in NT
control statements.

A CT ION |S| Optional. String that designates how the

program merges input nontransit legs with
generated nontransit legs.
The Public Transport program maintains a
single table of nontransit legs. The program
merges the legs from each GENERATE
statement, generated or input, into this
table. The table stores only one leg, the
one with the least cost, for each
combination of A-node, B-node, and
nontransit mode.
Possible values:
• A — Add the input leg, if it is shorter
than a matching one in the table, or if it
does not already exist in the table.

• D — Delete the leg from the table, if it

exists. Useful for eliminating nontransit
legs from the network.
• R — Replace an existing leg in the
table with the input one, even if it is
longer than the existing one. No
action is taken if the leg is not already
in the table.
• RS — Replace an existing leg in the
table with the input one, only if it is
shorter than the existing one. No
action is taken if leg is not already in
the table.
Default value is A.

COS T |R| Cost, in user-specified units, to traverse the

nontransit leg.
Valid values are great than or equal to 0.01.
NOTE: COST inputs support two decimal
places. More may be specified, but only
two will be considered. Please see
“Considerations on numeric formats” on
page 850.

D IS T |R| Length, in user-specified units, of the

nontransit leg.
Valid values are great than or equal to 0.01.
NOTE: DIST inputs support two decimal
places. More may be specified, but only
two will be considered. Please see
“Considerations on numeric formats” on
page 850.

FMV OL |R| Optional. Directional flow-metered

passenger volume (total number of flow-
metered passengers that the loading
models assigned to the nontransit leg). This
crowd-modeling data accounts for
constraints that bottlenecks impose in the
public transport network.
Valid values are great than or equal to 0.
FMV OLT |R| Optional. Nondirectional flow-metered
passenger volume (total number of flow-
metered passengers that the loading
models assigned to the nontransit leg in the
forward and reverse directions). This
crowd-model data accounts for constraints
that bottlenecks impose on the public
transport network. Enter the same value for
FMVOLT for leg A-B and leg B-A.
Valid values are great than or equal to 0.

MOD E |I| Mode of the nontransit leg.

Valid values range from 1 to 999.

ON E W A Y |?| Optional. Flag indicating whether nontransit

leg is a one-way leg. Possible values:
• T — Nontransit leg is a one-way leg
• F — Nontransit leg is a two-way leg
Default is T.

SPEED |R| Optional. Speed, in user-specified units per

hour, that the transit vehicle traverses the
nontransit leg.
Valid values are great than or equal to 0.01.

V OL |R| Optional. Directional passenger volume

(number of passengers that the loading
models assign to the nontransit leg).
Valid values are great than or equal to 0.

V OLT |R| Optional. Nondirectional passenger

volume (total number of passengers that
the loading models assign to the nontransit
leg in both the forward and reverse
directions). Enter the same value for VOLT
for leg A-B and leg B-A.
Valid values are great than or equal to 0.

XN |S| Optional. List of nodes between the start

and end nodes in a nontransit leg.
LEG defines the start and end nodes.
Public Transport Program > Control statements > NT > Example

Exam ple

A selection of nontransit legs generated by the Public Transport program.

NT LEG=6-800 MODE=5 COST=1.92 DIST=39.00 ONEWAY=T
NT LEG=6-2054 MODE=5 COST=5.40 DIST=53.00 ONEWAY=T XN=792
NT LEG=6-2056 MODE=5 COST=5.92 DIST=43.00 ONEWAY=T XN=800
NT LEG=7-803 MODE=5 COST=1.52 DIST=41.00 ONEWAY=T
NT LEG=7-806 MODE=5 COST=8.35 DIST=52.00 ONEWAY=T XN=2058
NT LEG=7-2058 MODE=5 COST=4.35 DIST=29.00 ONEWAY=T
NT LEG=8-814 MODE=5 COST=0.88 DIST=12.00 ONEWAY=T
NT LEG=9-812 MODE=5 COST=1.16 DIST=29.00 ONEWAY=T
Public Transport Program > Control statements > OPERATOR

OPERATOR
Defines the operators in the public transport system. Keywords include:
• LON GN A ME

• N A ME

• N U MB E R

All lines belong to operators and refer to them by their numeric identifiers. The OPERATOR
control statement associates descriptive names with operators. You can include these
names in reports and graphics. Although not mandatory, Citilabs recommends that you
define the operators in use with the OPERATOR statement.
Input OPERATOR statements in the public transport system data file, specified with
SYSTEM I.

OP E R A T OR k e y wo rd s

Ke y wo rd D e s c rip tio n

LON GN A ME |S| Optional. Unique secondary string that

identifies a transit operator. Supplements
NAME.

N A ME |S| Optional. Unique string that identifies a

transit operator.

N U MB E R |I| Unique number that identifies a transit

operator.
Must be the first keyword coded with the
OPERATOR control statement.
Valid values range from 1 to 999.
Public Transport Program > Control statements > PARAMETERS

PARAMETERS
Specifies global parameters for the Public Transport run. Keywords and sub-keywords
include:
• A ON ME T H OD

• CH A N GE A T LA S T S T OP

• E FA R E

• E XT E N D R E P OR T

• E XT E N D R U N T IME S

• FA R E

• FA R E MS G

• H D W A Y P E R IOD
m DELAY_DEFAULT
m DWELL_DEFAULT
m TIMEFAC

• MA P S CA LE

• MA XMW

• ME U S E S N T

• MOD IR E

• N OR OU T E E R R S

• N OR OU T E MS GS

• S KIP B A D LIN E S

• T R A N T IME

• T R IP S IJ

• U S E R CLA S S E S

• V 4R OU T E FOR MA T

• ZON E MS G

P A R A ME T E R S k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

A ON ME T H OD |IK| Optional. Integer specifying all-or-

nothing path-building algorithm to use.
Possible values:
• 0 — Use latest available algorithm
• 3 — Use algorithm from version 3.2
• 4 — Use algorithm from version 4.0
Default value is 0.
CH A N GE A T LA S T S T OP |?K| Optional. Flag that indicates how
transfers between routes occur. Possible
values:
• T — Method from version 3.2 and
earlier releases: When two routes
share a common sequence of
stopping nodes, transfers occur at
the last stopping node in the
sequence.
Citilabs recommends this setting
only when required for consistency
with earlier runs.
• F — When two routes share a
common sequence of stopping
nodes, transfers may occur at any
of the nodes.
Default value is F.

E FA R E |?K| Optional. Flag indicating whether to input

descriptions of fare systems.
If ENUMFARE=T and no fare skimming
and route evaluation required, EFARE
must be set to True to allow fares to be
considered during the
BESTPATHONLY route enumeration
process.
Default value is False. This keyword will
be ignored if FARE=T, or Fare skim
functions (FAREA/FAREP) and route
evaluation are required.
Example 4 — Example of EFARE
parameter.

E XT E N D R E P OR T |?| Optional. Flag that specifies whether to

print messages for excessive calculated
travel times. Possible values:
• T — Program prints messages
when a line’s calculated travel time
exceeds the values specified by
RUNTIME, NODES NNTIME, or
NODES RT.

• F — Program does not print

messages for excessive
calculated travel times.
Default value is F.
The program determines run times
along transit lines from junction delays
and link travel time, using data in
keywords such as TRANTIME, DELAY,
DELAY_C, DWELL, DWELL_C.
When calculated travel times exceed the
travel time limits imposed by the
RUNTIME, NNTIME, or RT keywords and
subkeywords in the LINE control
statement, you might edit the LINE
statement or extend the line’s run time
with the EXTENDRUNTIMES keyword.

E XT E N D R U N T IME S |?| Optional. Flag that indicates whether the

program automatically extends travel
 time along a line when it exceeds control
values. Possible values:
• T — When calculated travel times
along a line exceed control values,
the program increases the control
values and travel times to reflect
the prevailing network conditions
• F — When calculated travel times
along a line exceed control values,
the program scales calculated
values to match control values.
Default value is F.
The program calculates run times along
transit lines from junction delays and link
travel time, using data in keywords such
as TRANTIME, DELAY, DELAY_C,
DWELL, DWELL_C.
The LINE control statement and its
RUNTIME, NNTIME, or RT keywords and
subkeywords set control values for
travel time.
Only set EXTENDRUNTIMES to T when
reading LINEI files. If the program reads
line data from a network file, then link
travel times have already been
calculated and cannot be amended.

FA R E |?K| Optional. Flag indicating whether fares

are included in generalized cost during
the route-evaluation process. Possible
values:
• T — Program includes fares as part
of the generalized cost during the
route-evaluation process. Input
descriptions of fare systems with
FILEI FAREI. If required, input
descriptions of fare matrices with
FILEI FAREMATI.

• F — Program does not include

fares as part of the generalized
cost during the route-evaluation
process.
Default value is F.
FARE does not impact the selection of
fare skims chosen with the skimming
functions FAREA and FAREP.
Fare data is required only for the route-
evaluation and skimming processes.
The program only validates fare data if
you select one of these processes. You
do not need to provide fare data for the
DATAPREP phase.

FA R E MS G |IK| Optional. Integer indicating how the

program treats message 770. Possible
values:
• 0 — Treat as message
• 1 — Treat as warning
 • 2 — Treat as error
Default value is 2.
Message 770 describes missing or
inconsistent data in the FILEI FAREI. The
program only validates this data if fares
are included in the route-evaluation or
skimming processes.

H D W A Y P E R IOD |IK| Optional. Integer indicating which

HEADWAY and HEADWAY_R fields to
use from the LINE control statement, if
more than one such field is coded.
You can code up to five headways for
each line. If you do not specify
HDWAYPERIOD, the default is 1
(HEADWAY[1]).
Valid values range from 1 to 5.

H D W A Y P E R IOD D E LA Y _D E FA U LT |RV5| Optional. Additional time delay added to

all link times for the line until one
specifies a DELAY_C or DELAY sub-
keyword. DELAY_C and DELAY work as
they normally do. When the DELAY
terminates the DELAY_C, the value for
DELAY_ALL is then used for all
subsequent links down the line.
The program selects the line specific
delay to be consistent with the
PARAMETERS HDWAYPERIOD. If
coding only one line specific dwell
value, you may enter either
DELAY_DEFAULT=x or
DELAY_DEFAULT [1]=x. If entering
multiple line specific dwells, you must
enter each index separately, such as
DELAY_DEFAULT [1]=1,
DELAY_DEFAULT [2]=2
DELAY_DEFAULT [3]=3. You cannot
enter DEWELL_DEFAULT =1,2,3.
Valid values range from 0 to 999. Default
value is 0.
See Example of DELAY_DEFAULT
keyword.
NOTE: DELAY_DEFAULT inputs support
two decimal places. More may be
specified, but only two will be
considered. Please see “Considerations
on numeric formats” on page 850.

H D W A Y P E R IOD D W E LL_D E FA U LT |RV5| Optional. Dwell time, in minutes, the line

spends at all stop nodes for the line until
one specifies a DWELL_C or DWELL
sub-keyword. DWELL_C and DWELL
work as they normally do. When the
DWELL terminates the DWELL_C, the
value for DWELL_ALL is then used for all
subsequent stop nodes down the line.
The program selects the line specific
dwell to be consistent with the
PARAMETERS HDWAYPERIOD. If
coding only one line specific dwell
value, you may enter either
 DWELL_DEFAULT=x or
DWELL_DEFAULT[1]=x. If entering
multiple line specific dwells, you must
enter each index separately, such as
DWELL_DEFAULT[1]=1,
DWELL_DEFAULT [2]=2,
DWELL_DEFAULT [3]=3. You cannot
enter DWELL_DEFAULT =1,2,3.
Valid values range from 0 to 999. Default
value is 0.
NOTE: DWELL_DEFAULT inputs support
two decimal places. More may be
specified, but only two will be
considered. Please see “Considerations
on numeric formats” on page 850.
See Example of DWELL_DEFAULT
keyword.

H D W A Y P E R IOD T IME FA C |RV5| Optional. Time factor applied to the

travel time of all links the line traverses.
The program applies this factor until
encountering a NODES TF keyword or
NODES SPEED keyword.
The program selects the line specific
time factor to be consistent with the
PARAMETERS HDWAYPERIOD. If coding
only one line specific TIMEFAC value,
you may enter either TIMEFAC=x or
TIMEFAC [1]=x. If entering multiple line
specific dwells, you must enter each
index separately, such as TIMEFAC
[1]=1, TIMEFAC [2]=2 TIMEFAC [3]=3.
You cannot enter TIMEFAC =1,2,3.
Valid values are numbers greater than
or equal to 1.
See Example of TIMEFAC keyword.
NOTE: TIMEFAC inputs support two
decimal places. More may be specified,
but only two will be considered. Please
see “Considerations on numeric formats”
on page 850.

MA P S CA LE |RK| Optional. Factor indicating coordinate

units divided by distance unites
The program uses this value in
conjunction with LINE XYSPEED. If not
specified, the program estimates a
value from the link data.

MA XMW |IK| Optional. Maximum index for work

matrices (MWs). Valid values range from
1 to 999. Default value is 999. Normally,
you do not specify this keyword and
override default value.

ME U S E S N T |?| Optional. Flag indicating whether

program considers link use of nontransit
modes. Possible values:
• Y — Program considers link use of
all modes when creating intercept
data.
• N — Program considers only link
 use of transit modes when creating
intercept data.
You can override this default setting with
keywords in the FILEO SCREENLINEO
statement.
Default value is Y.

MOD IR E |?K| Optional. Flag indicating that Public

Transport will use a modified route
enumeration process. Set this to True to
enhance the stability of the enumerated
route sets and skims under small
variations of network characteristics
(such as link travel time).
• T — Public Transport will use
modified route enumeration
process.
• F — Default route enumeration
process
Default value is F.

N OR OU T E E R R S |IK| Optional. Number of zone pairs that the

program can process with trips between
them but no valid routes.
When the number of zone pairs with trips
but without valid routes exceeds this
value, the program terminates.
Generally, all zones in a public transport
network are connected. This keyword
permits you to accommodate
unconnected zones, if necessary.
NOROUTEERRS applies to all user
classes.
Valid values are greater than or equal to
0. Default value is 10.

N OR OU T E MS GS |IK| Optional. Number of messages the

program reports for loaded zone pairs
that have trips between them but no valid
routes.
The program terminates when the
number of such zone pairs exceeds
NOROUTEERRS.
NOROUTEMSGS applies across all user
classes.
Valid values are greater than or equal to
0. Default value is 5.

S KIP B A D LIN E S |?| Optional. Flag indicating whether to treat

data errors when reading transit line data
as warning. Possible values:
• Y — Downgrade data errors to
warnings when reading transit line
data.
This setting allows the program to
read an entire input file without
termination due to data errors.
• N — Treat data errors as errors,
leading to program termination.
Default value is N.
 You may override this global setting with
the FILEI LINEI control statement.

T R A N T IME |NKVt|1 Expression specifying how to compute

base transit time for links that transit lines
traverse. May vary per mode.
You can refine this time with the LINE
control statement and the NODES
keyword.
You might specify:
• Name of an input-network link-
based variable that contains link
transit times. Denote input-network
link variables as LI.name.

• Name of a link work array that you

computed in the LINKREAD
phase. Denote these arrays as
LW.name.

• Expression involving one or more

link variables. Include only input-
network link variables (LI.name) or
link work arrays (LW.name). You
must enclose expressions in
parentheses.
NOTE: If you set TRANTIME to any other
variables, the results are unpredictable.
Examples:
TRANTIME = LI.name
TRANTIME = LW.TRANTIME;
LW.TRANTIME was computed in
the LINKREAD phase.
TRANTIME =
(LI.DISTANCE*60/LI.SPEED)
The settings in these examples apply to
all modes. You can override these
settings with a mode-specific
expressions. For example, if mode 3
uses a different formula, you might
define:
TRANTIME[3] =
(1.14*LI.DISTANCE*60/LI.SPEED)

T R IP S IJ |NVu|2 Optional. Numeric expression used to

compute trips loaded for a particular
user class. You might assign an input or
generated trip matrix.
You must provide a value for all user
classes, unless using the SELECTIJ
phase. The index is defined by
USERCLASSES. If USERCLASSES=1, you
need not code the index.
TRIPSIJ applies to all I-J pairs; the
program can compute trips for individual
or sets of I-J pairs in the SELECTIJ
phase.
Examples
FILEI MATI[1]=TRIPS.MAT
PARAMETERS TRIPSIJ[1] = MI.1.1
Loads the cells of an input trip matrix.
 FILEI MATI[1]=TRIPS.MAT
PARAMETERS TRIPSIJ[1] = MI.1.1
* 0.7, TRIPSIJ[2] = MI.1.1 *
0.3
Loads 70% of the input trip matrix to user
class 1 and 30% to user class 2.

U S E R CLA S S E S |IK| Optional. List of modeled user classes.

Specify the list as a set of single
numbers or dash-separated pairs of
numbers that give a range. Delimit each
number or pair with a comma.
User classes need not be monotonic or
sequential. For example:
USERCLASSES=1,3-5,7
Valid user classes range from 1 to 10. By
default, all ten user classes are
available in the Public Transport
network.
For more information, see “More on user
classes” on page 906.

V 4R OU T E FOR MA T |?K| Optional. Flag indicating formatting of

route file. Possible values:
• T — Program writes older, version
4-compatible route file format with
FILEO R OU T E O.

• F — Program writes current route

file format
Default value is F.

ZON E MS G |IK| Optional. Frequency with which the

program writes zonal timing messages
to the run monitor or console.
Value corresponds to number of zones.
For example, with a value of 1, the
program writes a message for every
zone. With a value of 10, the program
writes a message for every 10 zones.
With a value of 0, the program writes no
zonal messages. Specify a larger value
to reduce run times.
Program writes to the run monitor when
initiated through Application Manager or
voyager.exe. The program writes to the
console when initiated through
runtpp.exe.
Valid values are greater than or equal to
zero. Default value is 1.

1 t represents number of transit modes

2 u represent number of user classes

Public Transport Program > Control statements > PARAMETERS > Example > Example

Exam ple

Parameters for the data-preparation, route-evaluation, and loading processes. Note

most PARAMETERS keywords, other than TRIPSIJ, are trigger keywords and need not be
preceded by the control statement name.
PARAMETERS USERCLASSES=1,2
PARAMETERS TRIPSIJ[1] =MI.1.1
PARAMETERS TRIPSIJ[2] =MI.1.2
NOPATHMSGS=10
NOPATHERRS=25
Public Transport Program > Control statements > PARAMETERS > Example > Example of EFARE parameter

Exam ple o f EFARE param eter

See Example 4 — Example of EFARE parameter under BESTPATHONLY.

Public Transport Program > Control statements > PARAMETERS > Example > Example of DWELL_DEFAULT keyword

Exam ple o f DW ELL_DEFAULT keywo rd

The DWELL_DEFAULT keyword is applied to all the stops except the first stop station
because the first stop station would be served on the scheduled operating time. If the
nodes are indicated as the non-stop with a negative sign in node number (or
STOPA=0), the dwell time would not be added into the nodes. As an example, the
'Comparison of run times in link level' shows the addition of 2 min for peak period only in
each transit stop station (e.g. STOPA=1).
< Transit line coding: 2 min for peak and 1 min for off-peak >
LINENAME="B6 EB", LONGNAME="Stockton-Wilson EB", HEADWAY[1]=60,
HEADWAY[2]=60, MODE=21, ONEWAY=T, OPERATOR=1,
CIRCULAR=F, DWELL_DEFAULT[1]=2, DWELL_DEFAULT[2]=1,
USERA3="Line 026", USERA2="B6", USERA1="LOCAL",
N=11964, -11967, -11960, -11965, -11962, -11966,
-11963, -11969, DELAY=5, N=11961, -11968, -11972,
-11959, -11958, -11956,
Public Transport Program > Control statements > PARAMETERS > Example > Example of DELAY_DEFAULT keyword

Exam ple o f DELAY_DEFAULT keywo rd

The DELAY_DEFAULT keyword is applied to all the links except the link specified with either
DW ELL or DW ELL_C sub-keyword. It simply adds the delay time into each link. As an
example, the 'Comparison of run times in link level' shows the addition of 1 min for peak
period for every link except the link 11969-11961 with 'DELAY=5'.
< Transit line coding: 1 min for peak and 0.5 min for off-peak >
LINENAME="B6 EB", LONGNAME="Stockton-Wilson EB",
HEADWAY[1]=60,HEADWAY[2]=60, MODE=21, ONEWAY=T,
OPERATOR=1, CIRCULAR=F,DELAY_DEFAULT[1]=1,
DELAY_DEFAULT[2]=0.5,USERA3="Line 026", USERA2="B6",
USERA1="LOCAL", N=11964, -11967, -11960, -11965,
-11962, -11966, -11963, -11969, DELAY=5, N=11961,
-11968, -11972, -11959, -11958, -11956,
Public Transport Program > Control statements > PARAMETERS > Example > Example of TIMEFAC keyword

Exam ple o f TIM EFAC keywo rd

The TIMEFAC keyword is applied to all the links except the links specified with either
NODES TF or NODES SPEED sub-keyword. It simply multiplies the runtime by the
input factor value into in each link. As an example, the 'Comparison of run times in link
level' shows the increase of link runtime by approximately twice for every link for peak
period because 'TIMEFAC[1]' is 2.0. Note that the time proportions in the summary table
are not exactly same as 2.0 for peak period due to the rounding issue in the dBase
format.
< Transit line coding: 2.0 min for peak and 1.5 min for off-peak >
LINENAME="B6 EB", LONGNAME="Stockton-Wilson EB",
HEADWAY[1]=60, HEADWAY[2]=60, MODE=21, ONEWAY=T,
OPERATOR=1, CIRCULAR=F, TIMEFAC[1]=2.0,
TIMEFAC[2]=1.5, USERA3="Line 026", USERA2="B6",
USERA1="LOCAL", N=11964, -11967, -11960, -11965,
-11962, -11966, -11963, -11969, DELAY=5, N=11961,
-11968, -11972, -11959, -11958, -11956,
Public Transport Program > Control statements > PARAMETERS > More on user classes

More on user classes

You can use user classes for multiple purposes. For example, you can use user classes
to stratify demand, such as by purpose or fare type. Similarly, each user class might
have different behavior patterns, which you model with user-class-specific cost
functions.
The Public Transport network contains several components that are common to all user
classes:
• Basic network infrastructure (such as zones, nodes/stops, and links) produced by the
Network program

• System data input with S Y S T E MI

• Demand data, input with MA T I

• Nontransit legs, generated with the GENERATE control statement, input with N T LE GI, or both

• Line data, input with LIN E I

Other data and processes vary by user class:

• Factor data, input with FA CT OR I, specifies cost functions that can vary by user class.

• Skim data, output with MA T O , specifies level-of-service data that can vary by user class.

• Routes are enumerated and evaluated by user class. Routes are input with R OU T E I, and
output with ROUTEO.

You must specify FACTORI and MATI files by user class. However, if there are no
differences between the behavior for some user classes, you can point those user
classes to the same FACTORI file.
For example, suppose you want to define input files for user classes 1, 3, and 4. User
class 3 and 4 use the same factors. You might create the following control statements:
FILEI FACTORI[1]= FACTSUC1.FAC, FACTORI[3]=FACTSUC3.FAC, FACTORI[4]=FACTSUC3.FAC
FILEI ROUTEI[1]=ENROUTEUC1.RTE, ROUTEI[3]=ENROUTEUC3.RTE, ROUTEI[4]=ENROUTEUC4.RTE

The Public Transport program outputs a public transport network that contains the four
components that are common to all user classes (network infrastructure, system data,
nontransit legs, and line data) and that contains the factors for all user classes.
The program outputs user-class-specific enumerated routes files (ROUTEO), matrices
(M ATO ), and skims and select link analyses.
You define input and output files for user classes with the FILEI and FILEO control
statements.
Public Transport Program > Control statements > PRINT

PRINT
Specifies the format for data items output in a single line to the standard printed output, a
file, or both.
The program prints one line for each PRINT statement. The length of the printed line is
determined by the formatting of each listed item.
See “PRINT” on page 69 for details about the standard Cube Voyager control
statement.
Public Transport Program > Control statements > PRINTROW

PRINTROW
Specifies format for reporting work matrices to the main print file.
See “PRINTROW” on page 77 for details about the standard Cube Voyager control
statement.
Public Transport Program > Control statements > PRINTROW > Example

Exam ple

Print two skim matrices, ten columns per line.

PRINTROW MW=2 FORM 10.2 TITLE='COMPCOST'
PRINTROW MW=2 FORM 10.2 TITLE='TIMEA''
Public Transport Program > Control statements > PTRUN

PTRUN
The PTRUN control is used within LINEI files for providing detailed timetable information
for each RUN Read from LINEI (based on the LINE control). Keywords and sub-
keywords include:
• DAYT YPE

• N OD E S
m AT
m ARR
m DEP

• OFLIN E
PTRUN keywo rds

Ke y wo rd S ub k e y wo rd D e s c rip tio n

DAYT YPE |IPa*| Specifies what day types the run

operates on. Reads a list of single
values and/or ranges. No default
values, so list is required.

N OD E S |IPD| Defines a timing point where timing

data is read as sub-keywords.

N OD E S AT |RPD*| Specifies the time when the service

calls at the stop (hhmm)

N OD E S ARR |RPD*| Specifies the arrival time when the

services wait at the stop (hhmm)

N OD E S DEP |RPD*| Specifies the departure times of

services waiting at the stop (hhmm)

OFLIN E |Sc| Specifies which line this service is a

run of.
Public Transport Program > Control statements > REPORT

REPORT
Generates reports. Keywords and sub-keywords include:
• LIN E S
m DEC
m SKIP0
m SORT

• LIN E V OLS
m DEC
m SKIP0
m STOPSONLY
m USERCLASSES

Two reports are generated:

• Summary of line attributes including passenger distance and hours

• Passenger loadings on lines

The program generates a third report, which shows passenger transfers between modes
and operators, when running the loading process.
R E P OR T k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

LIN E S |?| Optional. Flag indicating

whether to generate summary
report of line attributes, showing
attributes like number of stops,
route time, and distance.
Possible values:
• T — Produce summary
report of line attributes.
Summary includes
passenger distance and
hours if line loads are
available.
• F — Do not produce
summary report.
Default value is F.
More than one LINES report
may be selected in a run.
See “Transit line summary” on
page 932 for an example of this
report.

LIN E S DEC |I| Optional. Number of decimal

places to include in the “Pass”
 and “PassDist” columns in the
summary report produced by
LINES.
Valid values range from 0 to 5.
Default is 2.

LIN E S S KIP 0 |?| Optional. Flag indicating

whether to omit lines without
loads in the summary report
produced by LINES. Possible
values:
• T — Omit lines without
loads
• F — Include lines without
loads
Default value is F.

LIN E S S OR T |S| Optional. String specifying field

that the summary report uses to
sort lines. Possible values:
• NAME
• MODE
• OPERATOR
By default, report does not sort
lines, but displays in order of
input.

LIN E V OLS |?| Optional. Flag indicating

whether to report passenger
loadings (boardings, alightings,
and flows) by line. Possible
values:
• T — Report passenger
loadings by line. By
default, program
generates single report
summed over all user
classes. You can produce
reports for individual user
classes with subkeyword
USERCLASSES.

• F — Do not report
passenger loadings.
Default value is F.
See “Transit line loadings” on
page 933 for an example of this
report.

LIN E V OLS DEC |I| Optional. Number of decimal

places in passenger loading
fields.
Valid values range from 0 to 5.
Default is 2.

LIN E V OLS S KIP 0 |?| Optional. Flag indicating

whether to include only stop
nodes with flows. Possible
values:
• T — Produce passenger
 loadings report only for
stop nodes with nonzero
flows; ignore nonstopping
nodes and nodes that
have no passenger
activity.
• F — Include all nodes in
report.
Default value is F.

LIN E V OLS S T OP S ON LY |?| Optional. Flag indicating

whether to include stop nodes
only. Possible values:
• T — Produce passenger
loadings report for stop
nodes only; do not include
nonstopping nodes.
• F — Include all nodes in
report.
Default value is F.

LIN E V OLS U S E R CLA S S E S |IV10| Optional. List of user classes

that require individual
passenger loadings reports.
Specify the list as a set of single
numbers or dash-separated
pairs of numbers that give a
range. Delimit each number or
pair with a comma.
Valid values range from 1 to 10.
You may specify up to ten user
classes. By default, none are
included, and the program
produces a single report,
summed over all user classes.
Public Transport Program > Control statements > REREPORT

REREPORT
Produces reports showing the input simplified public transport network and allied data
structures that the route enumeration process uses.
Keywords include:
• A CCE S S LE GS

• E GR E S S LE GS

• LIN E

• LIN E S

• LIN E LIN E LE G

• LIN E ZON LE G1

• LIN E ZON LE G2

• N

• S T OP N OD E S

• T LE GS

• T R N LE GS 1

• T R N LE GS 2

• T R N LE GS 3

• T R N LE GS 4

• T T DEPS

• T T LE GS

• U S E R CLA S S

• XFE R LE GS

These basic reports help you understand the network-simplification and route-
enumeration processes. For examples, see “Network simplification” on page 947.
A run can have multiple REREPORT statements. A statement’s selections apply to the
reports generated by that statement. The statement outputs reports to the file specified
with REPORTO .
None of the REREPORT keywords are “trigger” keys; you must code all on a REREPORT
statement.
R E R E P OR T k e y wo rd s

Ke y wo rd D e s c rip tio n

A CCE S S LE GS |?| Optional. Flag indicating whether to produce

an access-leg report. Possible choices:
• T — Produce a report showing access
legs in the public transport network.
 Access legs connect zones to
serviced boarding nodes. GENERATE
control statements generate or input
access legs.
Specify included nodes with N.
• F — Do not produce this report.
Default value is F.

E GR E S S LE GS |?| Optional. Flag indicating whether to produce

an egress-leg report. Possible values:
• T — Produce a report showing egress
legs in the public transport network.
Egress legs connect zones to serviced
alighting nodes. GENERATE control
statements produce or input egress
legs.
Specify included nodes with N.
• F — Do not produce this report.
Default value is F.

LIN E |S| Optional. List of lines included in the reports

produced by LINES, TRNLEGS3, and
TRNLEGS4. The list can contain up to 1000
comma-separated items.
You can mask names with “*” and “?” to
specify multiple lines. The program
compares nonmasked portions of a line’s
name when selecting lines. “*” applies to any
number of characters, while “?” applies to
single characters.
For example, LINE=MUNI* selects all lines
that have names beginning with “MUNI,” such
as MUNICENTRAL and MUNINORTH, while
LINE=MUNI-?? selects lines that have
names beginning with MUNI- and any two
additional characters, such as MUNI-01 and
MUNI-02.
Default value is all lines.

LIN E S |?| Optional. Flag indicating whether to produce

a line-attribute report. Possible values:
• T — Produce a report showing transit-
line attributes and the nodes the lines
traverse.
Specify included lines with LINE.
• F — Do not produce this report.
Default value is F.

LIN E LIN E LE G |?| Optional. Flag indicating whether to produce

a line-to-line transfer-leg report. Possible
values:
• T — Produce a report showing the line-
to-line transfer legs, in line order. This
report expands upon the direct-and-
nontransit-transfer-leg report, produced
with XFERLEGS.
You might use this report to improve
performance of the route-enumeration
 process. GENERATE control statements
generate or input nontransit transfer legs.
• F — Do not produce this report.
Default value is F.

LIN E ZON LE G1 |?| Optional. Flag indicating whether to produce

a line-ordered line-to-zone nontransit-leg
report. Possible values:
• T — Produce a report showing line-to-
zone nontransit legs, in line order.
This report expands on the access-leg
and egress-leg reports produced with
ACCESSLEGS and EGRESSLEGS. You
might use this report to improve
performance of the route-enumeration
process.
• F — Do not produce this report.
Default value is F.

LIN E ZON LE G2 |?| Optional. Flag indicating whether to produce

a zone-ordered line-to-zone nontransit-leg
report. Possible values:
• T — Produce a report showing line-to-
zone nontransit legs, in zone order.
This report expands on the access-leg
and egress-leg reports produced with
ACCESSLEGS and EGRESSLEGS. You
might use this report to improve
performance of the route-enumeration
process.
Specify included nodes with N.
• F — Do no produce this report.
Default value is F.

N |IV1000| Optional. List of nodes included in the reports

produced by ACCESSLEGS, EGRESSLEGS,
LINEZONLEG2, TRNLEGS1, TRNLEGS2, and
XFERLEGS.
Specify the list as a set of single numbers or
dash-separated pairs of numbers that give a
range. Delimit each number or pair with a
comma. The list can contain up to 1000
comma-separated items.
For example, if REREPORT
ACCESSLEGS=T, EGRESSLEGS=T,
N=1000-2000, 3000-4500, then the
selected reports will include nodes 1000
through 2000 and nodes 3000 through 4500.
Default is to include all nodes.

S T OP N OD E S |?| Optional. Flag indicating whether to produce

a stop-node report. Possible values:
• T — Produce a report showing all
nodes in the public transport network
where transit lines stop for transfer,
access, or egress.
• F — Do not produce this report.
Default value is F.
T LE GS |IP| Used to specify start and end of transit leg
(e.g. 123-456, 123-789 would report transit
legs from 123 to 456 then 123 to 789).

T R N LE GS 1 |?| Optional. Flag indicating whether to produce

a node-ordered transit-leg report that shows
perceived costs (including BRDPEN) during
route enumeration. Possible values:
• T — Produce a report showing all transit
legs in the public transport network,
sorted by node.
Specify included nodes with N.
This report shows actual and perceived
in-vehicle time that the route-enumeration
process uses. The report calculates
perceived in-vehicle time as:
Actual in-vehicle
time*RUNFACTOR[mode] +
BRDPEN[mode]
• F — Do not produce this report.
Default value is F.

T R N LE GS 2 |?| Optional. Flag indicating whether to produce

a node-ordered transit-leg-bundle report that
shows the perceived costs (including
BRDPEN) during route enumeration for all
legs and that identifies a bundle’s fastest line
and shows that leg’s estimated waiting time.
Possible values:
• T — Produce a report showing transit-
leg bundles in the public transport
network, sorted by node.
Specify included nodes with N.
This report shows actual and perceived
in-vehicle time that the route-enumeration
process uses. The report calculates in-
vehicle time as:
Actual in-vehicle
time*RUNFACTOR[mode] +
BRDPEN[mode]
The perceived time for the bundle’s top
leg also includes the estimated wait time
for the bundle.
• F — Do not produce this report.
Default value is F.

T R N LE GS 3 |?| Optional. Flag indicating whether to produce

a line-ordered transit-leg report that shows
perceived costs (including BRDPEN) during
route enumeration. Possible values:
• T — Produce a report showing transit
legs and attributes, sorted by line.
Specify included lines with LINE.
This report shows actual and perceived
in-vehicle time that the route-enumeration
process uses. The report calculates
perceived in-vehicle time as:
Actual in-vehicle
 time*RUNFACTOR[mode] +
BRDPEN[mode]
• F — Do not produce this report.
Default value is F.

T R N LE GS 4 |?| Optional. Flag indicating whether to produce

a line-ordered transit-leg report that shows
perceived costs used for route evaluation.
Possible values:
• T — Produce a report showing transit
legs and attributes, sorted by line.
Specify included lines with LINE.
This report shows actual and perceived
in-vehicle time that the route-evaluation
process uses. The report calculates
perceived in-vehicle time as:
Actual in-vehicle cost *
RUNFACTOR[mode]
NOTE: The report TRNLEGS3 produces
includes BRDPEN.
• F — Do not produce this report.
Default value is F.

T T DEPS |?| Set to true to obtain report of all lines/runs

departing from the specified node. Can use
sub-keyword N= to specify required nodes.

T T LE GS |?| Set to true to obtain report of all lines/runs

between a pair of nodes. Can use sub-
keyword TLEGS to specify start and end
node of transit leg.

U S E R CLA S S |IPa| Optional. List of user classes included in the

reports produced by the REREPORT
statement.
You define valid user classes with
USERCLASSES.
By default, reports produced for each
defined user class.

XFE R LE GS |?| Optional. Flag indicating whether to produce

a direct-and-nontransit-transfer-leg report.
Possible values:
• T — Produce a report showing direct
and nontransit transfer legs in the
public transport network.
Specify included nodes with N.
GENERATE control statements generate
or input nontransit transfer legs.
• F — Do not produce this report.
Default value is F.
Public Transport Program > Control statements > REREPORT > Example

Exam ple

In the REREPORT statement below, all reports are for user class 1. Node-based reports
only apply to nodes 250-450, and line-based reports apply to lines with line names
beginning with MUNI.
//The REREPORT control statement name must be coded at the beginning of the
statement
REREPORT,
ACCESSLEGS=T,
EGRESSLEGS=T,
LINES=T,
TRNLEGS1=T, TRNLEGS2=T, TRNLEGS3=T, TRNLEGS4=T,
XFERLEGS=T,
LINEZONLEG1=T, LINEZONLEG2=T,
STOPNODES=T,
N=250-450, LINE='MUNI*', USERCLASS=1
Public Transport Program > Control statements > VEHICLETYPE

VEHICLETYPE
Defines the main vehicle types used by the transit lines operating public transit services.
Keywords include:
• N U MB E R

• CR OW D CU R V E

• CR U S H CA P

• LOA D D IS T FA C

• LON GN A ME

• N A ME

• S E A T CA P

A vehicle can be any form of transport that provides public transit service over fixed
routes, such as a bus, tram, train, ferry, or hovercraft. The vehicle definitions provide a
template that you can associate with one or more transit lines. You can amend vehicle
attributes on a line-by-line basis when needed.
You may define up to 255 vehicle types. The program includes no default vehicle types.
When transit lines operate with particular vehicle types, you may specify the vehicle type
in the LINE statement.
You must input VEHICLETYPE statements in the Public Transport system data file,
specified with SYSTEM I.
V E H ICLE T Y P E k e y wo rd s

Ke y wo rd D e s c rip tio n

N U MB E R |I| Unique numeric identifier for a

vehicle type.
NOTE: Number must be the first
keyword coded on the
VEHICLETYPE control statement.
Valid values range from 1 to 255.

CR OW D CU R V E |IV10| Optional. Crowd curve used to

adjust link travel times for a
particular user class. Specify per
user class.
Required to adjust link travel time.
Valid values range from 1 to 255.
By default, none is used.

CR U S H CA P |I| Vehicle’s crush capacity (the sum

of seated capacity and maximum
standing capacity). Must be greater
than or equal to the value of
SEATCAP.
Valid values range from 1 to
 20,000.

LOA D D IS T FA C |R| Optional. Percentage of seats

occupied when standing first
occurs. Represents load factor at
which passengers begin
experiencing additional perceived
travel time due to crowding.
Required for adjusting link travel
time.
Valid values range from 0.0 to
100.0. By default, model does not
consider crowding and load
factors.
NOTE: LOADDISTFAC inputs
support two decimal places. More
may be specified, but only two will
be considered. Please see
“Considerations on numeric
formats” on page 850.

LON GN A ME |S| Optional. Second unique string that

identifies the vehicle type (in
addition to NAME).

N A ME |S| Optional. Unique string that

identifies the vehicle type.

S E A T CA P |I| Optional. Vehicle’s seated

capacity.
Required for adjustment to link
travel time.
Valid values range from 1 to
10,000. By default, vehicle has
unlimited seating capacity.
Public Transport Program > Control statements > VEHICLETYPE > Example

Exam ple

Define vehicle type number 1 for a single-deck bus.

VEHICLETYPE NUMBER=1,
NAME="Bus single deck",
SEATCAP= 40, CRUSHCAP=55, LOADDISTFAC=0.9, CROWDCURVE=1
Public Transport Program > Control statements > WAITCRVDEF

WAITCRVDEF
Defines wait curves used to compute initial and transfer wait times at stop nodes based
on the frequency of services. See “Generalized cost” on page 936 for a description of
the wait-time calculation. Keywords include:
• N U MB E R

• N A ME

• LON GN A ME

• CU R V E

You may define up to 255 wait curves. You may allocate two wait curves to each stop
node with IW AITCURVE and XW AITCURVE . Use IWAITCURVE when the node is a trip’s first
boarding point and use XWAITCURVE at transfer points. Use the node-specific
W AITFACTOR to weight the wait time. You must input WAITCRVDEF statements in the Public
Transport system data file, specified with SYSTEM I.
The program provides default wait curves for initial boarding and transfers at stop nodes
where you do not assign wait curves. See “More on wait curves” on page 922 for details
about wait curves.
W A IT CR V D E F k e y wo rd s

Ke y wo rd D e s c rip tio n

N U MB E R |I| Unique number that identifies a

wait curve.
NOTE: Must be the first keyword
coded in a WAITCRVDEF control
statement.
Valid values range from 1 to 255.

N A ME |S| Optional. Unique string that

identifies a wait curve.

LON GN A ME |S| Optional. Second unique string the

identifies the wait curve (in addition
to NAME).

CU R V E |RKV10000| List of pairs of X-Y coordinates that

define wait curve. The X-axis
shows headway and the Y-axis
shows wait time.
Separate X and Y values in a pair
by a comma or a dash. Separate
each pair with a comma.
For example:
WAITCRVDEF NUMBER=1
LONGNAME="InitialWait"
NAME="InitWait",
CURVE=1,0.5, 16,8, 27,12,
48,15, 160,20
WAITCRVDEF NUMBER=2
LONGNAME="TransferWait"
NAME="XferWait", CURVE=1-
0.5, 4-2, 12-6, 20-8, 40-
15, 60-20
See “More on wait curves” on
page 922 for information about
default wait curves.
NOTE: CURVE inputs support two
decimal places. More may be
specified, but only two will be
considered. Please see
“Considerations on numeric
formats” on page 850.
Public Transport Program > Control statements > WAITCRVDEF > Example > Example

Exam ple

Defining wait curve number 1 for stops in the central business area.
WAITCRVDEF NUMBER=1,
NAME="CENTRAL-AREA"
CURVE=
1-0.5,
15-7.5,
100-12.0
Public Transport Program > Control statements > WAITCRVDEF > More on wait curves

More on w ait curves

The Public Transport program calculates wait times at a stop as a function of the
frequency of transit services at the stop. At each stop node, you may assign two wait
curves: IW AITCURVE , used when the node is the trip’s first boarding point, and
XW AITCURVE , used at transfer points in the trip.
Public Transport Program > Control statements > WAITCRVDEF > More on wait curves > Default wait curves

Default wait curves

The program uses default wait curves at nodes where you do not assign wait curves.
The following diagram shows the default wait curve at the first boarding point.

For transit services with a frequency of 60 vehicles per hour or more, the default wait
time is set to half a minute. The default curve uses a constant wait time in this case
because services with very small headways tend to have irregularly arriving vehicles,
causing the relationship between wait time and headway to break down.
The default wait curve for transfer points is half the headway of all services visiting the
stop.
Public Transport Program > Control statements > WAITCRVDEF > More on wait curves > Rules for defining wait curves

Rules fo r defining wait curves

The following rules apply to the coding/interpreting of wait curves:

• The first coded X-Y pair must have a minimum X-value of 1 and minimum Y-value of 0.5.

• Wait time (Y-axis) may not decrease as headway (X-axis) increases.

• Linear interpolation applies between coded points.

• The curve runs from the point (1- 0.5) to the first coded point. Wait time is fixed at 0.5
minutes for headways less than one minute.

• Extrapolation beyond the last coded point occurs at the same gradient as immediately
below that point.

Only the route-evaluation process uses wait curves.

Public Transport Program > Reports

Reports
This section describes the reports that the Public Transport program produces. You
select reports using a variety of control statements. The program writes the reports to the
main Cube Voyager print file unless otherwise stated.
The program can produce the following reports:
• Enumerated routes

• Evaluated routes

• Fare matrices

• Transit line summary (including passenger hours and distance if loads are present)

• Transit line loadings

• Transfers between modes (transit and nontransit)

• Transfers between operators

The REREPORT control statement produces a series of basic reports that let you examine
and understand the network-simplification and route-enumeration processes. See
“Network simplification” on page 947 for examples of these reports.
Public Transport Program > Reports > Enumerated routes

Enumerated routes
You can produce a report of enumerated routes with the ROUTEO keyword and its
subkeywords, REPORTI and REPORTJ . The program writes the report to the file specified
by REPORTO .

S a mp le e nume ra te d -ro ute re p o rt

REnum Route(s) from Origin 1 to
Destination 9
1 -> 773
773 -> 769 -> 769 lines GMB1-36A
769 -> 812 -> 9 lines PLB129A
Cost=16.649
1 -> 773
773 -> 769 -> 769 lines GMB1-36A
769 -> 796 -> 796 lines PLB1-113A
PLB129A
796 -> 799 -> 799 lines GMB1-39MB
PLB144B PLB129A
799 -> 812 -> 9 lines PLB129A
Cost=19.896
1 -> 773
773 -> 771 -> 771 lines GMB1-36A
771 -> 799 -> 799 lines GMB1-39MB
799 -> 812 -> 9 lines PLB129A
Cost=17.364
1 -> 2052
2052 -> 2058 -> 806 lines ISL-UP
806 -> 812 -> 9 lines PLB129A
Cost=19.896
1 -> 773
773 -> 764 -> 764 lines GMB1-24MB
764 -> 806 -> 806 lines PLB127B PLB129A
806 -> 812 -> 9 lines PLB129A
Cost=20.737
1 -> 773
773 -> 764 -> 764 lines GMB1-24MB
764 -> 812 -> 9 lines PLB129A
Cost=19.737

This example shows routes from zone 1 to zone 9. The first line for each route shows
the access leg from the origin zone to the first boarding point. Subsequent lines for a
route show pairs of transit and nontransit legs with the names of the transit lines running
on the transit legs. The shown cost is used for selecting potential routes; it is not the cost
used for evaluating routes.
The program will discard some of these routes for various reasons, such as a probability
of use less than a user-specified minimum, or alighting and reboarding the same line.
The Evaluated Routes report (“Evaluated routes” on page 927) lists routes that are
actually used between the zones.
In this example, the program finds five (potential) physical routes between zones 1 and
9. Some offer more than one combination of services.
Public Transport Program > Reports > Evaluated routes

Evaluated routes
You can produce a report of evaluated routes using either the ROUTEI or the ROUTEO
keyword and the corresponding subkeywords REPORTI and TRACEI. The program writes
the report to the file specified by REPORTO . Reports produced with REPORTI list routes
taken; reports produced with TRACEI give a tabular output detailing component costs and
summaries for each mode. When using multirouting, the report lists all routes used and
the probability of taking each of them.
Specify the required origin zones with the REPORTI or TRACEI subkeywords and the
required destination zones with the REPORTJ or TRACEJ subkeywords. Note that REPORTI
requires REPORTJ, and vice-versa.
The following topics show:
• Example produced with REPORTI

• Example produced with TRACEI

Public Transport Program > Reports > Evaluated routes > Example produced with REPORTI

Example produced w ith REPORT I

S a mp le e v a lua te d -ro ute re p o rt p ro d uc e d with

R E P OR T I
REval Route(s) from Origin 1 to
Destination 9
1 -> 773
773 -> 769 -> 769 lines GMB1-36A
769 -> 796 -> 796 lines PLB129A
796 -> 799 -> 799 lines PLB144B
799 -> 812 -> 9 lines PLB129A
Cost= 17.249 Probability=0.0848007
1 -> 773
773 -> 769 -> 769 lines GMB1-36A
769 -> 796 -> 796 lines PLB1-113A
796 -> 799 -> 799 lines GMB1-39MB
799 -> 812 -> 9 lines PLB129A
Cost= 17.096 Probability=0.0468973
1 -> 773
773 -> 764 -> 764 lines GMB1-24MB
764 -> 812 -> 9 lines PLB129A
Cost= 17.937 Probability=0.17571
1 -> 773
773 -> 764 -> 764 lines GMB1-24MB
764 -> 806 -> 806 lines PLB127B
806 -> 812 -> 9 lines PLB129A
Cost= 19.137 Probability=0.17571
1 -> 2052
2052 -> 2058 -> 806 lines ISL-UP
806 -> 812 -> 9 lines PLB129A
Cost= 19.896 Probability=0.226877
1 -> 773
773 -> 771 -> 771 lines GMB1-36A
771 -> 799 -> 799 lines GMB1-39MB
799 -> 812 -> 9 lines PLB129A
Cost= 15.764 Probability=0.163768
1 -> 773
773 -> 769 -> 769 lines GMB1-36A
769 -> 796 -> 796 lines PLB1-113A
796 -> 799 -> 799 lines PLB144B
799 -> 812 -> 9 lines PLB129A
Cost= 17.249 Probability=0.00468973
1 -> 773
773 -> 769 -> 769 lines GMB1-36A
769 -> 812 -> 9 lines PLB129A
Cost= 14.849 Probability=0.121547

This report shows multiple routes from zone 1 to zone 9, along with their probability of
use. The first line for each route shows the access leg from the origin zone to the first
boarding point. Subsequent lines for the route show pairs of transit and nontransit legs
with the names of the transit lines running on the transit legs.
The cost shown is the generalized cost of each route in minutes, weighted by the
probability of use. This cost includes walk and in-vehicle times, and boarding and
transfer penalties, but not wait time, which the program computes from the routes’
common segments for the origin-destination pair as a whole.
Public Transport Program > Reports > Evaluated routes > Example produced with TRACEI

Example produced w ith T RACEI

S a mp le e v a lua te d -ro ute re p o rt p ro d uc e d with T R A CE I

REval Route(s) from Origin 1129 to Destination 757
N: 1129 Mode WaitA TimeA Actual B/XPen Percvd Dist Total
Lines(weight)
-> 5409 30 - 14.00 14.00 - 14.00 0.75 0.75
-> 4544 2 5.00 11.00 30.00 3.00 38.00 9.03 9.78
76(0.031) 79(0.016) 80(0.953)
-> 4538 31 - 3.00 33.00 - 41.00 0.25 10.03
-> 4209 7 7.50 34.85 75.35 1.00 91.85 8.92 18.95
949(1.000)
-> 757 30 - 16.00 91.35 - 107.85 0.10 19.05
Mode TimeA Dist IWaitA XWaitA
2 11.00 9.03 5.00 0.00
7 34.85 8.92 0.00 7.50
30 30.00 0.85
31 3.00 0.25
Probability=0.5248
N: 1129 Mode WaitA TimeA Actual B/XPen Percvd Dist Total
Lines(weight)
-> 5409 30 - 14.00 14.00 - 14.00 0.75 0.75
-> 4249 2 5.00 20.00 39.00 3.00 47.00 18.27 19.02
76(0.667) 79(0.333)
-> 4201 31 - 1.30 40.30 - 48.30 0.11 19.13
-> 4209 7 7.50 17.70 65.50 1.00 82.00 4.53 23.66
1359(1.000)
-> 757 30 - 16.00 81.50 - 98.00 0.10 23.76
Mode TimeA Dist IWaitA XWaitA
2 20.00 18.27 5.00 0.00
7 17.70 4.53 0.00 7.50
30 30.00 0.85
31 1.30 0.11
Probability=0.47521

This report shows two possible routes from 1129 to 757. For each route, the report lists:
• Leg-by-leg information. The report contains a printed line for each leg, starting with the
access leg, followed by alternating transit and nontransit legs, and ending with the egress
leg. For each leg, the printed line shows destination node, mode, wait time, travel time,
cumulative actual total cost, perceived boarding and transfer penalties, cumulative
perceived cost, distance, cumulative distance, and transit lines used (along with
probability).

• Mode information. For each mode used, the report lists actual travel time, distance, and
wait times.

• Trip fare. If you model fares, the report includes the trip fare, in monetary units.

• Probability of taking the route.

Public Transport Program > Reports > Fare matrices

Fare matrices
You can produce a report of fare matrices with the FAREMATI keyword in the REPORT
control statement. The program writes the report to the main print file. The report shows
the contents of the input fare matrices, specified with FILEI FAREM ATI and used by fare
systems defined by the FARESYSTEM control statement.

S a mp le fa re -ma tric e s re p o rt
FareMatrix(FMI.1.FROMTO) for FareSystem 3
(FAREZONE-FROMTO):
--------------------------------------------------
----------
J: I=1 FareSystem 3 Tot= 11
-- --- ---------- - ---- --
1: 1 1 2 3 4
J: I=2 FareSystem 3 Tot= 14
-- --- ---------- - ---- --
1: 1 1 3 4 5
J: I=3 FareSystem 3 Tot= 20
-- --- ---------- - ---- --
1: 2 3 4 5 6
J: I=4 FareSystem 3 Tot= 20
-- --- ---------- - ---- --
1: 3 4 5 1 7
J: I=5 FareSystem 3 Tot= 23
-- --- ---------- - ---- --
1: 4 5 6 7 1
Public Transport Program > Reports > Transit line summary

Transit line summary

You can produce a report summarizing transit lines with the LINES keyword in the REPORT
control statement.

S a mp le tra ns it-line -s umma ry re p o rt (with line lo a d ing s )

REPORT LINES UserClass=Total
Name Mode Op Stp Cr Distance Time Pass
PassDist PassHr
Sort=MODE
---------------------------------------------------------------
-------------------
ISL-UP 1 1 14 - 13.60 13.56 28,407.36
15,403,939.52 2,557.14
ISL-DN 1 1 14 - 13.60 13.56 46,808.82
22,259,805.12 3,694.35
GMB1-29AA 7 11 3 - 2.46 6.48 1,295.35
39,401.16 15.01
GMB1-29AB 7 11 4 - 3.68 9.87 4,998.67
1,192,384.23 451.21
GMB1-53B 7 11 14 - 7.90 23.28 2.14
568.86 0.25
GMB1-55A 7 11 13 - 5.05 16.13 4,901.84
477,329.89 306.13
GMB1-49MA 7 11 5 - 2.70 8.28 16,684.93
2,308,165.02 1,202.95
GMB1-49MB 7 11 2 - 1.98 7.05 7,712.42
1,527,059.16 906.21
GMB1-24MA 7 11 10 - 6.07 17.53 31,436.51
8,892,119.27 3,785.20
GMB1-24MB 7 11 10 - 5.49 17.76 31,802.20
9,824,320.61 4,516.16
GMB1-2A 7 11 5 - 2.11 5.99 4,507.49
915,698.20 438.00
GMB1-2B 7 11 5 - 3.18 10.96 4,562.50
1,009,772.05 568.80
GMB1-16MA 7 11 4 - 8.97 20.90 5,178.26
4,630,383.81 1,797.44
GMB1-16MB 7 11 6 - 10.29 26.14 2,007.41
1,800,646.77 699.25
GMB1-1A 7 11 5 - 6.01 13.86 202.24
3,790.72 0.91
GMB1-1B 7 11 5 - 7.08 19.15 370.56
16,756.35 19.74
GMB1-39MB 7 11 7 - 8.25 22.77 21,992.27
7,540,680.36 3,531.89
GMB1-55B 7 11 12 - 4.92 12.67 2,796.67
1,090,492.38 465.26
GMB1-52A 7 11 6 - 8.79 22.07 8,460.99
4,409,590.96 1,836.13
GMB1-52B 7 11 6 - 8.79 22.07 10,497.51
6,561,755.16 2,713.20
GMB1-39MA 7 11 6 - 8.39 22.10 44,765.14
11,716,456.15 5,232.96

This example shows transit lines sorted by mode. Because the public transport network
includes line loadings, this report includes passenger distance and passenger hours.
This report shows data for all user classes. The program also produces a separate
report for each user class.
If the public transport network does not include line loadings, the program only reports
transit line attributes once, as the attributes are common to all user classes.
Public Transport Program > Reports > Transit line loadings

Transit line loadings

You can produce a report of transit line loadings with the LINEVOLS keyword in the
REPORT control statement.

S a mp le o f tra ns it-line -lo a d ing re p o rt

REPORT LINEVOLS UserClass=Total
Name Mode Op
N ON OFF VOL
-----------------------------------
--------
ISL-DN 1 1
-----------------------
2072 7,526.20 -- 7,526.20
2070 -- 874.81 6,651.39
2068 20,072.95 1,692.68 25,031.66
2066 3,737.72 4,876.35 23,893.03
2062 7,132.78 1,290.47 29,735.34
2058 1,383.06 1,883.62 29,234.78
2056 1,817.37 13,423.42 17,628.73
2054 5,084.75 577.75 22,135.73
2052 45.97 15,108.40 7,073.30
2004 8.02 7,073.30 8.02
2001 -- 8.02 --

This example report shows the number of passengers boarding, alighting, and riding
through the nodes of a transit line. This report shows only stopping nodes with some
passenger activity because STOPSONLY and SKIP0 are set to T.
This report shows data for all user classes. You can request a separate report for each
user class.
If the program performed crowd modeling with wait-time adjustments, the program would
supplement reports showing all user classes with columns showing the flow-metered
boarding, alighting, and through-ridership volumes.
Public Transport Program > Reports > Transfers between modes

Transfers between modes

When performing loading, the program automatically produces two reports showing
transfers between modes:
• A report showing transfers between all modes (that is, transit and nontransit)

• A report showing transfers between transit modes (ignoring walk transfers between transit
modes)

The program produces these reports for each user class and for all classes combined.

S a mp le o f tra ns fe rs -b e twe e n-mo d e s re p o rt

REPORT XFERSUM=MODE UserClass=1
MODE 1 7 8 11 33 34
----------------------------------------------------------
------------
1 -- -- -- -- 35,419.40 39,796.77
7 -- 131,189.92 63,228.77 10,669.03 124,326.24 19,008.94
8 -- 58,769.06 29,930.60 5,459.60 49,723.45 17,346.75
11 -- 10,255.88 2,931.91 1,629.01 3,849.26 116.51
33 38,743.98 126,731.07 47,398.96 444.35 -- --
34 36,472.20 21,476.97 17,739.22 580.58 -- --
MODE names:
1 = Train
7 = Bus
8 = Underground
11 = Light Rail
33 = Access/Egress
34 = Walk Xfer
REPORT XFERSUM=TMODE UserClass=1
TMODE 1 7 8 11
-------------------------------------------------
1 -- 21,476.97 17,739.22 580.58
7 19,008.94 131,189.92 63,228.77 10,669.03
8 17,346.75 58,769.06 29,930.60 5,459.60
11 116.51 10,255.88 2,931.91 1,629.01
MODE names:
1 = Train
7 = Bus
8 = Underground
11 = Light Rail
33 = Access/Egress
34 = Walk Xfer
Public Transport Program > Reports > Transfers between operators

Transfers between operators

When performing loading, the program automatically produces a report showing
transfers between operators. The program produces this report for each user class and
for all classes combined.

S a mp le o f tra ns fe rs -b e twe e n-o p e ra to rs re p o rt

REPORT XFERSUM=OPERATOR UserClass=1
OPERATOR 1 11 14 19
-------------------------------------------
---------
1 -- 21,476.97 17,739.22 580.58
11 19,008.94 131,189.92 63,228.77 10,669.03
14 17,346.75 58,769.06 29,930.60 5,459.60
19 116.51 10,255.88 2,931.91 1,629.01
OPERATOR names:
1 = BR - Stratford - Lea Valley Services
11 = BR - Fenchurch Street
14 = BR - Upminster Branches
19 = BR - Liverpool Street - Via Stratford
Public Transport Program > Theory

Theory
This section discusses the theory used in the Public Transport program:
• Generalized cost

• Modeling approach

• Network simplification

• Route-enumeration process

• Route-evaluation process

• SFM and SFCM examples

• Skimming process

• Loading process

• Fares

• Crowding
Public Transport Program > Theory > Generalized cost

Generalized cost
Generalized cost is a measure of the main components of a Public Transport trip.
The generalized cost of a public transport trip has three components:
• Time
m
Walk time (nontransit time)
m
Wait time
m
In-vehicle time

• Inconvenience
m
Boarding penalty
m
Transfer penalty

• Cost
m
Fare

The route-evaluation process considers each component separately. The route

enumeration process, described in “Route enumeration cost calculation” on page 940,
uses a slightly simpler estimation.
A trip’s generalized cost automatically includes walk and in-vehicle time; the cost might
include wait time, boarding and transfer penalties, and fare, depending on the values of
keywords in the FACTORS control statement.
Generalized cost is a linear function of its components, weighted by coefficients. The
coefficients let you:
• Reflect passengers’ perceived importance of each component

• Convert the components to a common unit

The Public Transport program measures generalized cost in time, using minutes as the
s working units. Fares, if used, are input in monetary terms and converted into the
corresponding time units.
Subsequent sections provide details about individual components and their weighting
factors.
Public Transport Program > Theory > Generalized cost > Walk time (nontransit time)

Walk time (nontransit time)

Walking may occur at the following points in a trip:
• Between stop node and zone centroid, at the start and end of the trip

• Between stop nodes, as part of a transfer between services

• Between an origin and destination zone, without using any transit mode

You can develop walk links outside the Public Transport program and input the links to
the program, or you can develop the walk links when developing the public transport
network.
A link’s walk time (nontransit time) is typically the actual travel time. To convert the times
to perceived values (for inclusion in generalized costs), you can weight the link times
with the RUNFACTOR keyword.
Public Transport Program > Theory > Generalized cost > Wait time

Wait time
The program uses the combined headway of available transit services to compute the
wait time at any boarding point. Specifically, the program computes wait time from wait
curves that you specify. If you do not specify any wait curves, the program uses default
wait curves. To represent passengers’ ability to control wait time at the start of a trip but
not at transfer points, you may specify different wait curves for initial and subsequent
boardings at each node.
You define wait curves with the WAITCRVDEF control statement. You assign wait curves to
nodes with IW AITCURVE and XW AITCURVE keywords in the FACTORS control statement.
You can weight the wait times with the node-specific W AITFACTOR keyword.
The program uses default wait curves at nodes where you do not assign wait curves.
See “Default wait curves” on page 923 for a description of the default wait curves.
When the program performs crowd modeling with wait time adjustments, passengers
might experience additional wait time attributable to crowding. For example, a transit
service might be so loaded that a passenger cannot board (and must wait for a later
service). Similarly, a network bottleneck might occur (where demand exceeds capacity,
and some passengers cannot proceed forward within the modeled period). You model
these additional wait times with a node-specific W AITFACTOR keyword in the FACTORS
control statement.
Public Transport Program > Theory > Generalized cost > In-vehicle time

In-vehicle time
In-vehicle time is the time passengers spend travelling in a public transport vehicle for
each transit leg of a trip. If a trip has more than one leg, the value is the total in-vehicle
time for all legs.
You can weight in-vehicle time with a transit-mode-specific value specified with the
RUNFACTOR keyword.

When performing crowd modeling with link travel-time adjustments, the program also
weights in-vehicle time with a crowding factor.
Public Transport Program > Theory > Generalized cost > Boarding penalty

Boarding penalty
Boarding penalty is a fixed penalty applied at each boarding (that is, at the start of the
trip) and at each interchange. You may specify separate penalties for each mode. The
default penalty for each mode is zero (that is, no penalty).
You specify boarding penalties by mode with the BRDPEN keyword.
Public Transport Program > Theory > Generalized cost > Transfer penalty

T ransfer penalty
Transfer penalty is the transit-mode-to-transit-mode interchange penalty, which
represents the inconvenience of transferring between modes. The program applies this
penalty at transfer points, even if there is walking between the two modes. The penalty is
based on a combination of alighting and boarding modes.
The transfer penalty applies in addition to the boarding penalty for the subsequent transit
leg. For transfers between the same mode, you might set the transfer penalty to a
negative value to counteract or reduce the boarding penalty applied to the subsequent
leg of that mode.
You can ban changes between modes by setting a high transfer penalty, such as 999,
for that mode-to-mode combination. All mode-to-mode penalties default to zero—that is,
there are no penalties by default.
You specify transfer penalties with the XFERPEN keyword. You may add constants to
transfer penalties with the XFERCONST keyword, and you may weight transfer penalties
with the XFERFACTOR keyword.
Public Transport Program > Theory > Generalized cost > Fare

Fare
By defining fare models, you can include fares in the route-evaluation and skimming
processes. Fare models describe how the program computes the fare for part of a trip or
for an entire trip.
You define fare models with the FARESYSTEM control statement, and specify the input file
with the FILEI control statement and FAREI keyword.
You associate fare models with transit lines two ways:
• Directly with the LINE statement and FA R E S Y S T E M keyword

• Through their mode or operator attribute, with the FACTORS control statement and
FA R E S Y S T E M keyword
Public Transport Program > Theory > Generalized cost > Route enumeration cost calculation

Route enumeration cost calculation

Route enumeration is a heuristic process that identifies a set of discrete routes between
zone pairs along with the probability that passengers will use the routes to travel
between the zones.
Data compression techniques improve the performance of the route-enumeration
process. For example, the process bundles together transit legs with the same boarding
and alighting points, and enumerates routes only for the cheapest leg in the bundle.
(The process disaggregates transit leg bundles for analysis.) For this reason, the
process cannot use all the components of generalized cost.
The route-enumeration process converts the following components to generalized cost
units:
• In-vehicle time, weighted by mode-specific factor specified with the R U N FA CT OR (using the
value of the bundle’s fastest transit line)

• Boarding penalty

• Wait time, weighted by W A IT FA CT OR and subject to a range defined by R E W A IT MIN and

R E W A IT MA X

The route-enumeration process uses a simple estimate of wait time for each leg
bundle. The process computes the headway for each bundle’s boarding node from
the sum of the frequencies of the bundle’s legs. The process sets the wait time to half
this headway, weighted by WAITFACTOR. Where necessary, the process adjusts the
resulting value to fall within the range set by REWAITMIN to REWAITMAX. You can
exclude wait time from the route-enumeration process by setting these factors to zero.
• Walk time, taken directly from nontransit legs and weighted by an appropriate RUNFACTOR

When modeling best paths (or when REBESTPATHCOST is T), the route-enumeration
process handles some of these components differently. In this case:
• Calculations of wait and in-vehicle time depend on the value of FR E QB Y MOD E :
m
When true (default value), the process computes these times for individual modes (and
the value for fastest mode subsequently used in enumeration).
m
When false, the process computes these times across all modes in a transit leg bundle.

• In-vehicle time is based on the average value for lines in the transit leg bundle. The
process uses the calculations described in “SFM and SFCM examples” on page 975 to
discard any slow routes in the bundle and to obtain the required value.

• Wait time is calculated using initial or transfer wait curves and W A IT FA CT OR (as in the route-
evaluation process). The process uses the headway of the transit-leg bundle (or the lines
 of a particular mode in the bundle) after discarding any slow routes. For best-path models,
the route-enumeration process uses transfer penalties (based on XFE R CON S T ,
XFE R FA CT OR , and XFE R P E N ) when identifying discrete routes.

The route-enumeration process does not consider fares, and ignores transfer penalties
except when modeling best paths. Instead, the route-evaluation process disaggregates
transit-leg bundles by mode to apply transfer penalties. Using fares and transfer
penalties with leg bundles during route enumeration could eliminate valid routes. For
example, consider a banned transfer between transit modes 3 and 5. Routes transferring
from a mode-3 leg to a mode-5 leg would be eliminated. However, suppose these legs
are the top legs in bundles that contain legs of other modes. These other legs would
also be eliminated.
The route-enumeration process adds wait time to the time of each bundle’s top leg to
obtain a transit-leg cost.
The report produced by the TRNLEGS3 keyword in the REREPORT control statement shows
the generalized cost of transit legs used during the route-enumeration process.
Public Transport Program > Theory > Modeling approach

Modeling approach
This section discusses the algorithms that the Public Transport program uses. The
program supports two distinct modeling methods: multirouting and best-path. For both
modeling methods, the program finds attractive or reasonable routes, (that is, routes that
have some probability of use), in three steps: network simplification, route enumeration,
route evaluation. You can restrict modeling to consider just those routes that use a
particular transit mode at some stage in the trip.
This section discusses:
• Multirouting and best-path methods

• Network simplification

• Route enumeration

• Route evaluation

• Limiting selected routes to particular transit modes

• Advantages of the Public Transport program for multirouting

Public Transport Program > Theory > Modeling approach > Multirouting and best-path methods

Multirouting and best-path methods

During a public transport trip, passengers must make decisions at several points on their
route. When on a transit line, passengers might need to decide which stop to alight at (in
order to transfer or walk to their destination). At the origin and on completion of a transit
leg, passengers must decide where to board the next transit leg. At a stop, passengers
must choose between the transit lines that enable progress toward the destination.
A number of possible methods, or modeling philosophies, are possible at each decision
point. The Public Transport program includes two distinct methods:
• Multirouting — Evaluate multiple routes and calculate the probabilities of using each one.

• Best-path — Identify a single “best path” route for an origin-destination pair.

For example, suppose travelers waiting at node N have a choice between two routes to
reach the trip’s destination. The first route uses line L, which runs every 20 minutes and
takes 15 minutes to reach the destination after boarding. The second route uses line M,
which runs every 30 minutes and takes 11 minutes to reach the destination. Either line
offers an efficient effective route towards the required destination. Taking these values
as components of the generalized cost (without need for further weighting), you can
compute an expected travel time from the stop to the destination.
In a multirouting model, travelers are prepared to board whichever bus comes first.
There are a total of five services per hour. Assuming equal spacing of departures, the
combined headway is 12 minutes and average wait is 6 minutes. The cost to the
destination is the wait time plus travel time, either 11+6 or 15+6, that is, 17 or 21.
Assuming route usage proportional to service frequency, the average time to destination
is 19.4 minutes.
In a best-path model, travelers choose between the two routes and then wait for a
service on the chosen transit line (ignoring any service on the other line). Travelers
assess attributes of each route: L has an average wait of 10 minutes and travel time of
15 minutes, for a total cost of 25 minutes. M has an average wait of 15 and travel time of
11, for a total of 26 minutes. Therefore, travelers using the best-path method would
select transit line L, with an average trip cost of 25 minutes.
Model developers must decide between the two methods. The appropriate method
might depend on externally imposed requirements or practices (for example, guidelines
from government departments) or a choice regarding the suitability of each method.
Many modelers prefer the multirouting method in cities with extensive, well-developed
public transport systems.
Public Transport Program > Theory > Modeling approach > Network simplification

N etw ork simplification

To improve performance and to minimize memory and storage requirements, the Public
Transport program simplifies the public transport network into a set of intermediate data
structures:
• Transit legs

• Transit leg bundles

• Nontransit legs

• Line-zone leg

• Line-line legs

See “Network simplification” on page 947 for a description of these data structures.
Public Transport Program > Theory > Modeling approach > Route enumeration

Route enumeration
For multirouting modeling, the route-enumeration process finds all potentially attractive
routes and enumerates them. The process follows three principles:
• The trip should move progressively from the origin to the destination.

• Travelers prefer simpler trips, that is, direct trips or trips that involve few transfers.

• Travelers are unwilling to walk very long distances.

The route-enumeration process uses these principles to identify reasonable routes.

First, the process establishes connectivity between transit lines. This step is analogous
to travelers examining a map and identifying the sequence of lines they can use to travel
from their origin to their destination. The process limits routes by choosing simpler trips
and trips with shorter walking distances during line-to-line transfers.
Next, the process identifies the route attributes—basic cost and number of transfers—and
compares them, selecting reasonable routes for evaluation. This step is analogous to
travelers rejecting routes that are very long relative to more direct alternatives.
For best-path modeling, the route-enumeration process identifies possible routes for the
best single path between an origin and a destination. The route-enumeration process
uses the same cost components as the route-evaluation process, with the exception of
transfer penalties. The route-enumeration process allows for possible transfer-penalty
values, and enumerates any route which potentially could be the best route.
See “Route-enumeration process” on page 959 for a detailed description of this
process.
Public Transport Program > Theory > Modeling approach > Route evaluation

Route evaluation
For multirouting models, the route-evaluation process takes the explicit list of reasonable
routes between an origin and destination and determines which routes passengers will
use to make trips and what fraction of passengers will use each route.
The route-evaluation process treats the routes like a hierarchy of conditional choices:
Each stop or branch point represents a decision whether to board a service, alight from
a service, or walk elsewhere to board another service. The program uses conventional
algorithms to forecast these individual choices. For example, the program uses
information about the trip sequence to preclude alighting and reboarding the same
service.
For best-path models, the route-evaluation process identifies the best path using a
similar evaluation method, and assigns all demand to that route.
Public Transport Program > Theory > Modeling approach > Limiting selected routes to particular transit modes

Limiting selected routes to particular transit modes

The Public Transport program uses the route-enumeration process to identify possible
routes from an origin to a destination, followed by a the route-evaluation process to
evaluate the routes. The enumerated routes may vary widely in characteristics, perhaps
having different transfer points, and using different modes.
Sometimes you might want routes to use a particular mode. Earlier software packages
used biases to attract travelers toward one mode and away from other modes. However,
biasing could lead to modeling distortions affecting route costs or identification of the
best route.
With the Public Transport program, you need not use biases. Instead, you can specify a
“must-use-mode”—a mode that must be used during at least one leg of a public transport
route in order for the Public Transport program’s route-enumeration process to select
that route.
Public Transport Program > Theory > Modeling approach > Advantages of the Public Transport program for multirouting

Advantages of the Public T ransport program for

multirouting
Some software packages trace paths from all zones to a particular zone or vice-versa.
Such paths do not retain the history of a trip at a node (that is, how the path reached the
node or where the path came from). When using multiroute paths, such packages
cannot easily extract route-based information, such as station-to-station movements,
matrices of trips using selected links or transit lines, or mode-to-mode and operator-to-
operator transfers.
The Public Transport program finds discrete multiple routes between pairs of zones.
Therefore, unlike traditional software packages, the Public Transport program operates
at the zone-pair level rather than at the zonal level. The Public Transport program
requires more computational time but produces more useful and better quality results.
The Public Transport program addresses other common problems associated with
multirouting:
• Calculating wait time at stops using the combined frequency of visiting services

• Modeling access, egress, and transfer choices

• Modeling combination of frequent and infrequent services

Public Transport Program > Theory > Network simplification

Network simplification
Public transport networks are often quite detailed and data intensive. To improve
algorithm performance and minimize memory and temporary disk storage, the Public
Transport program simplifies the network for enumerating and storing routes. The
program stores the simplified network in intermediate data structures, which you can
examine to gain an understanding of how multirouting works in the Public Transport
program.
Use the DELM ODE , DELACCESSM ODE , and DELEGRESSM ODE factors to remove legs of
particular modes from the network representation. The program does not use specified
legs at any stage in the modeling.
This section introduces the network representations used for:
• Transit legs

• Transit-leg bundles

• Nontransit legs

• Line-zone legs

• Line-line legs
Public Transport Program > Theory > Network simplification > Transit legs

T ransit legs
A transit leg is a trip segment, from a boarding point to an alighting point, that uses a
single transit line. Travel on the transit line can be over one or more links in the public
transport network. (A trip consists of an access leg, and one or more pairs of transit leg
bundles and nontransit legs, the last of which is the egress leg.)
Use the REREPORT control statement and LINES keyword to produce a line-attribute report.

Line -a ttrib ute re p o rt

REPORT: LINES
Int Fare #Line #Stop Line
Line# DIR Mode OP HDWAY Type Nodes Nodes Name
---------------------------------------------
------
20 (f) 7 11 5.00 0 10 5 GMB1-1B
Dis- Line Stop
Node Time tance Node# Node#
--------------------------------------
727 0.00 0.00 1 1
-897 0.28 0.12 2 0
-947 0.97 0.42 3 0
875 1.99 0.80 4 2
751 5.54 1.15 5 3
-881 6.36 1.55 6 0
748 7.10 1.92 7 4
-745 8.40 2.39 8 0
-746 12.33 4.16 9 0
747 19.15 7.08 10 5

Use the REREPORT control statement and TRNLEGS3 keyword to produce a line-ordered
transit-leg report.

S a mp le tra ns it-le g re p o rt fo r the GMB 1-1B tra ns it line

REPORT: TRANSIT LEGS III (Legs for Lines)
(REnum Time = actual time * RUNFACTOR + BRDPEN)
Int Fare #Line #Stop Line
Line# DIR Mode OP HDWAY Type Nodes Nodes Name
-----------------------------------------------
----
20 (f) 7 11 5.00 0 10 5 GMB1-1B
Top ON OFF Time Time Dis-
Leg Node Node Actual REnum tance
----------------------------------------------
727 875 1.99 4.99 0.80
727 751 5.54 8.54 1.15
727 748 7.10 10.10 1.92
* 727 747 19.15 22.15 7.08
875 751 3.55 6.55 0.35
875 748 5.11 8.11 1.12
* 875 747 17.16 20.16 6.28
751 748 1.56 4.56 0.77
* 751 747 13.61 16.61 5.93
* 748 747 12.05 15.05 5.16
* Top leg of a leg bundle, see “Transit-leg bundles.”
Public Transport Program > Theory > Network simplification > Transit-leg bundles

T ransit-leg bundles
A transit-leg bundle is a collection of transit legs that use different transit lines but board
and alight start at the same node. Transit-leg bundles have the following properties:
• The “top leg” of the bundle is the cheapest in terms of travel time (in the example all legs
within bundles have the same time).

• They may or may not traverse the same links of the underlying network.

The route-enumeration process treats transit-leg bundles as single entities, thus

simplifying and reducing the data to examine and enumerate. The program individually
evaluates each leg within a transit-leg bundle when determining “attractive” routes for
loading and skimming.
Use the REREPORT control statement and TRNLEGS2 keyword to produce a node-ordered
transit-leg-bundle report.

E xc e rp t fro m no d e -o rd e re d tra ns it-le g -b und le re p o rt

REPORT: TRANSIT LEGS II (Leg Bundles from Nodes)
(REnum Time = Actual Time * RUNFACTOR + BRDPEN)
(And top leg in Bundle includes Estimated Wait
time for Bundle)
Top ON OFF Time Time Dis- Line
Leg Node Node Actual REnum tance Name
------------------------------------------------
---
* 875 753 5.03 6.03 0.83 GMB1-24MA
875 753 5.03 5.53 0.83 PLB1-113A
875 753 5.03 5.53 0.83 PLB129A
875 753 5.03 6.04 0.83 RES-903R
* 875 757 5.32 6.32 1.06 GMB1-24MA
875 757 5.32 5.85 1.06 PLB1-113A
875 757 5.32 5.85 1.06 PLB129A
875 757 5.32 6.38 1.06 RES-903R
* 875 765 6.30 9.30 1.66 GMB1-24MA
* 875 774 7.75 10.75 1.95 GMB1-24MA
* 875 773 8.26 11.26 2.35 GMB1-24MA
* 875 776 13.04 16.04 4.30 GMB1-24MA
* 875 778 17.37 20.37 5.97 GMB1-24MA
* 875 751 3.55 4.55 0.35 GMB1-2B
875 751 3.55 3.55 0.35 GMB1-24MA
875 751 3.55 3.55 0.35 GMB1-1B
875 751 3.55 3.91 0.35 PLB1-113A
875 751 3.55 3.91 0.35 PLB129A
875 751 3.55 4.26 0.35 RES-903R
* 875 748 5.11 7.36 1.12 GMB1-2B
875 748 5.11 5.11 1.12 GMB1-1B

This sample shows transit legs from node 875, including three sets of leg bundles: from
node 875 to nodes 753, 757, and 751. When multiple lines connect node 875 to an
alighting node, the report marks the top line (the fastest line or the first line, if all have
equal time) with “*.” All legs in a bundle have the same actual in-vehicle time, but the
REnum time for the bundle’s top leg includes an estimate of the bundle’s waiting time.
(Do not confuse this waiting time with the wait time calculated during the route-
evaluation process. See “Generalized cost” on page 936.)
Public Transport Program > Theory > Network simplification > Nontransit legs

N ontransit legs
Nontransit legs are minimum-cost segments, traversed by nonmechanized modes.
Nontransit legs connect:
• Zones and stop nodes or stop nodes and zones that allow access to and egress from the
transit system

• Two stop nodes that allow a transfer between two lines

Nontransit legs may traverse none (special case), one, or multiple physical links. The
program derives leg attributes from link attributes.
The program can generate nontransit legs with the GENERATE control statement, input
user-specified nontransit legs, or do both. The program associates a cost with these
nontransit legs.
The program automatically generates a third type of “notional” nontransit leg, which
allows transfers between two lines visiting the same node. Such nontransit legs do not
have any associated cost.
Boarding and transfer costs apply to both types of transfers—those occurring at a node
and those between two nodes connected with a physical nontransit leg.
Use the REREPORT control statement and ACCESSLEGS, EGRESSLEGS, and XFERLEGS
keywords to produce nontransit-leg reports.

S a mp le no ntra ns it-le g re p o rt: R E R E P OR T

A CCE S S LE GS
REPORT: ACCESS LEGS
Desti- Dis-
Origin nation Time tance Mode
--------------------------------------
--
1 773 2.56 0.25 33
1 2052 8.70 0.36 33
1 3674 2.70 0.18 33
2 778 1.36 1.06 33
3 749 3.12 0.78 33
4 750 0.40 0.31 33
4 875 1.52 0.32 33
4 2004 7.52 0.41 33
5 959 2.70 0.11 33
6 796 1.92 0.38 33
6 800 1.92 0.39 33
6 2054 5.40 0.53 33
6 2056 5.92 0.43 33

S a mp le no ntra ns it-le g re p o rt: R E R E P OR T

E GR E S S LE GS
REPORT: EGRESS LEGS
Desti- Dis-
Origin nation Time tance Mode
--------------------------------------
--
703 19 0.64 0.23 33
705 19 0.96 0.19 33
709 19 0.96 0.70 33
714 20 1.32 0.22 33
716 20 1.80 0.24 33
721 21 1.68 0.42 33
725 22 6.00 0.24 33
728 22 0.52 0.36 33
730 22 0.76 0.20 33
734 22 0.80 0.30 33
735 23 2.64 2.46 33
747 24 1.72 0.43 33
749 3 3.12 0.78 33

S a mp le no ntra ns it-le g re p o rt: R E R E P OR T

XFE R LE GS
REPORT: TRANSFER LEGS
Desti- Dis-
Origin nation Time tance Mode
-------------------------------------
---
701 701 0.00 0.00 -1*
702 702 0.00 0.00 -1
703 703 0.00 0.00 -1
800 800 0.00 0.00 -1
800 2056 4.00 0.04 34
803 803 0.00 0.00 -1
806 806 0.00 0.00 -1
806 2058 4.00 0.27 34
813 813 0.00 0.00 -1
813 2060 4.00 0.16 34
823 2062 4.00 0.11 34
830 830 0.00 0.00 -1
830 2066 4.00 0.02 34
837 837 0.00 0.00 -1
838 838 0.00 0.00 -1
838 2072 3.00 0.11 34
* -1 indicates a direct transfer, without any walking.
Public Transport Program > Theory > Network simplification > Line-zone legs

Line-zone legs
During network simplification, the program expands access and egress nontransit legs—
legs from zone to stop node and vice versa—into zone to line and line to zone legs. The
program stores line-zone legs as pointers to the corresponding access and egress
nontransit legs along with some additional information that helps improve the
performance of the route-enumeration algorithm.
When multiple access and/or egress legs exist between a zone and a line, the program
might eliminate some legs or restrict their use to ensure that routes starting or terminating
on a line use distinctive segments and do not overlap. For best-path models, the
program uses all connectors to ensure identification of the best route; because the
program selects exactly one best route, overlapping segments are not possible.
For multirouting models, the program eliminates multiple access legs by applying the
following rules:
• Among a set of legs accessing consecutive stops (disregarding intermediate nonstopping
nodes), select the leg with the least generalized cost and discard the others. (Between legs
of equal cost, select the downstream leg.) If SHORTESTWALK=F then selection is based
on lowest travel time to some downstream point on the line (rather than shortest leg cost).

• Always retain the first access leg (that is, the leg connected to the transit line’s earliest
stop).

• If the cost of the “first access + riding to the next” is more than the cost of the next access,
those boarding at the first access may only ride until the stop before the next access.

• If the cost of the “first access + riding to the next” is less than the next access, discard the
next access.

• Each access has a stop up to which those boarding can ride; either to the stop before the
next valid access or to the end of the line.

For multirouting models, the program eliminates multiple egress legs by applying the
following rules:
• Among a set of legs providing egress from consecutive stops (disregarding intermediate
nonstopping nodes), select the leg with the least generalized cost and discard the others.
(Between legs of equal cost, select the upstream leg.) If SHORTESTWALK=F then
selection is based on travel time from some upstream node on the line.

• Always retain the last egress leg (that is, the leg connected to the transit line’s latest stop).

• If the cost of an egress leg is more than the cost of “riding to the next + next egress,”
discard the leg.

• If the cost of the an egress leg is less than the cost of “riding to the next + next egress,”
 then only those boarding after the current egress can use the next one.

• Each egress has a stop that specifies the beginning of a range of valid boarding stops; this
may be the stop after the previous valid egress or the beginning of the line.

Both sets of rules apply to circular lines.

Use the REREPORT control statement and LINEZONLEG1 LINEZONLEG2 keywords to produce
line-to-zone nontransit-leg reports.

S a mp le line -o rd e re d line -to -zo ne no ntra ns it-le g

re p o rt
(R E R E P OR T LIN E ZON LE G1)
REPORT: LINE ZONE I (In Line Order)
Origin Dest Dis- Access/ Line
Node Node Time tance Egress Name
-------------------------------------------
--
6 800 1.92 0.39 Access GMB1-49MA
800 6 1.92 0.39 Egress GMB1-49MA
7 803 1.52 0.41 Access GMB1-49MA
803 7 1.52 0.41 Egress GMB1-49MA
8 814 0.88 0.12 Access GMB1-49MA
814 8 0.88 0.12 Egress GMB1-49MB
3 749 3.12 0.78 Access GMB1-2A
22 728 0.52 0.36 Access GMB1-2A
728 22 0.52 0.36 Egress GMB1-2A
749 3 3.12 0.78 Egress GMB1-2B
4 875 1.52 0.32 Access GMB1-2B
875 4 1.52 0.32 Egress GMB1-2B
15 852 1.52 1.33 Access GMB1-29AA
855 16 1.80 0.97 Egress GMB1-29AA
852 15 1.52 1.33 Egress GMB1-29AB
16 855 1.80 0.97 Access GMB1-29AB

S a mp le zo ne -o rd e re d line -to -zo ne no ntra ns it-le g

re p o rt
(R E R E P OR T LIN E ZON LE G2)
REPORT: LINE ZONE II (In Zone Order)
Origin Dest Dis- Access/ Line
Node Node Time tance Egress Name
-------------------------------------------
--
1 773 2.56 0.25 Access GMB1-24MA
1 773 2.56 0.25 Access GMB1-24MB
1 773 2.56 0.25 Access GMB1-36A
1 773 2.56 0.25 Access GMB1-36B
1 2052 8.70 0.36 Access ISL-UP
1 2052 8.70 0.36 Access ISL-DN
773 1 2.56 0.25 Egress GMB1-24MA
773 1 2.56 0.25 Egress GMB1-24MB
773 1 2.56 0.25 Egress GMB1-36A
773 1 2.56 0.25 Egress GMB1-36B
2052 1 8.70 0.36 Egress ISL-UP
2052 1 8.70 0.36 Egress ISL-DN
2 778 1.36 1.06 Access GMB1-24MB
778 2 1.36 1.06 Egress GMB1-24MA
3 749 3.12 0.78 Access GMB1-2A
749 3 3.12 0.78 Egress GMB1-2B
4 750 0.40 0.31 Access PLB1-113B
4 750 0.40 0.31 Access PLB129B
4 750 0.40 0.31 Access PLB127A
4 750 0.40 0.31 Access PLB127B
4 750 0.40 0.31 Access RES-91R
Public Transport Program > Theory > Network simplification > Line-line legs

Line-line legs
During network simplification, the program expands nontransit legs between stop nodes,
direct transfers at the same stop node, and walk transfers between stops into line-to-line
legs. The program stores line-line legs as pointers to the nontransit transfer legs along
with some additional information that improves the performance of the route-
enumeration algorithm.
The route-enumeration process eliminates some transfer legs. When generating line-to-
line legs, the program applies the following rules:
• For multirouting, among multiple connectors between consecutive stops on a “from-line”
and consecutive stops on a “to-line,” retain only the lowest-cost connector; discard the
others. If SHORTESTWALK=F then the connector with shortest through travel time from
an upstream node on the from-line to a downstream node on the to-line is selected (rather
than the lowest cost connector).

• Do not permit transfers from a transit line’s first node; passengers must use the line before
transferring.

• Do not permit transfers to a transit line’s last node.

• For circular lines with the same first and last nodes, permit boarding at the first node and
alighting at the last node.

• For multirouting, prohibit transfers involving backtracking, such as if the node prior to
alighting is the same as the one after boarding.

• If two lines traverse the same physical route with the same stop characteristics, record only
one transfer location for consecutive stops.
For example, consider the following transit lines.
In this case, the program only records one transfer location between
Lines A and B instead of four—the last stop. The program relaxes this
restriction during route evaluation to give flexibility in transfer location, especially when
modeling crowding.
However, if stop 2 is a stopping node for line A and not for line B, then the program
records two transfer locations: one at stop 1 and one at stop 4 (representing transfers
at stops 3 and 4). If two lines meet at nonconsecutive stops, diverging between them,
the program records a transfer location at each stop where they meet.
Use the REREPORT control statement and LINELINELEG keyword to produce line-to-line
transfer-leg reports.

S a mp le line -to -line tra ns fe r-le g re p o rt (R E R E P OR T

 LIN E LIN E LE G)
REPORT: LINE TO LINE LEGS
From/To From/To From/To
LineNode NodeSeq# LineName
------------------------------
799 7 GMB1-49MA
799 14 PLB144A
806 4 GMB1-49MA
806 7 PLB144B
806 4 GMB1-49MA
806 34 PLB129A
799 7 GMB1-49MA
799 14 PLB129B
806 4 GMB1-49MA
2058 13 ISL-UP
806 4 GMB1-49MA
2058 16 ISL-DN
800 6 GMB1-49MA
2056 10 ISL-UP
800 6 GMB1-49MA
2056 19 ISL-DN
799 7 GMB1-49MA
799 1 GMB1-39MA
Public Transport Program > Theory > Route-enumeration process

Route-enumeration process
Route enumeration is a heuristic process that identifies a set of discrete routes between
zone pairs along with the probability that passengers will use the routes to travel
between the zones. Use keywords in the FACTORS and PARAMETERS control
statements to control the route-enumeration process.
The program measures trip cost differently during route-enumeration than during route-
evaluation. See “Route enumeration cost calculation” on page 940.
Route enumeration has three distinct stages:
• Finding minimum-cost routes

• Establishing connectivity between lines

• Enumerating routes

The process varies only slightly when you specify a must-use mode. See “Enumerating
routes with a must-use mode specified” on page 964. Public Transport also includes an
option to enhance the stability of the process under small variations of input network
characteristics. See “Modified route enumeration process” on page 965.
Public Transport Program > Theory > Route-enumeration process > Finding minimum-cost routes

Finding minimum-cost routes

The route-enumeration process finds minimum-generalized-cost routes between zone
pairs to establish a baseline cost. Each route has an access leg, and one or more pairs
of transit and nontransit legs, the last of which is an egress leg. Using explicit couples of
transit and nontransit legs is consistent with the multiroute-enumeration process,
described in “Enumerating routes” on page 963.
Because the process starts with transit-leg bundles rather than individual transit legs, the
process might disaggregate a minimum-cost route into one or more discrete routes. For
example, the following minimum-cost route is a collection of 14 individual routes:
Route(s) from Origin 1 to destination 100
1 -> 1276
1276 -> 1572 -> 1583 lines 744 746
1583 -> 1654 -> 100 lines 399 476 478 486 489 493 495

where:
• Node pair 1->1276 is the access leg from node 1.

• Triplet 1276->1572->1583 represents a transit leg between node 1276 and node 1572 on
line 744 or 746, and a nontransit-transfer leg between node 1572 and node 1583.

• Triplet 1583->1654->100 represents a transit leg between node 1583 and node 1654 on
line 399, 476, 478, 486, 489, 493, or 495, and an egress leg between node 1654 and node
100.

The route via lines 744 and 399 will have the best travel cost; the other routes may have
the same or slightly longer vehicle travel time.
The route minimizes the generalized cost, not the number of transfers. Therefore,
identified routes might have more than M AXFERS transfers. However, you can reflect the
impact of transfers in the generalized cost with sensible boarding penalties.
You can specify a “spread,” an upper cost limit for routes between an O-D pair when
using multirouting. Select the function for calculating the spread with the SPREADFUNC
keyword, and specify function parameters with the SPREADFACT and SPREADCONST
keywords. The route-enumeration process uses the costs from the minimum cost routes
and the spread to determine a maximum cost value for “reasonable” routes to that
destination.
Similarly, to set the maximum number of transfers permitted on “reasonable” routes to a
destination, the route-enumeration process uses the number of transfers from the
minimum-cost routes along with EXTRAXFERS1 and EXTRAXFERS2 .
Minimum-cost routes minimize some combination of user-specified trip attributes.
Passengers might not select such routes. This is a reason to prefer multirouting, which
includes both the direct and indirect routes in the full list of enumerated routes.
If a destination’s minimum-cost route uses more than M AXFERS transfers and the route-
enumeration process has identified no other routes, then the process will enumerate this
single route provided the route has no more than AONM AXFERS transfers and the route
meets any must-use-mode requirements.
Public Transport Program > Theory > Route-enumeration process > Establishing connectivity between lines

Establishing connectivity betw een lines

For each transit line, the route-enumeration process generates a set of connectors that
describe available connections with other transit lines. Connectors are subject to
constraints imposed by the keywords M AXFERS , EXTRAXFERS1 , and EXTRAXFERS2 .
Each connector consists of a set of lines: the “from” line, the “to” line, and intervening
lines required to reach the “to” line. The connector’s length (that is, the number of
transfers) is controlled by the three keywords mentioned.
The route-enumeration process only generates connectors for lines that have access
legs from origin zones specified with the ROUTEO keyword and I subkeyword. The default
configuration specifies all zones, and the process builds connectors for all lines.
When generating connectors, the process treats lines like nodes and treats line-to-line
connections like links in a network. The process stores connectors in a very
compressed form; at this stage the process only requires the number of transfer points
and the lines reached. The process examines alternative transfer points between lines
when enumerating the route—in the next stage.
For example, consider the illustrated public transport network.

For this network, the route-enumeration process generates the following connectors for
line A:
• Line A to line B (note there are two interchange points between these lines)

• Line A to line C via line B

• Line A to line C via line D

• Line A to line D

Line-to-line legs handle all transfers—direct, between lines A and B and lines B and C,
and by walking, between lines A and B and lines A and D.
Public Transport Program > Theory > Route-enumeration process > Enumerating routes

Enumerating routes
After generating the connectors for a transit line, the route-enumeration process
enumerates routes for each selected origin zone connecting to the line via a valid
access leg. The process uses two steps:
• Expand routes with viable connections
m
Record the beginning of the first route: origin zone and nontransit (access) leg.
m
Examine the transfer points between the first two lines of the connector. If the transit leg
used on the first line is the bundle’s top leg, and the time to the next boarding point (that
is, the sum of time for transit and nontransit legs) is within the spread established
earlier, and the number of transfers meets the constraints set by MAXFERS,
EXTRAXFERS1 and EXTRAXFERS2, extend the route by the transfer.
m
Examine each interchange between the two lines in the same way.
m
Repeat the process for the subsequent lines in the connector set until connections have
been fully expanded.

• Output valid routes

m
Examine expanded routes to find routes that link to nontransit legs terminating in zones.
m
If the complete route between the O-D pair meets the spread, transfer, and destination-
zone selection (ROUTEO J) criteria, output as a route between that O-D pair.

For example, consider the connector, “line A to line C via line B,” shown in the example
in “Establishing connectivity between lines” on page 962. The route-enumeration
process generates the routes in the following table.

Orig in N o ntra ns it T ra ns it N o ntra ns it T ra ns it N o ntra ns it D e s tina tio n

Zo ne Le g Le g Le g Le g Le g Zo ne

O O-A x
(access)

O O-A (access) A (ride) A-B1 (walk) x

O O-A (access) A (ride) A-B2 x

(direct)

O O-A (access) A (ride) A-B1 (walk) C (ride) C-D D

(egress)

O O-A (access) A (ride) A-B2 C (ride) C-D D

(direct) (egress)

The process does not re-record the common parts of routes, shown in italics.
Public Transport Program > Theory > Route-enumeration process > Enumerating routes with a must-use mode specified

Enumerating routes w ith a must-use mode specified

When enumerating routes required to use a particular transit mode, the route-
enumeration process uses a similar procedure. If you specify two or more must-use
modes, the process enumerates any route that uses at least one of the modes.
When establishing the minimum-cost route, the process considers all possible routes,
regardless of whether they use the specified transit modes.
For a particular origin-destination pair, the process calculates a cost limit using spread
factors as described in “Finding minimum-cost routes” on page 960. If this value
exceeds the total of the cost (along the minimum-cost path) plus M UM EXTRACOST , then
the process reduces the cutoff value to this total. The limit on transfers is based on the
number of transfers on the minimum cost route, EXTRAXFERS1 and EXTRAXFERS2 .
The route-enumeration process only outputs routes that use a specified must-use mode
at some point in the trip. The process enumerates routes if at least one line in the bundle
uses the specified mode. The route-evaluation process eliminates routes that do not use
the specified transit mode.
Public Transport Program > Theory > Route-enumeration process > Modified route enumeration process

Modified route enumeration process

Under certain circumstances, small variations in the input network (such as link travel
time) can yield noticeable differences in the enumerated route sets and skims. Public
Transport features a modified enumeration process, available with the MODIRE
keyword (under PARAMATERS).
When small link travel time variations are introduced in the input network, M ODIRE
increases the likelihood that the same leg will remain at the top of the leg bundle, and be
chosen as the cheapest-cost leg. As such, the same route sets are more likely to be
enumerated over small variations of the input network.
Public Transport Program > Theory > Route-evaluation process

Route-evaluation process
The route-evaluation process calculates the “probability of use” for each of the
enumerated routes between zone pairs.
The process discards enumerated routes that fail to meet certain criteria, such as routes
with a probability of use less than the minimum specified by CHOICECUT . Before
computing probabilities, the process removes routes that alight and reboard the same
service.
See “Generalized cost” on page 936 for a description of the trip cost used in route
evaluation.
The remainder of this topic presents:
• Methodology of route evaluation

• Deriving cost used

• Models applied at decision points

Public Transport Program > Theory > Route-evaluation process > Methodology of route evaluation

Methodology of route evaluation

The route-evaluation process uses a simple tree structure to represent the possible
routes from an origin to a destination. (The process compresses data for efficiency.)
Starting at the origin, passengers might use one or more access legs (first-level
branches). At a stop, passengers choose between one or more transit alternatives for
the next stage of the trip. One or more second-level branches linked to the first-level
branch represent the available choices. Passengers continue, making choices from
additional branches, until reaching their destination. All routes arrive at the same
destination, though they arrive via different branches.
If routes have a must-use mode, the route-evaluation process checks to ensure that all
routes satisfy the condition. (The route-enumeration process only ensures that at least
one line in a transit-leg bundle satisfies the condition.)
Like the calculation of hierarchic logit models, the route-evaluation process calculates
routes in two steps, passing through the data tree twice.
For multirouting models, the first pass starts at the destination zone and calculates the
conditional probabilities of each alternative at any decision point in the tree structure.
(Trips arriving at the node may proceed towards the destination along any of the
alternative next-level branches. Conditional probabilities define what proportion of the
trips arriving at a node proceed along each alternative branch.) The second pass starts
at the origin, and calculates the probability of choosing each discrete route. This is
simply the product of all conditional probabilities along the route.
For best-path models, the process uses the two-pass algorithm, but assigns all demand
at any decision point to the cheapest alternative.
The expected (generalized) cost to destination is the cost along a discrete route.
Because demand along a discrete route is not divided among alternatives, the
composite cost obtained from skimming is identical to the route’s generalized cost.
When the decision tree includes walking or alternative alighting choices, the process
selects the cheapest route to the destination and discards all other alternatives.
When making transit-line choices, the process uses the service-frequency model; the
process does not support the service-frequency-and-cost model. The calculations of the
service-frequency model are described in “Deriving cost used” on page 967, “Models
applied at decision points” on page 969, and “SFM and SFCM examples” on page 975.
For multirouting models, the process allocates routes assuming “all reasonable lines
forward from a node” (as with multirouting), but for best-path models, the process
allocates specific routes.
By default, the process computes service-frequency-model calculations for identical-
mode lines in a transit-leg bundle. However, when FREQBYM ODE is set to F, the
calculations consider all lines in a transit-leg bundle, without separating by mode.
For each route forward, the process computes the expected cost to destination. The
process identifies the cheapest transit-leg bundle/mode combination (or transit-leg
bundle when FREQBYM ODE is set to F) and allocates all demand to that route forward
towards the destination.
Public Transport Program > Theory > Route-evaluation process > Deriving cost used

Deriving cost used

The route-evaluation process computes a single expected cost to destination (ECD)
from any choice or decision point in a trip to the destination. Often called composite cost,
the process uses this generalized cost for calculating the probability that passengers will
use alternative routes.
Adding new services or improving existing services does not increase the cost—
improving service enhances passenger utility.
At points close to the destination, the costs are usually simple. For example, at the start
of the egress leg, the cost of the leg is the cost to reach the destination.
At points further from the destination, where there are alternative routes, the process
combines the costs to form a single value for the expected cost to destination from a
single point.
For multileg trips, the process computes the expected cost to the destination for each
leg, working away from the destination. Computed at decision points using the
composite-cost formula, the cost includes walk, transit, and wait times.
At choices between walking and alighting transit, the process uses logit models. The
logit composite cost formula combines costs, producing a single value that represents
the set of alternatives:

Where:

C(comp) is the composite cost

λ
is a scale parameter which reflects the
travelers sensitivity to cost differences

ECDalt is the expected (generalized) cost to

destination via a particular alternative

At choices between transit alternatives, the process computes the cost to the destination
by adding the cost of the transit leg (including boarding and transfer penalties) and the
expected cost to the destination from the end of the transit leg. Then, the process
combines the values for the transit alternatives into a single value for the expected cost
from the node to the destination. This is calculated as the average of the costs
associated with each alternative (weighted by the probability of passengers taking the
alternative).
In calculating the transit element of the expected cost to destination, the process applies
an additional condition to ensure that adding (or improving) services does not increase
costs. Specifically, the process examines each service operating between a pair of
boarding and alighting points and includes the service if the resulting reduction in wait
time exceeds the resulting increase in travel time. The process ensures that the
expected time to the destination from the boarding node improves when a service is
included in the set of attractive alternatives. This set of services is known as the basic
choice set.
Public Transport Program > Theory > Route-evaluation process > Models applied at decision points

Models applied at decision points

This section describes the mathematical models that calculate the conditional
probabilities for choices made at a route’s decision points. Models are available for
cases where there are:
• Walk choices

• Transit choices

• Alternative alighting choices

• Opportunities for transfer

Public Transport Program > Theory > Route-evaluation process > Models applied at decision points > Walk choices

W alk cho ices

The route-evaluation process applies the walk-choice model when passengers have
alternative walk choices available. For example, when passengers leave the origin or
alight from a service, they might walk to their destination, board a different line at that
stop, or walk to another stop for the next transit leg.
This model has a logit structure:

Where:

P(walk is the probability of walking to boarding

to i) stop i

λ
is the scaling factor for the model
(LAMBDAW)

CWi is the walk (generalized) cost to the

boarding stop i

α is the cost weighting factor (between 0

and 1), specified by ALPHA. A value of
1 indicates that the walk and onward
costs have equal weight; lower values
indicate that the walk cost has more
influence than onward cost in the
traveller’s choice. For example, a
traveller’s willingness to walk may
relate to familiarity with the network.

ECDi is the expected (generalized) cost to

destination from i.

ECDj is the expected (generalized) cost to

destination from j.

Composite cost adjustment for ALPHA

The difference between the average and composite cost values, calculated as part of
any logit model, represents the value of choice, or the benefit travelers gain from
choosing between available alternatives.
When the ALPHA value that the walk-choice model uses is less than 1.0, the cost from
the end of the walk leg to the destination is discounted. The composite-cost
specification, shown above, represents the true cost to the destination (or trip cost), and
has a different numeric value from the discounted form.
To adjust for an ALPHA value less than 1.0, the process estimates a composite cost
consistent with the nondiscounted cost to the destination. First, the process uses ALPHA
to calculate the value of choice for the walk-choice model. Next, the process subtracts
this value of choice from the average cost (evaluated with ALPHA set to 1.0) to estimate
the nondiscounted (true) composite cost.
Impact of LAMBDAW

The scaling factor LAMBDAW controls the shape of the logit curve used to allocate
passengers to alternatives at each decision point. Large the scaling factors produce a
smaller spread of trips between alternatives—that is, more trips are allocated to the best
route. Conversely, low scaling factors produce trips spread over a wider range of
alternatives.

The X-axis shows the difference between the time by service i, ECDi, and the time by
the best service, ECDbest. The Y-axis shows the proportion of trips allocated to the
longer choice when a binary choice is available. The diagram plots three different values
for the scaling factor: 0.2, 0.5, and 1. The curve for LAMBDAW = 0.5 shows that a
choice five minutes longer than the best would be allocated 7.6% of the total trips. With a
scaling factor of 0.2, the longer route gets 26.9% of trips, but with a scaling factor of 1.0,
the longer route gets only 0.67% of trips. Thus, longer routes get a larger share of the
trips as the scaling factor is reduced.
Public Transport Program > Theory > Route-evaluation process > Models applied at decision points > Transit choices

Transit cho ices

Two models are available to allocate passengers to the transit choices available at a
stop: the service-frequency model (SFM) and the service-frequency-and-cost model
(SFCM). SFM considers only service frequency while SFCM also considers the cost to
the destination. See “SFM and SFCM examples” on page 975 for examples that show
how the two models treat transit choices at a stop.
Service-frequency model

Applied at stops with a basic set of transit choices, the service-frequency model
calculates the conditional probabilities of the individual lines in proportion to their
frequency. The model is equivalent to travelers who arrive randomly without knowledge
of the timetables and take the first reasonable service forward from the node.

where:

P(use line l) is the probability of using line l.

Frequency(line is the frequency of line l (in

l) services per hour).

Frequency(line is the frequency of line k (in

k) services per hour).

Service-frequency-and-cost model

The service-frequency-and-cost model is an extension of the service-frequency model.

The model assumes that travellers have knowledge of the travel time to the destination
associated with each of the alternative routes, and that the traveller is less willing to use
slower alternatives. This model defines its own set of transit choices, which may be
different from the basic choice set described in “Deriving cost used” on page 967.
To define a set of transit choices, the model selects the line with lowest expected cost to
the destination. Next, the model considers the next fastest line. If that line passes the
validity test, the model adds the line to the set of selected lines and repeats the process,
considering the next fastest line. Once a line fails the validity test, the process terminates
and the model uses the set of lines currently selected as possible routes to the
destination.
The validity test computes the line’s “excess time” — the difference between its time to
destination and the average value for the lines already selected (excluding wait time at
the stop). The test compares the line’s excess time to the expected cost of waiting
(which is based on the headway of the combined services already selected, and any
wait factors):
• If the excess time has a value of zero (that is, the line is no slower than those already
selected), then the line is always a valid choice.

• If the excess time is more than the expected cost of waiting, then the line is not valid;
travellers are better off ignoring this line and waiting for the next service from the selected
set.

• If the excess time is greater than zero but no more than the expected cost of waiting, the
line is valid some of the time. Specifically, excess time divided by the cost of waiting
defines the proportion of time that travellers are better off ignoring the line. Therefore, one
minus this proportion defines the probability of using the line when its service arrives at the
stop.

As the probability of use varies between lines, the frequency of the combined services
takes account of probability of use, as follows:

where:

P(use l) is the probability of using

line l when a service is at
the stop.

Frequency(line l) is the frequency of the line

l (in services per hour).

Frequency(combined) is the combined frequency

of a set of selected lines
(in services per hour).

During loading, the proportion of demand using a particular line is given by:
Public Transport Program > Theory > Route-evaluation process > Models applied at decision points > Alternative alighting
choices

Alternative alighting cho ices

The route-evaluation process applies the alternative-alighting model when a line has
two or more valid alighting points. This model has a logit structure similar to the walk-
choice model:

where:

P(alight is the probability of alighting at stop i.

at i)

λ
is the scaling factor for the model
(LAMBDAA).
NOTE: LAMBDAA affects the choice of
alighting points just as LAMBDAW
affects walk choices. For an example,
see “Impact of the different values of
scaling factor LAMBDAW” on page 971.

ECDi is the expected (generalized) cost to

destination via alternative alighting point
i.

ECDj is the expected (generalized) cost to

destination via alternative alighting point
j.
Public Transport Program > Theory > Route-evaluation process > Models applied at decision points > Opportunities for
transfer

Oppo rtunities fo r transfer

At transfer points between transit services, the route-evaluation process applies a

combination of models. First, the walk-choice model allocates demand between true
walk alternatives and an imaginary alternative that represents the transit services
available at the node. Next, the service-frequency model allocates the transit demand to
the various services at the stop.
Public Transport Program > Theory > SFM and SFCM examples

SFM and SFCM examples

This section provides examples of the service-frequency model and the service-
frequency-and-cost model:
• Example of the service-frequency model

• Example of the service-frequency-and-cost model

Public Transport Program > Theory > SFM and SFCM examples > Example of the service-frequency model

Example of the service-frequency model

This example shows:
• Choices available

• Results of the service frequency model

Public Transport Program > Theory > SFM and SFCM examples > Example of the service-frequency model > Choices
available

Cho ices available

(6) (7) (8)

(4) (5) (9)
(1) (2) (3) Cum A v e ra g e T ra v e l
Cum W a it T ra v e l T ra v e l + W a it Inc lud e
Line T ra v e lT ime Fre q ue nc y Fre q ue nc y T ime T ime T ime T ime s Line

1 20 5 5 12.0 100 20 32.0 Y

2 21 6 11 5.455 226 20.545 26.0 Y

3 22 2 13 4.615 270 20.769 25.385 Y

4 24 1 14 4.286 294 21 25.286 Y

5 26 1 15 4.0 320 21.333 25.333 N

Notes:
• Lines 1-4 are included in the basic choice set because, with the addition of each line, the
overall time to destination improves. Line 5 is excluded from the basic choice set because
including it makes the time to destination worse.

• A wait factor of 2 was used to weight the waiting times.

• Column (5) = 60.0/(4) * 0.5 * Wait Factor

• Column (6) = (2)*(3), accumulated over lines

• Column (7) = (6)/(4)

• Column (8) = (7)+(5)

Public Transport Program > Theory > SFM and SFCM examples > Example of the service-frequency model > Results of the
service frequency model

Results o f the service frequency m o del

(3)
(2) (4)
(1) Cum
Line Fre q ue nc y P ro p o rtio n
Line Fre q ue nc y a t S to p o f T rip s

1 5 5 0.357

2 6 11 0.429

3 2 13 0.143

4 1 14 0.0714

5 1 - 0.0

Notes:
Column(4) = (2)/cumulative frequency at stop
Public Transport Program > Theory > SFM and SFCM examples > Example of the service-frequency-and-cost model

Example of the service-frequency-and-cost model

This example shows:
• Choice set

• Results of the service frequency & cost model

Public Transport Program > Theory > SFM and SFCM examples > Example of the service-frequency-and-cost model >
Choice set

Cho ice set

(4 ) (5 ) (6 ) (1 0 )
A v e ra g e E xce ss Wa it (7 ) (9 ) A v e ra g e
t ra v e l t ra v e l t ime P ro p o rt io n (8 ) Wa it t ra v e l
(2 ) (3 ) t ime t ime w it h o u t o f t ime Cu m t ime t ime
(1 ) L in e Tra v e l e xclu d in g ov er t h is w h e n lin e e f f e ct iv e in clu d in g in clu d in g
L in e f re q u e n cy t ime t h is lin e a v e ra g e lin e u se d f re q u e n cy t h is lin e t h is lin e

1 5 20 - - - 1 5 12 20

2 6 21 20 1 12 0.917 10.500 5.714 20.52

3 2 22 20.52 1.48 5.714 0.742 11.983 5.007 20.707

4 1 24 20.707 3.293 5.007 0.342 12.326 4.868 20.798

5 1 26 20.798 5.202 4.868 0 - -

Notes:
• Example uses a wait factor of 2 to weight the waiting times.

• Column (4) = (10) from the previous line

• Column (5) = (3) - (4)

• Column (6) = (9) from the previous line

• Column (7) = 1-MIN( (5)/(6)),1)

• Column (8) = (2)*(7), accumulated over lines

• Column (9) = 60.0/(8) * 0.5 * Wait Factor

• Column (10) = ((2)*(3)*(7), accumulated over lines) / (8)

Public Transport Program > Theory > SFM and SFCM examples > Example of the service-frequency-and-cost model >
Results of the service frequency & cost model

Results o f the service frequency & co st m o del

(3) (4)
(2) (5)
(1) E ffe c tiv e Cum
Line fre q ue nc y fre q ue nc y P ro p o rtio n
Line fre q ue nc y a t s to p a t s to p o f trip s

1 5 5 5 0.406

2 6 5.500 10.500 0.446

3 2 1.483 11.983 0.120

4 1 0.343 12.326 0.028

5 1 - - -

Notes:
• Column (3) = (2) * Proportion of time when line used (values are listed in Column (7) in the
Choice set table above)

• Column (4) = (3), accumulated over lines

• Column(5) = (3)/cumulative frequency at stop

Public Transport Program > Theory > Skimming process

Skimming process
The skimming process extracts the cost of a public transport trip into a zone-to-zone
matrix.
Because the Public Transport program finds multiple routes between zone pairs, the
program can provide several skims, suitable for different purposes:
• Composite-cost skim — Supports scheme evaluation and demand modeling

• Value-of-choice skim — Indicates the choice available in the public transport system

• Average skims — Supports model validation, operational statistics, revenue calculation

• Best-trip skim — Indicates actual trip cost

Available skims and the processes for extracting them are described in “Skimming (level
of service)” on page 720 and “Skim functions — quick reference” on page 732.
Public Transport Program > Theory > Skimming process > Composite-cost skim

Composite-cost skim
For each zone pair, the composite-cost skim computes the composite cost, or the total
utility of the trip including the choices available to the traveller.
The route-evaluation process uses composite costs, also referred to as the expected
cost to destination (see “Deriving cost used” on page 967 for a description of how they
are derived).
To enable you to model demand or evaluate schemes, the skim ensures that adding
new routes or improving services does not lead to an increase in the cost.
The skim calculates composite costs from each decision point in the trip to the
destination. The calculation varies with the type of choice:
• Walk choices

• Transit choices

• Alternative alighting points

• Walk and transit choices

Public Transport Program > Theory > Skimming process > Value-of-choice skim

Value-of-choice skim
For each zone pair, the value-of-choice skim computes the value of choice, a measure
of the extent to which travellers can choose between alternative routes. Higher values
indicate travellers can choose between routes of similar costs, whereas lower values
indicate a lack of route choice, or choices where the lesser alternatives are considerably
more expensive than the best route.
The value of choice provides a measure of the resilience or robustness of the public
transport system. With more low-cost choices, the system can continue functioning
following the failure of one or more components.
The value-of-choice skim is equivalent to the difference between the composite-cost
skim and the average-generalized-cost skim.
Public Transport Program > Theory > Skimming process > Average skims

Average skims
Average skims compute the costs a typical traveller incurs while making a public
transport trip. You can extract average skims for all components of the trip. There are
three broad areas:
• Time
m
Walk (nontransit)
m
Wait
m
In-vehicle

• Inconvenience
m
Boarding
m
Transfer

• Cost
m
Fare

Because multiple routes might connect zone pairs, average skims weighting each route
according to its probability of use.
Average skims compute component costs at network and route-set level. Within each
route set, average skims can compute costs other than wait time by mode.
Several average skims can compute either actual values—true measures of the cost—or
perceived values—the cost’s contribution to generalized cost (usually a product of the
cost and a weighting coefficient).
Average skims are appropriate for model validation and skimming operational statistics,
such as passenger miles, hours, and revenue.
Public Transport Program > Theory > Skimming process > Best-trip skim

Best-trip skim
For each zone pair, the best-trip skim computes the actual time for the best route (that is,
the time if travellers make the best choice at every decision point).
Because the skim uses actual values for all trip components, the skim does not reflect
traveller behavior, and is, therefore, inappropriate for demand modeling.
The skim bases the wait time and the transit-leg time on the lowest expected values.
The skim computes wait times from the appropriate wait curve, using the combined
frequencies of all acceptable lines from the node towards the destination. The skim
computes transit-leg times from the fastest line in the leg-bundles used.

NOTE: At present, walk(nontransit) legs have only one time attribute, the one used to
construct them (perceived time). See “Walk time (nontransit time)” on page 937.
Public Transport Program > Theory > Loading process

Loading process
The loading process (assignment) allocates trips, either computed or from the input trip
matrix, to services (transit lines) and nontransit legs. The loading process uses routing
and travel time information obtained from the route-evaluation process.
The loading process considers one origin-destination zone pair at a time. The process
assigns the zone pair’s trips to the available routes according to each route’s probability
of use, calculated during the route-evaluation process.
For example, consider the reports of enumerated and evaluated routes between zones
1 and 3.

E nume ra te d ro ute s b e twe e n zo ne s 1 a nd 3

REnum Route(s) from Origin 1 to
Destination 3
1 -> 773
773 -> 764 -> 764 lines GMB1-24MB
764 -> 751 -> 751 lines PLB1-113B
PLB129B PLB127A
751 -> 749 -> 3 lines GMB1-2B
Cost=27.668
1 -> 773
773 -> 759 -> 759 lines GMB1-24MB
759 -> 875 -> 875 lines RES34R
875 -> 749 -> 3 lines GMB1-2B
Cost=34.028
1 -> 2052
2052 -> 2004 -> 875 lines ISL-DN
875 -> 749 -> 3 lines GMB1-2B
Cost=31.84

E v a lua te d ro ute s b e twe e n zo ne s 1 a nd 3

REval Route(s) from Origin 1 to
Destination 3
1 -> 773
773 -> 764 -> 764 lines GMB1-24MB
764 -> 751 -> 751 lines PLB1-113B
PLB129B PLB127A
751 -> 749 -> 3 lines GMB1-2B
Cost= 23.668 Probability=0.631438
1 -> 773
773 -> 759 -> 759 lines GMB1-24MB
759 -> 875 -> 875 lines RES34R
875 -> 749 -> 3 lines GMB1-2B
Cost= 28.628 Probability=0.142594
1 -> 2052
2052 -> 2004 -> 875 lines ISL-DN
875 -> 749 -> 3 lines GMB1-2B
Cost= 30.04 Probability=0.225968

The first report shows three bundles of enumerated routes from zone 1 to zone 3. All
routes meet the evaluation criteria; none are eliminated. The second report lists the
routes with their probability of use. The enumerated-routes report shows used costs.
However, the evaluated-routes report shows the average cost for the route bundle, not
the composite costs used to calculate the probability of use.
The loading process considers two walk choices from zone 1: to nodes 773 and 2052.
The route-evaluation process determined that the probability of going to node 773 is
0.774032, while the probability of going to node 2052 is 0.225968, reflecting the shorter
time via node 773. The loading process splits trips from zone 1 to zone 3 in this
proportion and saves the trips for the nontransit (access) legs:
• At node 773, there is a single transit service, GMB1-24B; all trips arriving at node 773
board this service. There are two alighting points: nodes 764 and 759. The time via 764 is
less than the time via 759. Thus the probability of using node 764 is 0.631438 and the
probability of using node 759 is 0.142594. The loading process splits trips at node 773
between the two alighting points and saves the trips for the two transit legs.
m
At 764, the loading process assigns arriving trips to lines PLB1-113B, PLB129B, and
PLB127A in proportion to their relative frequencies for trips to node 751. From node
751, travelers go to zone 3 via node 749 and line GMB1-2B. The process saves the
number of trips assigned to the four transit legs for each leg.
m
At node 759, the loading process assigns arriving trips to transit lines RES34R and
GMB1-2B for trips to nodes 875 and 749 before ending at zone 3.

• At node 2052, the loading process assigns travelers to transit line ISL-DN for the trip to
node 875, and then to transit line GMB1-2B for the trip to node 749 before ending at zone
3.

All trips from zone 1 to 3 use line GMB1-2B as the last transit leg in the trip, and alight at
node 749 where they walk to zone 3. These are saved for the nontransit (egress) leg
749-3.
The loading process is complete after assigning trips between all (selected) origin-
destination zone pairs, and computing the total trips using transit and nontransit legs on
the underlying network links.
Public Transport Program > Theory > Fares

Fares
This section describes how to model fares in the Public Transport program. Topics
include:
• Overview

• Trip length

• Multiple fare systems

• Boarding and transfer costs

• Trip costs

• Fare zones

• Examples
Public Transport Program > Theory > Fares > Overview

Overview
Fares are a fundamental element of a public transport trip. Therefore, it is important to
incorporate fares fully into the Public Transport modeling process.
To incorporate fares, the Public Transport program:
• Considers fares in the route choice

• Skims average fares for each origin-destination zone pair

• Calculates and reports revenue

Fares do not always significantly impact route choice. To reduce run times, you might
exclude fares from the route-evaluation process and skim and calculate revenue from
the evaluated routes.
The Public Transport program must accurately represent the fare systems that
passengers face. The Public Transport program provides a framework which you can
use to directly represent or approximate most fare systems. In fact, you can represent
different types of fare systems within a single public transport network.
You can specify fare systems and value of time by user class. You might do this to use
readily available ticket type data to segment and model demand by ticket type.
Transit legs are the basic unit the program uses to calculate fares. A transit leg is one
part of a trip, from a boarding point to an alighting point, that uses a single transport line.
The program assigns each line to a fare system, either directly or through its mode or
operator.
The program calculates fare for a single leg of the trip. If multiple consecutive legs have
the same fare system, the program assumes integrated or through ticketing and
calculates fare for that sequence of legs.
To model fares, the Public Transport program requires a program-wide “fare system”
that describes each transit line’s individual fare system, its data requirements, and how it
interfaces with other lines.
You define fare systems with the FARESYSTEM control statement and input fare systems
with the FILEI FAREI file. You define fare system attributes with FARESYSTEM keywords and
subkeywords:
• Unique numeric and character identifiers (NUMBER, NAME, LONGNAME)

• Unit of measure for trip length, such as distance, number of fare zones crossed, or
boarding-alighting fare zones. (STRUCTURE, with possible values: FLAT, DISTANCE, HILOW,
COUNT, FROMTO, or ACCUMULATE)
• Boarding costs at the initial boarding and subsequent transfers, and the cost of transferring
between fare systems (IBOARDFARE, FAREFROMFS )

• Trip cost, which may be specified with a coefficient per unit measure of the trip, a table, or
matrix (UNITFARE, FARETABLE, FAREMATRIX)

• Rules for computing costs when transferring to the same fare system and interpreting fare
tables (SAME, INTERPOLATE)

Data requirements for fare systems depend upon the unit of trip measure (specified with
STRUCTURE) and the method for specifying trip costs (specified with UNITFARE, FARETABLE,
and FAREMATRIX). Requirements can vary from minimal to substantial. The following
table provides a quick reference to the various fare systems and their data requirements.

S T R U CT U R E FLA T D IS T A N CE H ILOW COU N T FR OMT O A CCU MU LA T E

IBOARDFARE Required Optional Permissible Permissible 3 Permissible Permissible

FAREFROMFS Optional Optional Optional Optional Optional Optional

UNITFARE NA Optional1 NA NA NA NA

FARETABLE NA Optional2 NA Required NA Required

FAREMATRIX NA NA Required NA Required NA

FAREZONE NA NA Required Required Required Required

1,2 One of the two items is required.

3 Permitted but use is questionable, as it could be included in the FAREMATRIX.

The program assigns fare systems to transit lines indirectly through the line’s mode and
operator with the FACTORS FARESYSTEM keyword or directly with the LINE control
statement. When modeling fares, each line must have an assigned fare system.
Include fares in the route-evaluation process by setting PARAMETERS FARE to T. Skim
fares, whether or not they are included in route-evaluation, by selecting skimming
functions FAREA and FAREP in the SKIMIJ phase.
Public Transport Program > Theory > Fares > Trip length

T rip length
The units for measuring trip-length is a key attribute of the fare system. Trip-length units
might be based on legs, actual distance, or fare zones. Fare zones are single nodes or
groups of nodes.
You specify the trip-length unit with the FARESYSTEM keyword STRUCTURE. There are six
possible values. Each value results in a different method for calculating trip length and
fare.
D e s c rip tio n o f trip -le ng th units

V a lue o f Me tho d fo r c a lc ula ting trip le ng th a nd

S T R U CT U R E fa re

FLAT Trip length not used for fare calculation.

Fares derived by leg using the boarding and
transfer costs specified with IBOARDFARE and
FAREFROMFS.

DISTANCE Trip length measured as in-vehicle distance, in

user-specified units.
Fares calculated by leg or for sets of
consecutive legs using the same fare system.
Fares based on:
• Boarding and transfer costs, specified
with IBOARDFARE and FAREFROMFS.

• Trip cost computed by multiplying in-

vehicle distance by UNITFARE.

• Trip cost obtained from the fare table

specified by FARETABLE. The value of
INTERPOLATE determines whether the
program uses linear interpolation or a
step function between coded points.

HILOW Trip length measured by the highest and

lowest fare-zones crossed.
Appropriate for an annular fare-zone structure.
Fares calculated by leg or for sets of
consecutive legs using the same fare system.
Fares based on:
• Boarding and transfer costs, specified
with IBOARDFARE and FAREFROMFS
(boarding costs are added to the fare
matrix)
• Trip cost, extracted from the fare matrix
specified with FAREMATRIX (rows
contain the lower fare zone, and columns
contain the higher fare zone)

COUNT Trip length measured by the number of fare

zones crossed plus 1 for the initial zone.
Best suited to a sequential zone system.
 Fares calculated by leg or for sets of
consecutive legs using the same fare system.
Fares based on:
• Boarding and transfer costs, specified
with IBOARDFARE and FAREFROMFS

• Trip cost, extracted from the fare table

specified with FARETABLE. In this case,
the program interpolates the fare table
as a step function.

FROMTO Trip length measured as function of the

boarding and alighting fare zones.
Best suited to a sequential zone system.
Fares calculated by leg or for sets of
consecutive legs using the same fare system.
Fares based on:
• Boarding and transfer costs, specified
with IBOARDFARE and FAREFROMFS
(boarding costs are added to the fare
matrix).
• Trip cost, extracted from the fare matrix
specified with FAREMATRIX (rows
contain the lower fare zone, and columns
contain the higher fare zone)

ACCUMULATE Trip length measured by accumulating fares

associated with each fare zone traversed.
Differs from COUNT, where program counts
the number of fare zones traversed to compute
fare.
Best suited to a sequential zone system.
Fares calculated by leg or for sets of
consecutive legs using the same fare system.
Fares based on:
• Boarding and transfer costs, specified
with IBOARDFARE and FAREFROMFS

• Trip cost, extracted from the fare table

specified with FARETABLE. The fare
table has a fare for each fare zone in the
system.
Public Transport Program > Theory > Fares > Multiple fare systems

Multiple fare systems

For public transport networks with multiple fare systems, use the SAME subkeyword to
specify whether the program treats consecutive legs in the same fare system as one leg
or as separate legs when calculating fares.
If two consecutive legs of a trip use different fare systems, the program always
calculates the fare separately for each leg.
Public Transport Program > Theory > Fares > Boarding and transfer costs

Boarding and transfer costs

Boarding and transfer costs are key attributes of the fare system. You specify boarding
and transfer costs with FARESYSTEM keywords:
• IBOARDFARE —
Fare incurred upon boarding the first transit leg of a trip. See “IBOARDFARE”
on page 809.

• — Fare incurred when transferring from lines using other defined fare systems.
FAREFROMFS
See “FAREFROMFS” on page 805.
Public Transport Program > Theory > Fares > Trip costs

T rip costs
Trip cost is a key attribute of the fare system. The program determines trip cost using
one of three methods:
• UNITFARE —Coefficient used to calculate fares. Only available when STRUCTURE is DISTANCE.
To obtain fare, the program multiplies UNITFARE by in-vehicle distance of a leg or a sequence
of consecutive legs using the same fare system.

• FARETABLE — Table of fares. Used when STRUCTURE is DISTANCE, COUNT, or

ACCUMULATE. Define FARETABLE with a list of paired X and Y coordinates, where X is the
trip length and Y is the fare.
See “FARETABLE” on page 807 for more information about coding FARETABLE.
Some graphic examples follow.
• FAREMATRIX — Matrix of fares. Used when STRUCTURE is HILOW or FROMTO. Input matrices
with FILEI FAREMATI in either standard Cube Voyager binary matrix format or as text
records. See FAREMATRIX for information about coding fare matrices. To report on fare
matrices, use the REPORT keyword FAREMATI.

You code fares in monetary units. The program converts fares to generalized costs
using the FACTORS keyword VALUEOFTIM E .
Public Transport Program > Theory > Fares > Fare zones

Fare zones
Fare systems that have the STRUCTURE set to HILOW, FROMTO, COUNT, or
ACCUMULATE require fare zones. Fare zones are either groups of nodes or single
nodes.
A public transport network might have multiple fare-zone schemes, but a fare system
must have only one zone scheme. Therefore, a node can be in only one fare zone.
The HILOW structure requires an annular fare zone system while the other structures
require sequential fare zones.

n T o identify and code fare zones for fare systems with a FROMT O,
COUNT , or ACCUMULAT E structure

1. Display the network in Cube.

2. Add a new node attribute to store the fare zone, such as FAREZONE.
a. From the Node menu, point to Attribute, and choose Add.
b. In the Add Note Network Variable dialog box, type FAREZONE and click OK.

3. Use the Polygon menu to define fare zones, one at a time

4. Assign a number to the new fare-zone attribute of the nodes within the polygon

n T o identify and code fare zones for fare systems with a HILOW structure

1. Display the network in Cube.

2. Add a new node attribute to store the fare zone, such as FAREZONE.
a. From the Node menu, point to Attribute, and choose Add.
b. In the Add Note Network Variable dialog box, type FAREZONE and click OK.
3. Associate the number of the outermost fare zone to the new fare-zone attribute of all
nodes.

4. Use the Polygon menu to define a ring separating the outermost fare zone from the other
zones.

5. Assign the number of the penultimate fare zone to the new fare-zone attribute of the nodes
within the polygon

6. Repeat the last two steps until all fare zones have been completed.
Public Transport Program > Theory > Fares > Examples

Examples
This section shows how fares are calculated for a four-leg trip using different fare
models, individually and in combination.

B o a rd ing & In-v e hic le

a lig hting d is ta nc e
Le g p o ints Mo d e (mile s )

1 A-B 1=British Rail 10

2 B-C 2=Underground 3
Piccadilly

3 C-D 2=Underground 2
Bakerloo

4 D-E 3=Bus 1
Public Transport Program > Theory > Fares > Examples > Example 1: FLAT fare system

Exam ple 1: FLAT fare system

FARESYSTEM NUMBER=1, NAME=Flat Fare British Rail’, STRUCTURE=FLAT, IBOARDFARE=100,
FAREFROMFS[1]=0, 100
FARESYSTEM NUMBER=2, NAME=Flat Fare Underground+Bus’, STRUCTURE=FLAT, IBOARDFARE=50,
FAREFROMFS[1]=75, 0
FACTOR FARESYSTEM=1, MODE=1
FACTOR FARESYSTEM=2, MODE=2,3

FARE(A-E) = 175 pence, which is the sum of fares for each leg, calculated as:
Leg A-B = 100 {IBOARDFARE for A-B} +
Leg B-C = 75 {FAREFROMFS[1] for B-C, for transferring from FARESYSTEM 1 to 2}
Leg C-D = 0 {FAREFROMFS[2] for C-D, for transferring from FARESYSTEM 2 to 2}
Leg D-E = 0 {FAREFROMFS[2] for D-E for transferring from FARESYSTEM 2 to 2}
Public Transport Program > Theory > Fares > Examples > Example 2: DISTANCE fare system

Exam ple 2: DISTANCE fare system

The trip uses three fare models, all with STRUCTURE set to DISTANCE but with different
unit cost for trip length.
FARESYSTEM NUMBER=1, NAME=’Distance British Rail’, STRUCTURE=DISTANCE,
IBOARDFARE=100, FAREFROMFS[1]=0, 100, 100, FARETABLE=1.0,0.75, 5.0,2.50, 10.0,3.50
FARESYSTEM NUMBER=2, NAME=’Distance Underground’, STRUCTURE=DISTANCE,
SAME=CUMULATIVE, IBOARDFARE=100, FAREFROMFS[1]=100, 0, 100, UNITFARE=60
FARESYSTEM NUMBER=3, NAME=’Distance Bus’, STRUCTURE=DISTANCE, IBOARDFARE=50,
FAREFROMFS[1]=50, 50, 0, UNITFARE=50
FACTOR FARESYSTEM=1, MODE=1
FACTOR FARESYSTEM=2, MODE=2
FACTOR FARESYSTEM=3, MODE=3

FARE(A-E) = 950 pence, which is the sum of fares for trip legs, calculated as:
Leg A-B = 100 + 350 (IBOARDFARE + trip cost)
Legs B-D = 100 + (5*60) (FAREFROMFS[1] + total distance * UNITFARE)
Leg D-E = 50 + (1*50) (FAREFROMFS[2] + total distance * UNITFARE)

NOTE: Where two consecutive legs have the same fare system, the fare can be
calculated for each leg separately or cumulatively, depending upon the setting of SAME.
In this example, legs B-C and C-D have the same fare system and SAME is set to
CUMULATIVE, so the fare is calculated for B-D. SAME has no effect in this case
because UNITFARE is used rather than FARETABLE.

There is no cost for transferring from fare type 2 to another leg using the same fare type.
Public Transport Program > Theory > Fares > Examples > Example 3: FROMTO fare system

Exam ple 3: FROM TO fare system

FARESYSTEM NUMBER=1, NAME=’Trip Based’, STRUCTURE=FROMTO, FAREMATRIX=FMI.1.5,
FAREZONES=NI.FAREZONE
FACTOR FARESYSTEM=1, MODE=1-3

FARE(A-E) = 350 pence,

The node variable, NI.FAREZONE, defines the fare zones for stops A through E, and
the program extracts the fare from fare matrix number 5, input on FAREMATI[1], row
NI.FAREZONE(A) and column NI.FAREZONE(E).
There are no boarding costs or costs for transferring between the same fare system.
Public Transport Program > Theory > Fares > Examples > Example 4: COMBINATION of FROMTO and DISTANCE fare
systems

Exam ple 4: COM BINATION o f FROM TO and DISTANCE fare system s

The two FROMTO fare systems use different FARETABLE values and an incentive is
offered to interchange between fare system 1 and 2 and vice versa.
FARESYSTEM NUMBER=1, NAME=’British Rail’, STRUCTURE=FROMTO,
FAREMATRIX=FMI.2.BritRail, FAREFROMFS[1]=0, -25, 0, FAREZONES=NI.FAREZONE
FARESYSTEM NUMBER=2, NAME=’Underground’, STRUCTURE=FROMTO, SAME=CUMULATIVE,
FAREMATRIX=FMI.1.UndGrnd, FAREFROMFS[1]=-25, 0, 0, FAREZONES=NI.FAREZONE
FARESYSTEM NUMBER=3, NAME=’Bus’, STRUCTURE=DISTANCE, UNITFARE=50, IBOARDFARE=50,
FAREFROMFS[1]=50, 50, 0

FARE (A-E) = 525 pence, which is the sum of fares for legs, calculated as:
Leg A-B = 250 (FAREMATRIX FMI.2.BritRail, row NI.FAREZONE(A), column NI.FAREZONE(B))
Leg B-D = -25+200 (FAREFROMFS[1] and FAREMATRIX FMI.1.UndGrnd, row NI.FAREZONE(B),
column NI.FAREZONE(D))
Leg D-E = 50 + 1*50 (FAREFROMFS[2] + trip cost)
Public Transport Program > Theory > Crowding

Crowding
An iterative process, crowd modeling enables a public transport system’s capacity to
influence the system’s travel times and thus the routes found and their probability of use,
as calculated during route evaluation.
The Public Transport program supports two types of crowd models:
• Link-travel-time adjustment

• Wait-time adjustment

This section also discusses:

• Crowding process
Public Transport Program > Theory > Crowding > Link-travel-time adjustment

Link-travel-time adjustment
A link-travel-time adjustment models a passenger’s perception that travel time is more
onerous when standing (rather than sitting), or when in crowded vehicles. Specify this
adjustment with a “crowding factor.” The program multiplies the crowding factor by in-
vehicle time to determine the perceived “crowded in-vehicle time.”
For example, suppose a vehicle has a seating capacity of 40, crush capacity of 50, and
load distribution factor of 0.85 (standing occurs when more than 85% of 40—that is, 34
seats—are occupied). Once standing starts, the crowding factor might increase slowly
from 1.0 for the first few standing passengers, then more steeply once vehicle loading
exceeds 40.

The Public Transport program uses crowding curves. Derived from the crowd-factor
curve, crowding curves show utilization on the X‑axis. Utilization, the percentage of
standing places occupied, can vary between 0 and 100with the default option, but a user
control keyword (UTFLEX)
allows to specify crowding curves for values of Utilization beyond 100%. The
corresponding crowding curve is shown below.
Crowd factors are 1.0 in uncrowded conditions, and typically rise to values in the ranges
1.0 to 1.4 for seated passengers and 1.5 to 3.0 for standing passengers when the
vehicle is fully loaded with standing occurring.
The program calculates crowded link travel time as:

where:

Tc is the crowded link travel time

Tu is the link travel time (in uncrowded

conditions)

CCrvv,c is the crowd curve value (where the

(U) curve is specific to a vehicle type, v, and
a user class, c) for utilization U

U is the utilization measure (as a

percentage)

The utilization measure, U, is defined by the expression:

where:
P is the passenger demand (per hour).

SeatCap is the seating capacity (per hour) for

the line.

CrushCap is the crush capacity (per hour) for the

line; this is the total of seated and
standing capacities.

LDFv is the load distribution factor for the

vehicle type. As loads increase this is
the proportion of seats occupied when
standing starts to occur. It may be less
than 1.0, indicating that standing
occurs before all seats are used.
(Note: the LDF value specified in
commands is coded as the
corresponding percentage.)

With the default settings, the value of utilization is constrained with a minimum value of
0% (when no standing occurs) and an upper limit of 100% (when crush capacity is
exceeded). A user selected keyword (UTFLEX) allows to specify utilization values
beyond 100%.
If the values of seating capacity and crush capacity are identical for any line, then
utilization is 100% whenever demand exceeds the seating capacity, and 0% otherwise.
Public Transport Program > Theory > Crowding > Wait-time adjustment

Wait-time adjustment
The wait-time adjustment reflects the ability to board a service. In simple models (without
crowd modeling) travellers typically board the first service that arrives at a stop and goes
to the required alighting point. As loadings on services increase, this becomes less
realistic, as travellers will choose the first appropriate service that has available capacity.
Using measures of demand and available capacity, the wait-time adjustment computes
the probability of being able to board a service. With heavily loaded services, some
travellers will wait for the next service, incurring additional wait time at the boarding node.
Without crowding, the program assigns demand with the service-frequency model
(SFM), or service-frequency-and-cost model (SFCM). The wait-time adjustment
redistributes the initial SFM or SFCM loadings whenever any line does not have the
available capacity to take its assigned demand. The program reassigns this excess
demand to other lines with spare unused capacity; those travellers incur additional wait
time.
The additional wait time might make this route less attractive, resulting in diversion of
demand to other enumerated routes for the origin-destination pair.
If demand exceeds capacity and no alternative routes are available, then this transit leg
acts as a “bottleneck”—not all of the travel demand is able to use the service during the
modeled period. The demand remaining at the end of the modeled period would
discharge once peak travel volumes subside; those travelers experience additional
delays, which form a second component to the wait-time adjustment.
“Flow metering” handles the bottleneck effect and the inability of demand to pass
through that point. Flow metering removes the excess demand from later stages in the
trip; thus demand at any downstream point reflects the number of travellers who can
reach that point. For any origin-destination pair, the program can calculate the proportion
of flow-metered demand (that is, demand unable to reach its destination due to network
bottlenecks), and the number of trips affected.
Public Transport Program > Theory > Crowding > Crowding process

Crow ding process

The crowd modeling process uses the loaded demand from an iteration to provide
updated values for:
• Link travel times (which may vary by user class)

• Probability of being able to board a line at a particular stop

These calculations incorporate a degree of damping to help stabilize the resulting

assignments.
All damping factors work in the EMA type formula, i.e., X(new) = X(old) +
LINKDF/VOLDF/WAITDF *(X(calculated) – X(old)). Where X corresponds to crowding
factors, crowding volumes, capacity and demand averaging, for LINKDF, VOLDF,
WAITDF respectively. Higher damping factors implies higher weights to the most recent
(calculated in the current iteration) X values, whilst lower damping factors implies higher
weights for averaged X values from the previous iteration.
The crowding process is viewed as a stochastic assignment, and results are obtained
from the final iteration.
Crowded networks might cause instabilities in the loadings between iterations, as
demand switches toward less congested routes. In turn, those routes might become
more heavily loaded, and thus less attractive at the next iteration. These changes might
converge toward a solution, or might continue oscillating; oscillation is more likely in
highly overloaded networks. The service-frequency-and-cost model usually results in
better convergence than the service-frequency model because the route-choice
process is more responsive to changes in costs.
Four keywords can be used to impose automatic stopping criteria to this iterative
process (RMSESTOP, RMSECUTOFF, RDIFFSTOP and RDIFFCUTOFF). If the
stopping criteria are unset or not met, the program will stop at the iteration specified by
the ITERATIONS keyword.
The formulas used to calculate these iteration-by-iteration statistics are reported below:
Where:
C = Composite Cost
n = Current iteration number
ij = OD pair
u = User class
The crowding algorithm will run one extra iteration after the stopping criteria are met for
three consecutive iterations, and output the corresponding results. This behaviour (one
more step to stop) is due to the original design of the PT process, based on a predefined
maximum number of iterations as stopping criteria.
Due to the heuristic nature of the Public Transport crowding algorithm, this stopping
criteria that the program provides should not be considered a convergence measure.
Therefore, it is suggested that users also analyse the evolution of the assignment
algorithm iteration-by-iteration, using the statistics and measures provided by the other
available keywords (RDIFF, REPORTIJ, RMSE, SKIMS, STOP2STOP and TRACEIJ).
Public Transport Program > Using the Public Transport program

Using the Public Transport program

This section discusses useful information for using the Public Transport program. Topics
include:
• Estimating demand matrices

• Defining input and output files

• Linking Highway and Public Transport models

• Coding network times/speeds

• Generating nontransit access and egress legs

• Considering nontransit-only routes

Public Transport Program > Using the Public Transport program > Estimating demand matrices

Estimating demand matrices

You can use Cube Analyst to estimate public transport demand matrices. Cube Analyst
uses screenline count data to update a “prior” matrix. Confidence levels determine how
much each input influences the estimation process. See Cube Analyst Reference Guide
for detailed information about the methods used.
Matrix estimation requires an intercept file, which provides data on routes crossing the
defined screenlines for each origin-destination pair. A run of the Public Transport
program produces the intercept file.
Screenline data files specify the links that compose each screenline and contain
associated data, such as link counts and confidence levels. Confidence levels reflect
the accuracy of count data and affect the weighting during the estimation process. You
can create a screenline file with:
• Cube, or text-file editors, and read the file in to the Public Transport run

• Public Transport run, based on data values stored in the input network
Link variables in the input network contain the screenline number (zero if the link is
not part of a screenline), link count, and confidence level.
For a Public Transport run to produce matrix estimation data, the script must specify a
FILEO INTERCEPTO command, along with either a FILEI SCREENLINEI or a FILEO
SCREENLINEO command. Alternatively, the software may save just a screenline output file
without performing any route evaluation.
To configure the intercept file to contain only transit use of the links, or all demand (that
is, transit plus nontransit use of all links), use the MEUSESNT keyword on PARAMETERS and
FILEO SCREENLINEO commands.
Public Transport Program > Using the Public Transport program > Defining input and output files

Defining input and output files

You define input and output files for the Public Transport program with control
statements FILEI and FILEO. These are present in the main script file.
Use control statements to define input and output data items (that is, LINE, MODE,
OPERATOR, and NTLEGS). These are usually contained in files defined by FILEI and
FILEO, and not in the script file.

All control statements available in the Public Transport program are described in
“Control statements” on page 759. This section shows which files contain which data
items.

FILE I/ O File V a lid c o ntro l s ta te me nts

k e y wo rd d e s c rip tio n d e fining d a ta

FAREI Fare system FARESYSTEM

LINEI Lines LINE

NTLEGI Nontransit NT
leg

SYSTEMI Public MODE, OPERATOR,

transport VEHICLETYPE,
system WAITCRVDEF, and
CROWDCRVDEF

LINEO Lines LINE

NTLEGO Nontransit NT
leg
Public Transport Program > Using the Public Transport program > Linking Highway and Public Transport models

Linking Highway and Public Transport models

In studies that model both highway and transit demand, you can link the two models.
Transit vehicles travel through junctions and take some of the junction capacity. For
networks with congestion, a typical highway model estimates delays on links and at
junctions. Link travel times include link delays, and trip time also includes junction
delays. Junction delays can affect transit vehicles, though provisions like bus-only lanes
can reduce or eliminate such delays at particular locations.
Cube Voyager can export junction delay data from Highway program runs, and include
these delays in the run times of transit lines. However, because Highway assignment
does not support turn-based preloads, Cube Voyager cannot import transit-vehicle turn
volumes from Public Transport to Highway.
The Highway program can export delays for turning movements to a TURNPENO file.
The Public Transport program can then read this file. The Public Transport program
calculates a line’s travel times using TRANTIME (a global parameter that represents link
travel times), junction delays, link delay, and dwell time values. TRANTIME and junction
delays are network components, and delay and dwell time are line components.
When junction delays are included, transit-line run times are influenced by the highway
network’s congestion levels. To model bus-only lanes or other provisions designed to
reduce transit-line delay at junctions, you can limit the delay at a junction by defining a
link variable that specifies an upper limit for delay on the approach link to a junction.
LINE definitions can include RUNTIME, RT, or NNTIME keywords, which provide control
values. The program scales the line’s travel times up or down to match these control
values. You might use control values in base-year models to ensure that the line’s travel
time matches an expected value.
For forecast years, when you do not know the line’s travel time, you cannot code the
time as part of the line. Instead, the program determines travel times with an incremental
approach. The program calculates the line’s travel times for the base year, and
compares these times to the control values to generate scaling factors for the increase
or decrease in travel times. The program applies these factors and the forecast-year
junction delays to compute the line’s travel times in the forecast year. Because the
program does not scale these travel times to control totals, any changes reflect
increases and decreases in junction delay along the route. The program applies scaling
to link travel times and delay values; the program does not scale dwell times and
junction delays. The method uses two sets of TURNPENI data, each with its own
MAXDELAY variable (to reflect possibly different bus-lane provisions each year).

Typically, modeled stops are close to a junction node. Therefore, the program adds the
entire junction delay to the travel time of the link approaching the modeled junction.
You might model turning delays at a transit line’s last node. The program accounts for
such delays as occurring before the line reaches its final stop, even though the vehicle
does not pass through the node. The program adds that node’s lowest turning delay to
the travel time along the final link.
You should configure the model to read the TURNPENI file at the same time as the
LINEI files. When reading LINE data from a network file, the program has already
calculated link travel times and cannot amend turn penalties.
Public Transport Program > Using the Public Transport program > Coding network times/speeds

Coding network times/speeds

The Public Transport program requires a network that provides the basic infrastructure
over which public transport services operate— zones, nodes/stops, links. This network
can contain any node and link attributes you choose. Possible sources of the network
include:
• Network program, produced specifically for modelling a public transport system

• Existing highway network produced by the Network or Highway programs

• Public Transport program, in which case only the network information is used (the public
transport element is discarded)

The network must provide basic link attributes that support the Public Transport
program’s modelling functions: link distance, and walk and transit times or speeds.
Link distance is required (specified by LI.DISTANCE or another variable from which
distance can be derived). The program uses link distance to calculate link times when
you provide only speeds, to skim distance from routes, and to calculate fares for
distance-based fare models.
Subsequent sections in this topic offer guidance on how to code transit and nontransit
times and/or speeds in the network:
• Transit times/speeds

• Nontransit times/speeds
Public Transport Program > Using the Public Transport program > Coding network times/speeds > Transit times/speeds

T ransit times/speeds
The Public Transport program requires a base transit time for links that public transit
lines traverse. This is supplied to the program with PARAMETERS TRANTIME. (You can
factor each line’s base link-time in a variety of way, as described in “LINE” on
page 868.)
You can use different techniques to specify a link’s transit time. Possible techniques
include:
• Set a link’s transit time to the congested time resulting from a highway assignment:
TRANTIME = LI.TIME_CONGESTED (assuming the links contain a variable named
TIME_CONGESTED).

• Create a network variable that stores transit speeds with the Network program.
(If the highway network stores public transport links, you can exclude those links from
highway assignments by setting those links’ path value to a negative value and their
capacity to 0.)
• Set array(s) of working link values in the LINKREAD phase and use those arrays in the
TRANTIME expression.
For example:
PHASE=LINKREAD
if (link condition…)
LW.TTIME = LI.DISTANCE*60/LI.SPEED * 1.2
else
LW.TTIME = LI.DISTANCE *60 / LI.SPEED
endif
ENDPHASE
PARAMETERS TRANTIME=LW.TTIME

• TRIPS users only. Input the TRIPS link records directly to the Network program to create a
Cube Voyager network. The Network or Public Transport programs can derive transit and
nontransit link times from the link record’s link-type field and the LTYP data in the lines file.
See “Example 2: Preparing a public transport network from TRIPS link data” on page 1019.
Public Transport Program > Using the Public Transport program > Coding network times/speeds > Nontransit times/speeds

N ontransit times/speeds
You can develop nontransit legs outside the Public Transport program, inside the Public
Transport program, or some combination. Regardless of the process, you must use
GENERATE statements within the DATAPREP phase to develop a nontransit network.

When developing the nontransit network outside the Public Transport program, you
must ensure that you use costs—perceived or actual—consistent with the cost
components that the route-enumeration and route-evaluation processes use.
Keywords in the GENERATE statement set the method for obtaining nontransit legs.
However, you might need to precede the GENERATE statement with a script that
manipulates link attributes. As in the LINKREAD phase, you can loop through all the
links in the network and set desired link values.
Example:
PHASE=DATAPREP
LINKLOOP
if(link condition…)
LW.NTCOST = LI.DISTANCE * 1.6
else
LW.NTCOST = LI.TIME*3.8
endif
ENDLINKLOOP
GENERATE COST=LW.NTCOST * 2.5, EXCLUDE=(LW.NTCOST > 100)
ENDPHASE
Public Transport Program > Using the Public Transport program > Generating nontransit access and egress legs

Generating nontransit access and egress legs

The GENERATE statement is a powerful and flexible tool that generates the components
of the nontransit network—access, egress, and transfer legs. However, misuse can
generate unnecessary legs, resulting in poor quality routing.
Public Transport Program > Using the Public Transport program > Generating nontransit access and egress legs >
Example 1: Drive-walk nontransit legs

Exam ple 1: Drive-walk no ntransit legs

Consider the routes from zone 1 to zone 11 in the network shown. Travellers access the
transit system through nontransit legs generated with two GENERATE statements, for
modes 1 (walk) and 2 (drive).
NT LEG=1-3967 MODE=2 COST=2.03 DIST=2.03 ONEWAY=T XN=4227 4006 4007 3963 3965 3966
NT LEG=1-4000 MODE=2 COST=1.66 DIST=1.66 ONEWAY=T XN=4005 4004 15646 4003 15647 3961
NT LEG=1-4143 MODE=2 COST=3.20 DIST=3.20 ONEWAY=T XN=4226 4267 4266 4265 4302 4303
4301 4144 4773
NT LEG=1-4227 MODE=1 COST=12.96 DIST=0.27 ONEWAY=T
NT LEG=1-4263 MODE=2 COST=3.87 DIST=3.87 ONEWAY=T XN=4005 4004 15646 4003 15647 3961
4000 3999 3998 3997 9420 9419 3996 9423 3993 3992 9810 3991
NT LEG=1-4276 MODE=2 COST=2.66 DIST=2.66 ONEWAY=T XN=4268 4269 4270 4271 15687 8710
8709 4273 4274
NT LEG=1-4309 MODE=2 COST=2.12 DIST=2.12 ONEWAY=T XN=4268 4269 4307 4306 4308
NT LEG=1-4322 MODE=2 COST=3.39 DIST=3.39 ONEWAY=T XN=4268 4269 4270 4271 15687 8710
8709 4273 4315 4314 4316 4319
NT LEG=1-4386 MODE=2 COST=3.40 DIST=3.40 ONEWAY=T XN=4268 4269 4307 4306 4308 4309
4774 4349 4775

Travellers egress from the public transport system to zone 11 with the nontransit legs
reproduced below, generated by a GENERATE statement.
NT LEG=4276-11 MODE=1 COST=3.36 DIST=0.07 ONEWAY=T
NT LEG=4278-11 MODE=1 COST=14.40 DIST=0.30 ONEWAY=T XN=4276

The routing algorithms only recognize routes that have an access leg followed by pairs
of transit and nontransit legs, the last being the egress leg. Although a nontransit-only
route, 1->4276->11 exists, the algorithm will not enumerate that route.
The all-or-nothing process, which marks base times for the route-enumeration “spread,”
finds that 1->4276 is the best access leg to the public transport system for zone 11.
Because travellers cannot cannot walk directly to 11 from 4276, they ride a transit line to
4278 and walk to 11 from there. (Where transit alternatives are either not available or not
feasible, the process will find no routes between the two zones.)
Because the program found a route, even a nonsensical one, the program finds base
times at nodes and enumerates and evaluates routes.
REval Route(s) from Origin 1 to Destination 11
1 -> 4322
4322 -> 4280 -> 4280 lines AM4L5 AM4L6- AM4L18
4280 -> 4276 -> 11 lines AM4L12 AM4L89-
Cost= 30.8287 Probability=0.2803
1 -> 4322
4322 -> 4325 -> 4325 lines AM4L5 AM4L6- AM4L18
4325 -> 4276 -> 11 lines AM4L12 AM4L89-
Cost= 30.83 Probability=0.2803
1 -> 4276
4276 -> 4278 -> 11 lines AM4L12- AM4L89
Cost= 31.42 Probability=0.0071
1 -> 4276
4276 -> 4280 -> 4280 lines AM4L12- AM4L89
4280 -> 4276 -> 11 lines AM4L12 AM4L89-
Cost= 34.98 Probability=0.0959
1 -> 4322
4322 -> 4276 -> 11 lines AM4L12 AM4L89-
Cost= 19.62 Probability=0.3364

The fourth route in the list accesses and egresses the transit system at node 4276 and
takes a transit line in between, raising questions about the quality of the evaluated
routes. Rather than being an algorithmic problem, this arises due to the quality of the
input data. In this case, if you allow drive access from zone 1 to 4276, then you should
consider generating a drive-walk nontransit-only route between zones 1 and 11.
Otherwise, remove the drive accesses and connect zone 1 to the transit system only
with walk legs.
Removing routes that access and egress the transit system at the same node would
alleviate just one symptom rather than the underlying cause.
A good nontransit network is essential for identifying good quality routes. You develop a
nontransit network through an iterative process, validating and refining the network
produced by the GENERATE statements over a few cycles.
Some useful GENERATE keywords to control the excessive generation of nontransit legs
are:
• SLACK

• MAXNTLEGS

• DIRECTLINK
Public Transport Program > Using the Public Transport program > Considering nontransit-only routes

Considering nontransit-only routes

A route in the Public Transport program consists of an access leg, and one or more
pairs of transit leg bundles and nontransit legs, the last of which is the egress leg. Thus,
nontransit-only routes never get enumerated, and zones may appear unconnected
when they are not.
Even when nontransit-only routes are not of interest, they have to be dealt with.
Nontransit-only routes might be much faster than expected transit routes. If the cost
difference between the two is outside the range of the route-enumeration SPREAD, the
program will not enumerate the transit routes either. Thus the program will not connect
zones by transit, for no apparent reason.
Public Transport Program > Using the Public Transport program > Considering nontransit-only routes > Example 1: Drive-
only route

Exam ple 1: Drive-o nly ro ute

This diagram shows two walk (MODE=11) access legs and one drive (MODE=12)
access leg that two GENERATE statements generate. No drive-drive routes are generated.
NT LEG=81-1092 MODE=11 COST=19.20 DIST=0.40 ONEWAY=T XN=1094
NT LEG=81-1104 MODE=11 COST=7.68 DIST=0.16 ONEWAY=T
NT LEG=81-1109 MODE=12 COST=1.41 DIST=0.47 ONEWAY=T VOL=430 VOLT=430 XN=1104

The transit time from 1109 to 1092 is just under a minute. Therefore, the all-or-nothing
process determines that the best stop to access line MAIN is 1109.
The program generates several nontransit legs at 1109, including a drive egress:
NT LEG=1109-99 MODE=12 COST=1.53 DIST=0.65 ONEWAY=T XN=1108 1105

The best-cost route from 81->99 is to drive from 81 to 1109 and then to 99. However,
because this is a nontransit-only route neither the all-or-nothing process nor the
enumeration process will enumerate the route. Further, because the route is so much
faster than any of the possible transit routes, the program will not enumerate the transit
routes either, unless you define a very large route-enumeration SPREAD, which will
result in an unnecessarily large route set for those zone pairs that genuinely connect
with transit routes (most zone pairs in any study). Therefore, zones 81 and 99 will
appear unconnected.
If you are not interested in nontransit-only routes, skims, and loads, you can leave such
zone pairs unconnected. However, when validating a network, you might establish why
zone pairs do not connect.
If, however, nontransit-only routes are required, then drive-only connections between
zones should be generated:
GENERATE,
 COST=(li.DIST * 60) /li.OFFPSPD,
MAXCOST[1]=5,
NTLEGMODE = 14,
FROMNODE=81, TONODE=99

This statement generates short drive-only routes between zones that cost 5 units or
less.
NT LEG=81-99 MODE=14 COST=2.19 DIST=0.88 ONEWAY=T VOL=10 VOLT=10 XN=1094 1093 1092
1091 1090 1107

This route traverses links other than 81->1109 and 1109->99 and costs even less,
making any transit-based routes even less competitive. However, because the NT
statement identifies the drive-only route, the route-enumeration and route-evaluation
processes enumerate that route:
REnum Route(s) from Origin 81 to Destination 99
81 -> 99
Cost=2.19
REval Route(s) from Origin 81 to Destination 99
81 -> 99
Cost= 2.19 Probability=1.0000

In this example, the transit routes are much slower than the drive-only one, and are only
enumerated when SPREADFACT is 1.5. Although the program enumerates transit routes,
the program only uses the drive-only route. The route-evaluation process discards the
other routes because they cannot compete with the drive-only route.
REnum Route(s) from Origin 81 to Destination 99
81 -> 1109
1109 -> 569 -> 569 lines SMAIN
569 -> 1107 -> 99 lines SMAIN SMAIN
Cost=58.95
81 -> 1109
1109 -> 1107 -> 99 lines SMAIN
Cost=59.61
81 -> 99
Cost=2.19
REval Route(s) from Origin 81 to Destination 99
81 -> 99
Cost= 2.19 Probability=1.0000

You must carefully consider how to model short, fast nontransit-only routes when there
are transit alternatives. Undetected, nontransit-only routes can result in poor quality
routing as described in “Generating nontransit access and egress legs” on page 1010.
Public Transport Program > Examples

Examples
This section contains examples showing different ways to run the Public Transport
program. Examples cover:
• Public transport network development

• Public transport skimming

• Public transport loading

• Public transport user classes

• Public transport crowding

Public Transport Program > Examples > Public transport network development

Public transport network development

This section contains two examples that show public transport network development:
• Example 1: Preparing a public transport network

• Example 2: Preparing a public transport network from TRIPS link data

Public Transport Program > Examples > Public transport network development > Example 1: Preparing a public transport
network

Example 1: Preparing a public transport netw ork

This example prepares a public transport network from:
• Network program-produced network, providing the basic infrastructure of zones, nodes and
links (input with N E T I)

• Line data (input with LIN E I[1])

• Public Transport system data (input with S Y S T E MI)

• Factor data for route-enumeration and route-evaluation processes (input with FA CT OR I)

• GENERATE statements that generate the nontransit network.

Parameter TRANTIME provides the location of transit time in the link record.
The script explicitly codes the DATAPREP phase. You can only code GENERATE
statements in this phase.
This script produces a public transport network, containing validated input and the
described generated components. You can save this network and for subsequent use
by the Public Transport program for route enumeration, route evaluation, skimming,
loading, and loading analyses. You can also display the network in Cube.
;Prepare a Public Transport Network
RUN PGM = PUBLIC TRANSPORT

;Output files
FILEO REPORTO = LDPRN00A.PRN
FILEO NETO = LDNET00B.NET

;Input Files
FILEI SYSTEMI = PTSYSTEM.PTS
FILEI FACTORI[1] =FACTORLD.FAC
FILEI LINEI[1] = ISL_PTLINES.LIN
FILEI NETI = LDHWN00A.NET

;Globals
PARAMETERS TRANTIME = li.TrnsTime

PHASE=DATAPREP
;generate access/egress links
list='\nGenerate Zone Access/Egress Legs'
GENERATE,
COST=li.WalkTime,
MAXCOST[1]=16*20,
LIST=T,
NTLEGMODE=33,
INCLUDELINK = li.WalkTime>0
 ;generate xfer non-transit legs
list='\nGenerate Transfer Legs'
GENERATE,
COST=li.WalkTime,
MAXCOST[1]=16*15,
LIST=T,
NTLEGMODE = 34,
ONEWAY=F,
INCLUDELINK = li.WalkTime>0,
FROMNODE=26-4000, TONODE=26-4000
ENDPHASE
ENDRUN
Public Transport Program > Examples > Public transport network development > Example 2: Preparing a public transport
network from TRIPS link data

Example 2: Preparing a public transport netw ork from

T RIPS link data
This example prepares a public transport network from TRIPS-formatted link data. You
can input the TRIPS network directly into the Network program to prepare the base
network.
The script uses three phases:
• NODEREAD reports the number, and X- and Y-coordinates of all nodes in the input
network.

• LINKREAD calculates walk and transit times for all links in the network. TRIPS networks
have links, identified by link type, that are “walk” only, “transit” only, or “both” walk and
transit. The LINKREAD phase produces walk and transit time fields for each link. For links
where only one activity can take place, the other field contains a zero.

• DATAPREP produces some diagnostics and generates access, egress, and transfer links.
The generation process only includes links with a walk link-time greater than zero.
;Prepare a Public Transport Network from TRIPS data
RUN PGM = PUBLIC TRANSPORT
;Output files
FILEO NETO =LDNET00B.NET
FILEO NTLEGO = LDNTL00A.NTL
FILEO REPORTO =LDPRN00A.PRN
;Input files
FILEI LINEI[1] = \ISL_PTLINES.LIN
FILEI NETI = LDHWN00A.NET
FILEI FACTORI[1] = FACTORLD.FAC,
LIST=T
FILEI SYSTEMI = PTSYSTEM.PTS
;GLOBALS
PARAMETERS TRANTIME = li.TrnsTime
;NODEREAD phase loops over nodes. Can access network node variables N.xxx,
;and generate node variables Nw.xxx.
PHASE=NODEREAD
print list=ni.n, ni.x, ni.y
ENDPHASE
;LINKREAD phase loops over links. Can access network link variables L.xxx and
;generate link variables Lw.xxx.
PHASE=LINKREAD
;this phase is used to generate walk and transit times for
;the links of a TRIPS Public Transport network
;convert TRIPS distance and speed/time fields from 100dths to units
lw.RDIST=li.DISTANCE/100.
lw.RSPDTIME=li.SPDTIME/100.

;links with LT codes 10, 28,29,31,32 are walk only

lw.WalkTimePT = 0
if(li.LType == 10,28,29,31,32 && li.STFLAG == 'S')
 lw.WalkTimePT = 60.* lw.RDIST/lw.RSPDTIME
elseif(li.ltype == 10,28,29,30,31,32 && li.STFLAG == 'T')
lw.WalkTimePT=lw.RSPDTIME
elseif(li.LType == 18)
lw.WalkTimePT = 60.* lw.RDIST/4.
endif

if(li.LType == 10,18,28,29,31,32)
lw.TrnsTime = 0.0
else
lw.TrnsTime = lw.RSPDTIME
endif

if(lw.TrnsTime != 0.0 && li.STFLAG == 'S')

lw.TrnsTime =(60.* lw.RDIST/lw.RSPDTIME)
endif

list =li.A(9),li.B(9), li.DISTANCE(8.2), lw.RDIST(8.2) li.WalkTime(8.2),

lw.WalkTimePT(8.2), li.TrnsTime(8.2), lw.TrnsTime(8.2), li.LType(3), li.STFLAG
ENDPHASE
;DATAPREP is the non-transit leg generation/input phase.
;Network and line variables can be
;accessed and manipulated and non-transit legs are generated.
PHASE=DATAPREP
;Count & report number of transit only, walk only and both walk and
;transit links. If no walk or transit links, or links with invalid
;time, the run is aborted with a suitable message
;(This demonstrates the use of the command LINKLOOP which loops over links)
WalkLnkCnt = 0
TrnsLnkCnt = 0
BothLnkCnt = 0
ErrLnkCnt = 0

LINKLOOP
if(lw.WalkTimePT > 0.0 && lw.TrnsTime == 0.0)
WalkLnkCnt = WalkLnkCnt+1
elseif(lw.WalkTimePT == 0.0 && lw.TrnsTime > 0.0)
TrnsLnkCnt = TrnsLnkCnt+1
elseif(lw.WalkTimePT > 0.0 && lw.TrnsTime > 0.0)
BothLnkCnt = BothLnkCnt+1
else
ErrLnkCnt = ErrLnkCnt+1
PRINT LIST = li.a, li.b, lw.WalkTimePT, lw.TrnsTime
endif
ENDLINKLOOP
PRINT LIST = '\nNumber of walk only links = ', WalkLnkCnt,
'\nNumber of transit only links = ', TrnsLnkCnt,
'\nNumber of walk and transit links = ', BothLnkCnt,
'\n'
;Note if and 'if' statement does not fit on one line and closing 'endif'
;is required
if(WalkLnkCnt==0 && BothLnkCnt==0)abort msg = No Walk links in the Network
if(TrnsLnkCnt==0 && BothLnkCnt==0)abort msg = No Transit links in the Network
if(ErrLnkCnt> 0)abort msg = Links with invalid time/speeds in Network
;Generate access/egress links
list='\nGenerate Zone Access/Egress Legs '
GENERATE,
COST=lw.WalkTimePT,
 MAXCOST[1]=16*20,
LIST=T,
NTLEGMODE = 33,
INCLUDELINK = lw.WalkTimePT>0
;Generate xfer non-transit legs
list='\nGenerate Transfer Legs '
GENERATE,
COST=lw.WalkTimePT,
MAXCOST[1]=16*15,
LIST=T,
NTLEGMODE = 34,
ONEWAY=F,
INCLUDELINK = lw.WalkTimePT>0,
FROMNODE=26-4000, TONODE=26-4000
ENDPHASE
ENDRUN
Public Transport Program > Examples > Public transport skimming

Public transport skimming

This example extracts skim or level-of-service matrices, reports them, and saves them
to the file indicated by MATO[1].
A previously prepared public transport network is input with NETI.
You must enumerate and evaluate routes before extracting skims. The ROUTEO file
indicates that the script will enumerate routes. (Alternatively, you could input routes
prepared in an earlier run with ROUTEI.)
The SKIMIJ phase selects skimming, which the script must explicitly code. Skim
functions select the skims for extraction. (Skimming automatically invokes the route-
evaluation process.)
The optional MATO phases reports skims.
;Skim Route Attributes from a previously prepared Public Transport network
RUN PGM=PUBLIC TRANSPORT
;Output files
FILEO REPORTO = LDPRN00A.PRN
FILEO MATO[1] = LDMAT00E.MAT,
MO=2-9,11-23, NAME = Compcost, ValOfChoice, IWAITA, XWAITA, IWAITP, XWAITP,
TIMEAAM, TIMEATM, TIMEPAM, TIMEPTM, TIMEPNTM, BRDPENAM, BRDPENTM,
XFERPENAM, XFERPENTM, DISTAM, DISTTM, DISTNTM, BRDINGSAM, BRDINGSTM, BESTJRNY,
=22*2
FILEO ROUTEO[1] = LDRTE00B.RTE
;Input files
FILEI NETI = LDNET00B.NET
;SKIMIJ loops over IJ pairs. Skim are saved in working matrices.
;Routes are enumerated, evaluated and skimmed before this phase.
PHASE=SKIMIJ
MW[2]=COMPCOST(0) ;composite cost
MW[3]=ValOfChoice(0) ;value of choice

MW[4]=IWAITA(0) ;initial wait time, actual, avg

MW[5]=XWAITA(0) ;transfer wait time, actual, avg
MW[6]=IWAITP(0) ;initial wait time, perceived, avg
MW[7]=XWAITP(0) ;transfer wait time, perceived, avg

MW[8]=TIMEA(0,ALLMODES) ;time for all modes, actual

MW[9]=TIMEA(0,1,7,8,11) ;in-vehicle time for transit modes, actual, avg
MW[11]=TIMEP(0,ALLMODES) ;time for all modes, perceived, avg
MW[12]= TIMEP(0,TMODES) ;in-vehicle time for transit modes, perceived,
;avg
MW[13]= TIMEP(0,33,-35) ;walk/ride time for non-transit modes,
;perceived, avg

MW[14]= BRDPEN(0,ALLMODES) ;boarding penalty for all modes, avg

MW[15]= BRDPEN(0,TMODES) ;boarding penalty for transit modes, avg
MW[16]= XFERPENA(0, ALLMODES) ;transfer penalty for all modes, actual, avg
MW[17]= XFERPENP(0, 1,7,-8,11) ;transfer penalty for transit modes, perceived,
 ;avg

MW[18]= DIST(0,ALLMODES) ;distance for all modes, avg

MW[19]= DIST(0,TMODES) ;in-vehicle distance for transit modes, avg
MW[20]= DIST(0,NTMODES) ;walk/ride distance for non-transit modes, avg

MW[21]= BRDINGS(0,ALLMODES) ;number of boardings for all modes, avg

MW[22]= BRDINGS(0,TMODES) ;number of boardings for transit modes, same as
;above, avg

MW[23]=BESTJRNY ;best travel time

ENDPHASE

;MATO loops over J for each I. All skims extracted above are reported
PHASE=MATO

if(ROWSUM(2) > 0) PRINTROW mw=2 TITLE='Compcost', BASE1=T, FORM=10.2

if(ROWSUM(3) > 0) PRINTROW mw=3 TITLE='ValOfChoice', BASE1=T, FORM=10.2

if(ROWSUM(4) > 0) PRINTROW mw=4 TITLE='IWAITA', BASE1=T, FORM=10.2

if(ROWSUM(5) > 0) PRINTROW mw=5 TITLE='XWAITA', BASE1=T, FORM=10.2
if(ROWSUM(6) > 0) PRINTROW mw=6 TITLE='IWAITP', BASE1=T, FORM=10.2
if(ROWSUM(7) > 0) PRINTROW mw=7 TITLE='XWAITP', BASE1=T, FORM=10.2

if(ROWSUM(8) > 0) PRINTROW mw=8 TITLE='TIMEA ALLMODES', BASE1=T, FORM=10.2

if(ROWSUM(9) > 0) PRINTROW mw=9 TITLE='TIMEA TMODES', BASE1=T, FORM=10.2

if(ROWSUM(11) > 0) PRINTROW mw=11 TITLE='TIMEP ALLMODES', BASE1=T, FORM=10.2

if(ROWSUM(12) > 0) PRINTROW mw=12 TITLE='TIMEP TMODES', BASE1=T, FORM=10.2
if(ROWSUM(13) > 0) PRINTROW mw=13 TITLE='TIMEP NTMODES', BASE1=T, FORM=10.2

if(ROWSUM(14) > 0) PRINTROW mw=14 TITLE='BRDPEN ALLMODES', BASE1=T, FORM=10.2

if(ROWSUM(15) > 0) PRINTROW mw=15 TITLE='BRDPEN TMODES', BASE1=T, FORM=10.2
if(ROWSUM(16) > 0) PRINTROW mw=16 TITLE='XFERPEN ALLMODES', BASE1=T, FORM=10.2
if(ROWSUM(17) > 0) PRINTROW mw=17 TITLE='XFERPEN TMODES', BASE1=T, FORM=10.2

if(ROWSUM(18) > 0) PRINTROW mw=18 TITLE='DIST ALLMODES', BASE1=T, FORM=10.2

if(ROWSUM(19) > 0) PRINTROW mw=19 TITLE='DIST TMODES', BASE1=T, FORM=10.2
if(ROWSUM(20) > 0) PRINTROW mw=20 TITLE='DIST NTMODES', BASE1=T, FORM=10.2

if(ROWSUM(21) > 0) PRINTROW mw=21 TITLE='BRDINGS ALLMODES', BASE1=T, FORM=10.2

if(ROWSUM(22) > 0) PRINTROW mw=22 TITLE='BRDINGS TMODES', BASE1=T, FORM=10.2
if(ROWSUM(23) > 0) PRINTROW mw=23 TITLE='BESTJRNY', BASE1=T, FORM=10.2
ENDPHASE
ENDRUN
Public Transport Program > Examples > Public transport loading

Public transport loading

This example loads a trip matrix, input with MATI[1], on to a previously prepared public
transport network.
You must enumerate and evaluate routes before loading trips. The ROUTEO file indicates
that the script will enumerate routes. (Alternatively, you can input routes prepared in an
earlier run with ROUTEI.)
TRIPSIJ[1] indicates that loading is to be performed. (Loading automatically invokes the
route-evaluation process.)
The REPORT statement selects two loading reports—line summary and passenger loading.
/*Load a previously built PT Network & Produce Loading Analyses Reports */
RUN PGM=PUBLIC TRANSPORT
;Output Files
FILEO NETO = LDNET00C.NET
FILEO ROUTEO[1] =LDRTE00C.RTE
FILEO REPORTO = LDPRN00B.PRN
;Input files
FILEI MATI[1] = OD.MAT
FILEI NETI =LDNET00B.NET
;Globals this invokes Loading
PARAMETERS TRIPSIJ[1] = MI.1.1
;Selection of Loading Reports
REPORT LINES=T, SORT=MODE, LINEVOLS=T, STOPSONLY=T, SKIP0=T
ENDRUN
Public Transport Program > Examples > Public transport user classes

Public transport user classes

This example prepares a public transport network, enumerates and evaluates routes,
skims, and loads for two user classes. Essentially, this example performs the main
functions of the Public Transport program for two user classes.
First, the script develops the public transport network for both user classes from:
• Network input on N E T I

• Lines input on LIN E I[1]

• Factors input on FA CT OR I[1] and FA CT OR I[2]

• Public Transport system data input on S Y S T E MI

• GENERATE statements for generating the nontransit network

The script codes the DATAPREP phase, a mandatory phase for public transport
network development.
Next, the script performs the following functions for each user class:
• Route enumeration — Saves routes on ROUTEO[1] and ROUTEO[2].

• Route evaluation

• Skimming — Extracts composite and value-of-choice skims, saves on MA T O[1] and MA T O[2],
and reports.

• Loading — Loads trip matrices input on any MA T I file (not necessarily the one subscripted
by the user class) to the evaluated routes.

The script codes the MATO phase to report the output skim matrices.
Finally, the script saves a public transport network containing the results of the loadings
for both user classes to NETO . You can display the results with Cube.
;Generate Non-transit network, Enumerate, Evaluate Routes,
Skim and Load for two User Classes.
RUN PGM=PUBLIC TRANSPORT

:Output Files
FILEO REPORTO = LDPRN00A.PRN
FILEO ROUTEO[2] = LDRTE00D.RTE
FILEO ROUTEO[1] = LDRTE00A.RTE
FILEO NETO = LDNET00E.NET

:input
FILEI MATI[2] = MSMAT00B.MAT
FILEI MATI[1] = MSMAT00B.MAT
FILEI SYSTEMI = PTSYSTEM.PTS
FILEI FACTORI[2] =FACTORUS2.FAC
FILEI FACTORI[1] = FACTORUS1.FAC
FILEI LINEI[1] = ISL_PTLINES.LIN
FILEI NETI =LDHWN00A.NET

;Globals
PARAMETERS TRANTIME=li.TrnsTime
PARAMETERS USERCLASSES=1,2
PARAMETERS TRIPSIJ[1] = Mi.01.1
PARAMETERS TRIPSIJ[2] = Mi.02.1

PHASE=DATAPREP
;generate access/egress links
list='\nGenerate Zone Access/Egress Legs '
GENERATE,
COST=li.WalkTime,
MAXCOST[1]=16*20,
LIST=T,
NTLEGMODE = 33,
INCLUDELINK = li.WalkTime>0

;generate xfer non-transit legs

list='\nGenerate Transfer Legs '
GENERATE,
COST=li.WalkTime,
MAXCOST[1]=16*15,
LIST=T,
NTLEGMODE = 34,
ONEWAY=F,
INCLUDELINK = li.WalkTime>0,
FROMNODE=26-4000, TONODE=26-4000
ENDPHASE

;Routes are enumerated, evaluated, skimmed and loaded for each user class

;SKIMIJ loops over IJ pairs. Skims are saved in working matrices in this phase
PHASE=SKIMIJ
MW[1]=COMPCOST(0) ;composite cost
MW[2]=ValOfChoice(0) ;value of choice
ENDPHASE

;MATO loops over J for each I. Skims are reported for each user class
PHASE=MATO
if(ROWSUM(1) > 0) PRINTROW mw=1 TITLE='Compcost', BASE1=T, FORM=10.2
if(ROWSUM(2) > 0) PRINTROW mw=2 TITLE='ValOfChoice', BASE1=T, FORM=10.2
ENDPHASE
ENDRUN
Public Transport Program > Examples > Public transport crowding

Public transport crowding

In the below example, the PT program will generate 10 STOP2STOP output files. They
are automatically named as “Stop2StopResults_1.DBF”, “Stop2StopResults_2.DBF”, …
, “Stop2StopResults_9.DBF”, “Stop2StopResults.DBF”, i.e. the numbers 1, 2, …, 9 are
corresponding to each individual iteration, and the last iteration file does not have the
iteration number appended. These files are likely to be very large for large networks.
Public Transport Program > Troubleshooting

Troubleshooting
E rro r D e ta ils

File sharing lock count This is an error message from

exceeded Microsoft Access indicating the
number of locks required to
perform a transaction exceeds
the maximum number of locks
per file.

This value can be modified using

the Cube installer (License
agreement > “Advanced
Options” > “Max Locks Setting”).
200000 is the recommended
default value, but this may need
to be increased when dealing
with larger recordsets.

There are other options for

modifying this setting here:
support.microsoft.com/kb/815281

InsertBufferedFeatureException InsertBufferedFeatureException
occurs when strings longer than
252 characters are being
imported into a field. In this case,
Cube will automatically truncate
the strings (with the last three
characters being “...”).
TRNBUILD Program > Using TRNBUILD in Cube Voyager

Using TRNBUILD in Cube Voyager

Developed for TP+, TRNBUILD has some unique differences from other Cube Voyager
programs. Important differences include:
• TRNBUILD supports a maximum of 64 transit lines through the same common stop node.

• TRNBUILD supports a maximum of 255 modes.

• TRNBUILD documentation refers to non-transit links as either support links or non-transit.

Both terms have the same meaning.

• When coding TRNBUILD scripts, enter any distances in control statements in hundredths
of distance units without any decimal point. Enter time and speed as true values, including
the decimal point included. For example, code 1.5 miles as 150, and code 1.4 minutes as
1.4.

NOTE: This applies to script statements only. NETI values are real: Enter distances in
true units (miles or kilometers, with decimal points included) on the networks.

• Times and distances are only accurate to the second decimal place. To increase
efficiency, TRNBUILD stores times and distances as 16-bit integers with an implied scale
of 100 and a maximum value of 65,530. For example, TRNBUILD stores a network
distance 1.235 as 124, and stores a time of 1.001 as 100.

• TRNBUILD displays distances reported in the print file or any output files in hundredths of
units. TRNBUILD reports times in real units in the print file, except for the LINESTRING
report and the TRACE summary. TRNBUILD outputs times in hundredths of units in LINKO
and MATO.

• Use the MATRICES statement to define the total number of O/P matrices in the MATO file.
You can only use a limited number of variables or values in matrix calculations.
Expressions cannot reference the values from other matrices.

• The process is static; you cannot alter processes on a zone-by-zone basis.

TRNBUILD Program > Introduction to TRNBUILD

Introduction to TRNBUILD
Transit processing is similar to highway-network processing, but more complex. During
transit processing, the program must form a transit network and develop paths between
zones. The program uses paths to extract level-of-service (LOS) data, which mode-
choice models use (in a separate process). The program also uses paths to assign trips
to the network. When developing paths for transit processing, the program must
consider mode transfers, mode weighting, and line combinations—a more complex
process than path development for highway processing.
A transit network contains lines and support links. Lines are user-defined transit routes.
Support links—nontransit links that provide connectivity between different transit lines and
between zone centroids and lines—are necessary to support the transit system. Types of
support links include walk, park-and-ride, and transfer. The program requires a
background highway network as the starting point for support links and lines. The
highway network provides the location of nodes, and basic information about distance
and highway travel. For transit lines that do not use separate guideways, such as buses,
the program computes the line’s speed as some function of the highway distances and
speeds on the links used.
Every support link and every transit line must have a mode number. Mode numbers can
range from 1 to 255. The program treats modes assigned to transit lines as transit
modes and treats all other modes as support modes. You may assign mode numbers as
desired, but if the program detects any support links with a mode used by a transit line,
the program will terminate with a fatal error message. Citilabs recommends that you set
a standard for defining modes and use that standard consistently.
Support links can use the distances from any related highway links, but usually the
program computes support-link travel times with a separate process. You must enter
support links with control statements. Traditionally, the program uses support links to
model people walking to, from, and between transit stop nodes, and for driving from
zones to transit. TRNBUIILD has no predefined specifications of support links and their
modes. For maximum flexibility, Citilabs recommends assigning separate modes for the
following categories:
• Walk from zone to another mode

• Walk to zone from another mode

• Drive from zone to another mode

• General walking

You might prefer to funnel all access to and from rail stations through links of certain
modes (usually walk, transit, and drive). This requires saving three modes for these
access links. You might prefer to further stratify transit access by grouping some transit
modes.
With properly structured data, you can easily change mode assignment. When defining
support links, you can assign modes. TRNBUILD allows you to assign a global value for
modes, and to change the global setting before reading various line records. However,
global values are not compatible with transit-network editing in Cube Base. Therefore,
Citilabs recommends that you not use global values.
The program has a built-in process to generate zonal access support links
automatically. That process builds traditional paths using the highway-link distances and
the walk speed to find the best path from each of the selected zone centroids to each of
the transit stops within a designated distance. The program generates a support link
from the zone to each stop reached within the specified distance. You can vary the
distance by mode, and can limit the number of links by mode. The program can
generate links from a zone, to a zone, or from a zone and to a zone. The program
assigns modes globally. If the program uses a special highway network, you can also
restrict the number of highway links that paths traverse. You can also provide access
links that cause the program to develop the path from the zone to the link’s A-node,
rather than from the zone to a stop node at the link’s B-node. You must initiate zonal
access with the ZONEACCESS control statement.
PNR control statements trigger a similar built-in process to generate drive-access support
links. PNR access development differs from zonal access development. If you code
PNR node as a link, the program considers the first node to be the PNR node, and
generates an additional lot link between the two nodes. Only the zones explicitly defined
with the PNR node can access the node. The program will generate an access link from
each specified zone that is within the specified distance of the PNR node. You can enter
the generated links as either one- or two-way; usually you will code drive-access links
as one-way. The program develops the zone-to-PNR-node link using a minimum-time
path-development process. These processes only use the links in the highway network.
Specifying the maximum-time parameter can reduce the path development time. You
cannot suppress this access development process if there are PNR control statements in
the input.
TRNBUILD Program > Introduction to TRNBUILD > Path building

Path building

The program builds transit paths using a special algorithm, which is similar to highway
path building. When building highway paths, the program develops a path set for an
origin zone, and then extracts individual zone-to-zone paths. Transit path building has
considerably more variables than traditional highway path building. Rather than simply
developing the single best path between two zones, TRNBUILD allows you to invoke
many factors at various points in the process.
The algorithm determines the best path to each node. Because there may be restrictions
(usually mode oriented) out of the node, the program must keep the best path into each
node for each active mode at the node. This requires considerable computer resources.
Though the algorithm can develop paths by saving just the single best path into a node,
this method may not obtain true minimum paths if there are mode-change factors or
prohibitions. Saving the single best path will reduce path-development time by about
sixty percent. The PATHSTYLE parameter sets the alternate option (see “PARAMETERS”
on page 1070).
Usually, you input transit-line data in some period-specific basis, which may be
inconsistent with the processed period. For example, you might include a line with a 90-
minute headway in an analysis for a 60-minute period. Because the program is not time
specific, the program does not know how many times the line is available at a particular
stop node during the process: one time or two times? Instead, the program assumes
that any line is available at any of its stop nodes.
Traditionally, a line’s wait time is calculated as one-half of its headway. However, most
travelers are somewhat knowledgeable about what time they can board the line.
Therefore, you might invoke a maximum initial wait time, IWAITMAX. For example, a 60-
minute line would normally have a 30-minute wait time. But when the line is the first in a
trip, you might cap the wait time. To ensure that wait time accounts for boarding time,
you can also set a minimum wait time, IWAITMIN. Similarly, for transferring passengers,
the transit system likely offers some synchronization and the wait time may differ from
the traditional wait time. You can specify maximum and minimum wait times at transfer
points with XWAITMAX and XWAITMIN.
TRNBUILD also allows you to factor times on various segments of a trip, creating
perceived times that differ from actual times. The program applies these perceived
factors based on modes, wait time, and transfers. The program builds paths based on
perceived times. Before choosing a path segment, the program converts the actual time
to perceived time based on the action considered. As the path moves from one segment
to another, the modes of the from- and to-segments determine how the program
processes the path. The program considers a segment to be either a support link or a
contiguous portion of a transit line. In most cases, segment connections have some
associated perceived time. Boardings occur when accessing a transit segment;
transfers occur at any boarding other than a path’s initial boarding.
During segment-to-segment processing, the program adds a value to the path time; it
can be zero. The program obtains the added value from the XPEN and XPENFAC arrays,
depending upon the segment modes (see “FACTOR” on page 1047). The program
considers the XPEN value to be an actual value, which is modified during path selection
by the XPENFAC factor to obtain a perceived value. The values are mode-to-mode
specific, and include all modes. You can prevent certain mode-to-mode combinations
with NOX factor switches. The program computes the perceived segment time by
multiplying the actual segment time by the segment’s MODEFAC factor. If the to-segment
is transit, the program also multiplies the wait time by the XWAITFAC factor and possibly
adds a boarding penalty, BOARDPEN. You can use the boarding penalty to add larger
perceived values to the path time as the number of boardings increases, discouraging
excessive transit boardings.
In basic mode, the program works with only the set of best paths between two zones (I-
J). For some zone combinations, there are other reasonable possibilities. However,
considering all possibilities would take an inordinate amount of computer resources.
TRNBUILD has an option to calculate additional path sets based on the accesses at the
zones. Specify this option with a MULTIACCESS control statement. With this option, the
program builds a path set from every outbound link at zone I and considers all the
access links at J for each path to J. Thus, if zone I has four outbound links and zone J
has four inbound links, the program might consider up to sixteen paths between I and J.
During assignment, the program compares each of the I-J possibilities to the best path
between the zones, and considers only those that fall within the MULTIACCESS
specifications. Those specifications define time differences, specified as both actual
minutes and relative time. For example, if MULTIACCESS MAXTIMEDIFF=3, MAXPCTDIFF=10,
then the assignment program will use any I-J path that is within 3 minutes, or 10 percent,
of the best I‑J path.
The program uses all the selected paths in assignment. The program allocates trips to
the paths according to the relative times of the paths. Specifying MULTIACCESS for an
application without assignment has no effect on results. However, if an application traces
paths, the trace will show the various paths that would be used during assignment. Note
that the multiaccess process does not necessarily create a good spread for the
assignment. The spread depends on the access links at a zone. For example, if three
outbound access links connect to the same line, the spread may be only between the
access links. If there is another access link to another line, that link might get a smaller
share because the program spreads the trips across the four links. The multiaccess
process increases path-building time because the process must build more paths.
TRNBUILD Program > Introduction to TRNBUILD > TRNBUILD line-combining process

TRNBUILD line-co m bining pro cess

The line-combining process selects the path from a node when travelers can choose
from more than one line to reach a specific downstream node. TRNBUILD’s line-
combining process combines only lines with the same mode.
When there are several lines of the same mode that can take a passenger from a
particular node to the same downstream node and those lines have different headways
or different run times, TRNBUILD considers perceived times and completes the following
steps:
1. Select the best line, based on the total time (sum of wait time and run time) between the
two points on each line.

2. Save lines that have a total time within the mode’s COMBINE criteria.

3. Compute combined wait time by dividing the total number of vehicles available per hour
into sixty minutes, and dividing by two.

In many cases, the run times for the lines vary, so a method must be employed to
compute a weight for each line’s run time.
It would seem that the average run time could be used, but there are scenarios where
this could result in rather strange values. A typical scenario would be at a station where
there are numerous local lines (low headways) that run at slow speeds, and an
occasional express line (high headway) that runs at a high speed.
A new wait time is computed for each line by subtracting the best run time from the line’s
total time. These new wait times are used to compute an equivalent headway, which in
turn, is used to compute an estimated combined wait time. Each line’s run time is given a
weight based upon the ratio of the estimated wait time to its new wait time. The total run
time is weighted sum of all the line run times.
There is no guarantee that the process will always result in a combined total time that is
less than the best path for every situation. But, the process is reasonable in most
situations.
To illustrate the process, define the following terms:
• Actual value (A) — Determine directly from line links and frequencies (that is, the actual link
time or the actual waiting time to board).

• Perceived value (P) — Compute by factoring actual value by an appropriate weighting

factor

• Arun — Actual run time

• Await — Actual wait time (headway/2). This value is restricted by the wait factors (IWAITMIN,
 IWAITMAX, XWAITMIN, and XWAITMAX)

• Prun — Perceived run time (Arun * ModeFac)

• Pwait — Perceived wait time (Await * WaitFac)

• Ptt — Perceived travel time (Prun + Pwait)

• B(arg) — Best value of arg

A list of all the lines and their corresponding Ptt to reach the node from this node is
obtained. The line with the lowest Ptt is considered as the best line. All other lines are
then evaluated to determine if they should be combined with the best line. A line will be
combined with the best line if its Ptt does not exceed the sum of the B(Ptt) + MaxDiff, or,
if there is a COMBINE IF expression which is satisfied for the line.
After the program obtains a list of the lines to be combined, it determines how the trips
will be distributed among the lines. A revised perceived wait time for each line is
computed as the difference between the line’s Ptt and the B(Prun). Each line is given a
weight based upon its revised wait time relative to the other lines’ revised wait times.
The perceived path wait time is computed as one half the headway based upon vehicles
available and factored by the appropriate wait factor. ( (60 / VehAvail / 2) * WAITFAC).
The perceived path run time is the sum of (weight * perceived run time) for all lines.
Example: Assume the following conditions for an initial boarding between a node pair,
and MaxDiff = 10.00:
IWAITMAX=8 IWAITMIN=2 MODEFAC=1.2 IWAITFAC=2.5
Line Freq Run Pwait Prun Ett RWait Wt Rtime
A 10 22 12.50 26.40 38.90 26.90 .291 7.69
B 15 15 18.75 18.00 36.75 24.75 .317 5.70
C 20 10 20.00 12.00 32.00 20.00 .392 4.70
D 60 23 20.00 27.60 47.60 Not combined

Perceived Path Values: Wait= 5.45 Rtime= 18.09

TRNBUILD Program > Introduction to TRNBUILD > Trip matrix processing

Trip m atrix pro cessing

TRNBUILD can assign trips from a trip matrix to the paths. When using a trip matrix, the
program does not build path sets for origin zones without trips. This can reduce
computation time considerably. If there are any trips for any of the I-J pairs selected
(explicitly or implicitly), the program generates the path set, but only processes the
selected I-J pairs with trips. If the assignment option is true, the program assigns trips to
the appropriate I-J paths. The program accumulates link volumes and node boardings
and exits. You can requests several types of reports showing assignment results.
See “FILEI” on page 1052.
TRNBUILD Program > Introduction to TRNBUILD > Level-of-service extraction

Level-o f-service extractio n

You can obtain zone-to-zone values for various elements of the I-J paths. These
elements include times, distance, first and last transit nodes, access and first transit
modes, number-of-boardings, and fares. You can extract most elements by mode, or
combinations of modes. You can combine elements with user expressions. If the
program traces an I-J pair, the trace includes a list of its basic elements. The transit
running times and distances may be not exact for the transit legs where the path is split
amongst several lines. In those segments, the extracted element is the sum of (line
weight * network value) for all lines in the segment.
See “FILEO” on page 1054.
If the you specify the FILEO MATO keyword, the program writes the extracted values in
matrix format to the specified file. See also “MULTIACCESS” on page 1069.
TRNBUILD Program > Introduction to TRNBUILD > Output network

Output network

This version of TRNBUILD does not write an explicit transit network. The program can
write a DBF file containing the nodes and links, and you can use the file with Cube Base.
You can reduce the number of links in the output file by restricting the modes to be
included. The TRNBUILD network will automatically include all the nodes in a transit line.
However, an option lets you restrict the output to only stop-to-stop links (omitting the
intermediate non-stop nodes). If an assignment is made, the file will contain link
volumes, boardings, and exits at each link’s nodes. See also “FILEO” on page 1054.
TRNBUILD Program > Control statements

Control statements
TRNBUILD has several levels of control statements. Some statements must be input
before other statements, so that certain memory allocations can be made at the
appropriate times. The order of statements is not important except that the level 1
statements must be read before any level 2 statements. At the first occurrence of any
level 2 statement, the input network (designated on the FILEI statement) is opened,
certain memory allocations (specifications obtained from PHASE1 statement values) are
made, and most level 1 statement values are no longer acceptable. If these rules are
violated, and the program can’t adjust itself at that time, fatal messages may be issued.
There are exceptions, but the fatal messages can be avoided if the rules are adhered to.
Level 1 statements: FILEI, PHASE1
Level 2 statements: LINE, LINK, PNR, SELECT, SUPPORT, XY, ZONEACCESS
All other statements can be input at any time.
The following control words are available in the TRNBUILD module.

Co ntro l wo rd D e s c rip tio n

COMBINE Line combination specifications

FACTOR Various mode and mode-to-mode

factors

FARE Compute fares from path

FARELINKS Establish fare links

FILEI Input files

FILEO Output files

LINE Describe public transport lines

LINK Insert underlying links for LINES

MATRICES Compute path level-of-service

matrices

MULTIACCESS

PARAMETERS Specify basic parameters

PHASE1 Initialization parameters

PNR Drive access specifications

REPORT Request standard reports

SEGLIMITS Travel segment limits

SELECT Select process zones

SUPPLINK Describe single nontransit links

SUPPORT Describe multiple non-transit links

TRIPS Input trip matrices

XFERGEN Generate transfer support links

XY Add / modify node coordinates

ZONEACCESS Walk access specifications

TRNBUILD Program > Control statements > COMBINE

COMBINE
Line-combining specification. Keywords include:
• IF

• MA XD IFF

COMB IN E k e y wo rd s

Ke y wo rd D e s c rip tio n

IF |s255*| Designates the criteria for determining if a line between two

nodes is to be combined with another line between the same
two nodes during path building. At each boarding node the
program examines all the stop nodes that are accessible via
the lines that stop at the boarding node. If a downstream node
is accessible on more than one line, it is possible that some
travelers would use one line and others would use the other
lines. In such a cases the program must determine the
allocation of users between the lines. But, first a decision must
be made to see if, and which, lines should be combined. The
COMBINE MAXDIFF and IF selections are used to help make
that combining decision. There may be one MAXDIFF value
and one IF selection for each mode (combining is possible
only within the same transit mode).
In line choice situations the program determines which line
(simply on its own merits) provides the best path and saves
that as the “best.” Then every other line is compared to the
best line to determine if it should be considered in combination
with the best line. To make this combination decision, the
program looks first at the differences in total times (the line vs.
best line). If the difference does not exceed the MAXDIFF
value for the mode, the lines will be combined. If the difference
exceeds MAXDIFF, and there is an IF selection for the mode,
the IF is evaluated. IF selections result in either a true or false
value. If the result is true, the line will be combined with the best
line; if it is false, the line is deleted from consideration at this
node. If the difference exceeds MAXDIFF and there is no IF,
the line is deleted. See the description concerning combining
lines for details of the combining process.
The IF selection expression must be enclosed within (). The
expression may reference any of the following variables:
• I — Origin zone of the trip
• M0 — Mode used to arrive at N1
• N1 — Boarding node
• N2 — Downstream node
• MINWAIT — Wait time for the best line
• MINRUN — Run time for the best line
• MINTIME — MINWAIT + MINRUN
• WAIT— Wait time for the line under consideration
• RUN — Run time for the line under consideration
• TIME — WAIT + RUN
 • BOARD — Number of transit boards prior to N1

MA XD IFF |R255*| <0> is the first process tested in the combination decision
process. If the line’s total time does not exceed best time +
MAXDIFF, the line will be combined with the best line.

You may specify MAXDIFF and an IF for each mode. The program provides a default
MAXDIFF of 0 for each mode, but you must provide any IF selections.
TRNBUILD Program > Control statements > COMBINE > Example

Exam ple
COMBINE MAXDIFF = 255*0 ; Default process.
COMBINE IF[1]=(
(N1=5000 && N2==6000-6010,7002 && (((WAIT+RUN)–MINTIME) <=3.25)) ||
(I=1-100,500 && (wait - minwait) <= 2.00 && (time - mintime) < 3) ||
(((WAIT+RUN)–MINTIME) <= 5.00) ), ; mode 1
(((WAIT+RUN)–MINTIME) <= 3.25 ), ; mode 2
5 * ( (wait-minwait)<=2 && (run-minrun)<= 2) ; modes 3-7
; no IFs for modes 8-10
TRNBUILD Program > Control statements > FACTOR

FACTOR
Wait, xfer, mode factors. Keywords and sub-keywords include:
• B OA R D P E N

• IW A IT FA C

• IW A IT MA X

• IW A IT MIN

• MA XW A IT T IME
m NODES

• MOD E FA C

• N OX

• XP E N

• XP E N FA C

• XW A IT FA C

• XW A IT MA X

• XW A IT MIN

FA CT OR k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

B OA R D P E N |KRV15*| Perceived time value to be

added to the path time when a
transit boarding is involved.
BOARDPEN[1] is added to the
first boarding, [2] is added to
the second, etc. It is used
primarily to discourage
multiple boardings. There may
be up to 15 values.

IW A IT FA C |KRV255*| Factor to convert initial wait

time for a mode to perceived
wait time.

IW A IT MA X |KRV255*| Maximum actual initial wait

time allowed.

IW A IT MIN |KRV255*| Minimum actual initial wait time

allowed.

MA XW A IT T IME |R| <0> is a value to be

considered as the maximum
wait time between transit lines
at the nodes that are listed in
the following N= list(s). This
keyword may be specified
more than once on a
 statement. The value must be
greater than 0 and less than
180. The purpose of this
keyword is to specify transfer
nodes where the line
arrival/departure times are
synchronized. Note that this
value is not considered when
calculating initial board time.
The English short name is
MWT.

MA XW A IT T IME N OD E S |IPV| Nodes where the most prior

MAXWAITTIME value is to be
applied. If a explicit or implied
value exceeds the highest
stop node number, that node is
ignored. Thus, NODES=500-
10000000 can be used to set
all nodes. The English short
name is N.

MOD E FA C |KRV255*| Factor to convert link time to

perceived time.

N OX |K?V255[255]*| Used to preclude a path from

going directly between links
which have certain modes. A
true value is used to preclude
the path.

XP E N |KRV255[255]*| Value to be added to the path

time at each node. The value
is in actual time and must be 0-
60.

XP E N FA C |KRV255[255]*| Factor to convert XPEN to

perceived time.

XW A IT FA C |KRV255*| Factor to convert transfer wait

time to perceived wait time.

XW A IT MA X |KRV255*| Maximum actual transfer wait

time allowed.

XW A IT MIN |KRV255*| Minimum actual transfer wait

time allowed.

Use FACTORS to account for certain types of activity based upon either the mode of the
link being entered, or upon the mode of the link being exited in combination with the
mode of the link being entered. All these keywords are used to enter values into arrays
where the index corresponds directly with the mode. The keywords with double
dimensions (NOX, XPEN, XPENFAC) are based upon mode-to-mode activity, where the first
index implies the from mode, and the second index implies the to mode. If, for those
keywords, only one index is specified, the second index is assumed to be 1.
Use IWAITMAX, IWAITMIN, XWAITMAX, and XWAITMIN to account for discrepancies in the
general use of line frequencies when computing wait time at a node. For example, a line
may have a headway of 60 minutes, and the average wait for the line would be 30
minutes. But the transit system schedulers may have arranged schedules so that
generally the wait times are kept to some more reasonable limit. Use IWAITMAX and
XWAITMAX to set somewhat tighter controls on that aspect. It is generally considered that
a knowledgeable user will arrive at his first boarding node at a time that minimizes the
wait time; thus, you can set IWAIT... values separately from XWAIT... values.
Use IWAITMIN and XWAITMIN to effectively cause a wait time greater than the computed
minimum to be used. In a busy grid, there may be shuttle busses running at every
minute. At some nodes the east-west busses may arrive at the same time as the north-
south busses. In all likelihood, the transfer could not be made within the normal 30
second wait time, so additional wait time would be required.
TRNBUILD Program > Control statements > FACTOR > Example

Exam ple
IWAITFAC=255*2.0 ; all initial wait factors are 2.0
IWAITMIN[3]=4,5.5,3*6 ; beginning at mode 3: 4.00 5.50 6.00 6.00 6.00
NOX[11]= y,n,n,y ; NOX 11->1 and 11->4
NOX[12][12] = y,n,n,y ; NOX 12->12 and 12->15
XWAITMIN=10*0.5, XWAITMAX=10*12.55 XWAITFAC=2,9*2.5
MAXWAITTIME=5, NODES=800, 901-903
MWT=5, N=800, 901-903 ; same as previous line
TRNBUILD Program > Control statements > FARE

FARE
The FARE control statement defines fare values. Keywords include:
• MOD E FA R E

• XFA R E

FA R E k e y wo rd s

Ke y wo rd D e s c rip tio n

MOD E FA R E |KIV255*| An array of fares based upon mode. During path

extraction, each path segment (every non-transit link,
or transit boarding) is assessed a fare based upon
the mode of the segment. These fares are
accumulated for the path and stored in the
MODEFARE skim variable. The highest MODEFARE
encountered for a path is stored in the
MAXMODEFARE skim variable. The MODEFARE and
MAXMODEFARE skim variables can be accessed
via the MATRICES statement.

XFA R E |KIV255*255| An array of transit fares that are to be assessed each

time a transit segment is boarded. The array is
dimensioned as 255 (from_mode) * 255 (to_mode),
but not all values used. The array is used only when
transit is boarded. For the first boarding, the non-
transit to transit XFARE value is used, and for
subsequent boardings, only the prior_transit to the
boarding transit mode XFARE value is used. During
path extraction, the XFARE values used are
accumulated into the XFARE skim variable, and the
highest XFARE is saved in the MAXXFARE skim
variable. The XFARE and MAXXFARE skim variables
can be accessed via the MATRICES statement.

The fares are all entered as signed integer units within the range of -32767 to 32767.
The summary and maximum value variables may not be less than 0, or greater than
65535. Any negative values are set to zero at the end of the path extraction. Because
users code networks with different techniques and have different fare computation
processes, and there is no single way to compute fares. Some users may wish to have
an XFARE for all 255 x 255 possibilities, but If the path goes from transit to non-transit to
transit, excessive fares would be assessed (the current logic with XFARE precludes this
from happening). Other users may wish to code non-transit links with a MODEFARE, and
not use XFARE at all. In that case, consecutive non-transit links could cause a problem.
Most likely. MODEFARE and XFARE would not be used in the same application, but that
combination may be useful for certain networks.
Fares based upon distance or time traveled can be obtained by using the STEPFUNC
function described on the MATRICES control statement (see “MATRICES” on
page 1067).
TRNBUILD Program > Control statements > FARE > Example

Exam ple
FARE MODEFARE=3*50,0,0,4*75,0 ; sets transit fares for modes 1-10
XFARE[11] = 10*50, XFARE[12] = 10*50;
TRNBUILD Program > Control statements > FARELINKS

FARELINKS
Sets fare links. Keywords include:
• FA R E

• MOD E S

• L

• ON E W A Y

Fare links are links, that when traversed in a path, cause an additional fare to be added
to the I-J mode-based fare. A total of all such fares is accumulated during I-J path
tracing (done only when LOS matrices are being accumulated). At the end of the trace,
the fare-link total is added to the I-J fare accumulated in the normal fashion. The fare-
link total can be either negative or positive. However, if the final total fare (mode-based +
fare-link) value is negative, it will be reset to zero. During the trace and accumulation, all
fare links that are traversed are used in the accumulation; there is no logical combination
of the links other than full addition.
Fare links on multi-path segments of the path can cause strange results. Suppose that
the path from I-J splits between two lines: A and B. If line A has a fare link and line B
does not, then the fare from the fare link on line A will be factored according to the
portion of the trips that would be assigned to line A between the points of divergence.
Thus, the fare link might indicate a fare of 100 should be assessed, but only a portion
will be.
FA R E LIN KS k e y wo rd s

Ke y wo rd D e s c rip tio n

FA R E |R| Fare assessed to the links on the

statement.
The fare is accumulated in the MODEFARE
skim variable. MODEFARE is accessable
when defining work matrices under the
MATRICES control statement.

MOD E S |IVP| Modes for which the specified links apply.

Each statement must specify at least one
valid mode.

L |IVP| Links specified as fare links. Code links as

A-B, A-B, etc. Code the links directionally.
Use the keyword ONEWAY to specify if the
links are entered only one way.

ON E W A Y |?| Flag that indicates whether links are

entered as A-B and B-A:
• True — Links entered in A-B direction
only.
• False — Default value. Links entered
as A-B and B-A.
TRNBUILD Program > Control statements > FARELINKS > Example

Exam ple
FARELINKS FARE=20 MODES=1-3,7 L=1000-1001, 2000-2001
FARELINKS FARE=-10 L=8000-1010 ONEWAY=TRUE, MODES=9
FARELINKS FARE=25 L=500-510,510-511 MODES=15 ; need not be transit
TRNBUILD Program > Control statements > FILEI

FILEI
Inputs data files. Keywords include:
• NET I

• MA T I

• FA R E MA T I

FILE I k e y wo rd s

Ke y wo rd D e s c rip tio n

NET I |KF| Name of the input network file.

MA T I |KF| Name of the input trips matrix file. See

“TRIPS” on page 1089 for details.

FA R E MA T I |KFV255| This statement will cause the program

to read a file of stop-to-stop fares for
the mode of the index of this keyword.
(FAREMATI[3]=filename will enter the
data records from the file to be applied
to mode 3.) The index should be a
transit mode. The file record format is:
FromNode, ToNode, Fare, Direction.
Direction is optional and has meaning
only if it is a “1,” which means that the
fare is applied only in the direction of
FromNode -> ToNode. Otherwise
(without Direction, or Direction != 1), a
reverse fare entry is also made.

The fare matrix is searched anytime there is a path segment on a mode for which there
is a FAREMATI. Assume a path of segments:
1-100 (mode=11),
100-101 (2)
101-102 (2)
102-103 (2)
103-300 (5)
300-301 (5)
301-400 (12)
400-308 (5)
308-2 (12)
The search process begins when a new mode is boarded; a search is made for the
boarding node to the exit node where the path changes mode. In this example, the first
search is node 100 (board mode 2) to node 103 (exit mode 2). If there is an entry, the
fare will be applied. If there is no entry, a search will be made to determine if there are
entries for any combinations of the modes 100-101-102-103, that would cover the entire
string. The following node-node combinations would be searched. If a search
combination is found the fare is assessed, and the next mode is processed. If no valid
combination is found, no fare assessed. The following combinations were be searched
for mode 2:
100-103
100-102 and 102-103
100-101 and 101-103
100-101, 101-102, and 102-103
Then there would be search for mode 5 nodes 103 to node 301 (103-300-301) followed
by a search for mode 5 (400-308). Note that there will not be search for 103-308
because the path has a mode change between the segments.
Different FAREMATI keywords may point to the same file, in order to enter the same
structure for different modes. Mode mixing can not occur.
The values can be obtained in the MATRICES MW statements:
MW[] = faremat(modes...) (0 is the total of the modes.)
TRNBUILD Program > Control statements > FILEI > Example

Exam ple
FILEI NETI=?hwy.net ; ? will be replaced by current system prefix.
NETI = r:\work\?\base.net ; r:\work\ALTA\vase.net -- system prefix = ALTA
MATI = mytrip.fil ; referenced by TRIPS statement.
FAREMATI[2] = myfare.mat
TRNBUILD Program > Control statements > FILEO

FILEO
Outputs files. Keywords and sub-keywords include:
• MA T O

• N E T O - currently disabled!
m MODES
m STOPSONLY

• S U P P OR T O
m MODES
m FIXED
m ONEWAY

• LIN KO

• N OD E O

• LIN E V OLO
m ID
m FORMAT

• LIN KV OLO
m ID
m FORMAT

FILE O k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

LIN E V OLO |KF| Name of the text file where the program
writes line summary records. If an
assignment is undertaken and this file is
specified, the program writes a record for
each LINE containing the following fields:
Name, Mode, Owner, Frequency,
LineTime, LineDistance, TotalBoardings,
PassengerMiles, PassengerHours, ID.
Specify the format of the file with the
FORMAT subkeyword.

LINEVOLO FOR MA T |S| Specifies the format for writing LINEVOLO

records. Possible values:
• TXT
• CSV (or any word that begins with C)
— Indicates comma separated
values.
• T — Indicates fixed-length fields
(default value).

LINEVOLO ID |S| ID that the program writes as the last field

 in the LINEVOLO records. It may be any
length, but will be truncated to 10
characters if FORMAT=T.

LIN KO |KF| Name of database file (DBF) where

program writes all transit links and support
links. You can process this file with other
software, such as Cube Base. Each link
record contains the following variables:
• A — A-node of link
• B — B-node of link
• TIME — A-B time (hundredths of
minutes)
• MODE — Mode of link (1-255)
• COLOR — User designated drawing
color
• STOP_A — 1 = A is a stop node

• STOP_B — 1 = B is a stop node

• DIST — A-B distance
• NAME — Name of line on this link
• FREQ — Service frequency
If assignment is made, the program adds
the following variables to each link:
• SEQ — Link sequence in the line
• OWNER — Line owner
• AB_VOL — Volume
• AB_BRDA — Number of trip
boardings a A
• AB_XITA — Number of exits at A
• AB_BRDB — Number of boardings
at B

• AB_XITB — Number of exits at B

These AB_ variables contain values for
trips on the line going in the A-B direction;
the XITA and BRDB values are not related
to the VOL. An additional set of variables
(prefixed with BA_) is also included for trips
on the reverse direction line if the line is
coded as not oneway. BA_ values
reference A and B in a true sense;
BA_BRDA references A for this link (not
the A of the reverse link).

LIN KV OLO |KF| Name of the text file where program writes
link summary records. If specified,
program writes a record for each LINK
containing the following fields: A, B, Time,
Mode, Plot, StopA, StopB, Distance,
Name, Owner, [Volume,] ID. (Plot is either
a 1 or a 0 to indicate this is the best record
for this A-B to plot. Volume is not written if
assignment is not in effect.) Specify the
format of the file with the FORMAT
subkeyword.
LINKVOLO FOR MA T |S| Specifies the format for writing LINKVOLO
records. Possible values:
• TXT

• CSV (or any word that begins with C)

— Indicates comma-separated
values.
• T — Indicates fixed-length fields
(default).

LINKVOLO ID |S| ID that the program writes as the last field

in the LINKVOLO records.

MA T O |KF| Name of the file where program writes

MATRICES.

NET O |KF| Name of the file where the program writes

transit network. The program writes a
binary network of transit links. Use the
subkeywords to reduce the number of
links. This option is currently disabled.

NETO MOD E S |IVP| Modes included when writing links to the

NETO file. If no modes are designated, the
program includes all modes by default.
Currently disabled.

NETO S T OP S ON LY |?| Flag that indicates the types of transit links

the program writes to the NETO file:
• True — Program writes transit links
that connect stops only.
• False — Program writes transit links
coded on the LINE control
statements.

N OD E O |KF| Name of a database file where program

writes node records with coordinates. You
might use this file to add additional
coordinates in other software, such as the
Cube Base.

S U P P OR T O |KF| Name of the file where program writes

support links in the format of the SUPPLINK
control statement.
Use the SUPPORTO keyword to write all
the support links to a single file and in a
consistent format. After creating a valid
support links file, you can use the file to
speed up subsequent applications by
reading in this file directly and bypass
zonal access development by setting
ZONEACCESS GENERATE to false.
Essentially, this file (with all nontransit
modes), along with the LINE file(s) and the
input highway network constitute a
complete transit network.

SUPPORTO FIXE D |?| Flag that indicates how the program writes
the data fields to statements in the
SUPPORTO file:
• False — Indicates statements are
 completely free form.
• True — Indicates fixed-length fields,
providing easier browsing, but
requiring more disk space.

SUPPORTO ON E W A Y |?| Flag that indicates how the program writes

support links:
• True — Indicates program writes
each support link as A-B.

• False — Indicates program writes

truly two-way support links in low-
high format, and flags one-way links
as one-way.

SUPPORTO MOD E S |IVP| Support modes that program selects when

writing to SUPPORTO file. If you designate
no modes, the program will issue a fatal
message.
TRNBUILD Program > Control statements > FILEO > Example

Exam ple
FILEO NODEO = trnnode.dbf ; output node file
FILEO LINKO = trnlink.dbf ; output link file
FILEO MATO = ?los.mat ; output transit LOS values
FILEO LINEVOLO=linevol.csv, ID=ASSIGNB, FORMAT=CSV
FILEO LINKVOLO=linkvol.txt, ID=ASSIGNB, FORMAT=text
SUPPORTO = D:SUPPORT MODES=11-16 ONEWAY=N FIXED=Y
Result:
SUPPLINK N=1-7783 MODE=11 DIST= 30 SPEED= 2.5 ONEWAY=Y
SUPPLINK N=3-7592 MODE=11 DIST= 133 SPEED= 2.5
SUPPLINK N=3-7593 MODE=11 DIST= 20 SPEED= 2.5
SUPPLINK N=7-7688 MODE=11 DIST= 16 SPEED= 2.5
.
.
SUPPLINK N=1007-7689 MODE=11 DIST= 26 SPEED= 2.5
.
.
SUPPORTO=D:SUPPORT MODES=11-16 ONEWAY=Y FIXED=N
Result:
SUPPLINK N=1-7783 MODE=11 DIST=30 SPEED=2.5 ONEWAY=Y
SUPPLINK N=3-7592 MODE=11 DIST=133 SPEED=2.5 ONEWAY=Y
SUPPLINK N=3-7593 MODE=11 DIST=20 SPEED=2.5 ONEWAY=Y
SUPPLINK N=7-7688 MODE=11 DIST=16 SPEED=2.5 ONEWAY=Y
.
.
SUPPLINK N=1007-7689 MODE=11 DIST=26 SPEED=2.5 ONEWAY=Y
.
SUPPLINK N=7593-3 MODE=11 DIST=20 SPEED=2.5 ONEWAY=Y
.
.
TRNBUILD Program > Control statements > LINE

LINE
Defines transit lines. Keywords and sub-keywords include:
• A LLS T OP S

• COLOR

• FR E QU E N CY

• FR E QU E N CY R

• GLOB A L
m CLEAR

• MOD E

• N A ME

• N OD E S
m ACCESS
m ACCESS_C
m DELAY
m DELAY_C
m RT
m SPEED
m TF
m TIME
m XYSPD

• ON E W A Y

• R U N T IME

• S H OR T N A ME

• T IME FA C

• U S E R A 1, U S E R A 2, U S E R A 3, U S E R A 4, U S E R A 5

• U S E R N 1, U S E R N 2, U S E R N 3, U S E R N 4, U S E R N 5

• XY S P E E D

LIN E k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

A LLS T OP S |?| Flag that indicates whether nodes are

all stop nodes:
• True — Program considers all
specified NODES as stop nodes,
even if they are explicitly
 designated as non-stop nodes.
• False — Program examines
explicit node designations.

COLOR |I| Color that Cube Base uses to display

the line.

FR E QU E N CY |RV5*| Time between arrival of vehicles on

this line (also called the headway).
There must be a FREQUENCY[n],
where n is the frequency period as
defined by PARAMETERS
FREQPERIOD, or TRNBUILD will not
include the line in this transit network.

FR E QU E N CY R |RV5*| Frequency for the line in the reverse

direction. If you do not supply any
FREQUENCYR values (from either
global or statement keywords), the
program sets the entire FREQUENCYR
array equal to the FREQUENCY array.

GLOB A L |?| Flag that indicates whether the

program saves line parameters in the
line global area. When reading each
line, the program sets initial values for
many of the above variables from the
line global area. The variables set in
the line global area are: ONEWAY,
MODE, ALLSTOPS, COLOR,
FREQUENCY, TIMEFAC, XYSPEED. If
FREQUENCYR is set in the LINE
statement or in the input global area,
then it is also included in the global
area.
NOTE: Global values are not
compatible with transit-network editing
in Cube Base. Therefore, Citilabs
recommends that you not use global
values.

GLOBAL CLE A R |?| Flag that indicates whether the

program clears line global parameters
(set global ONEWAY to true) before
moving them to the line work area. To
clear the global values, but not save
the line work parameters in the line
global area, code: GLOBAL=N,
CLEAR=Y.

MOD E |I| Mode for this line; it may not conflict

with support modes used.

N A ME |S| Name of the line. It may be up to 12

characters in length, and must be
unique. The program truncates longer
names and issues a warning.
Duplicate line names will cause a fatal
error.
NOTE: If ONEWAY is false for the line,
the program generates a reverse
image line with the same name, but
with the “-” character appended to it.
 Thus, you cannot use a hyphen as the
last character in a line name.

N OD E S |IV| List of nodes that the line passes

through. Follow each node by another
node, or one of the NODES
subkeywords. Two adjacent nodes—
even if there are intervening
subkeywords— form a transit link.
Positive-numbered nodes are stop
nodes; negative-numbered nodes are
non-stopping nodes. However, if
ALLSTOPS is true for the line,
negative-numbered nodes are
considered as stops, too.
If NODES appears multiple times for the
line, the program joins the last node of
the previous node string and the first
node of the current node string to form
another link. You may separate node
numbers with spaces, commas, or
hyphens. If you insert any of the NODES
subkeywords in the string of node
numbers, you must re-enter the NODES
keyword following the subkeyword
value. To simplify the coding in such
cases, you may use the word N as an
alias for NODES.
Citilabs recommends coding the
NODES keyword as the last keyword
for the line.

NODES A CCE S S |I| Restricts access at the previous node.

Possible values:
• 0 — No restriction
• 1 — Boarding only
• 2 — Exit only
This access restriction is inverted for
the line’s reverse direction.

NODES A CCE S S _C |I| Restricts access at the previous node

and at the following nodes, until the
program encounters another
ACCESS_C or ACCESS subkeyword.
NOTE: When applying ACCESS_C, you
must make sure that the last node of a
line has exit access (0 or 2); otherwise,
the line may become useless.

NODES D E LA Y |R| Additional time delay added to the link

time. Code DELAY between two nodes.

NODES D E LA Y _C |R| Additional time delay added to all

subsequent links, until program
encounters another DELAY_C or
DELAY subkeyword.

NODES RT |R| Sets an intermediate runtime from the

beginning of the line to the previously
coded nod. The program adjusts the
accumulated time to the node to meet
this value, and adjusts all accumulated
 times to downstream nodes to account
for the adjustment at the node.
If there is more than one RT, or there is
an RT and a RUNTIME, the program
makes subsequent adjustments from
the node of prior adjustment. If there is
an RT value after the last node and a
RUNTIME value, RUNTIME prevails. If
the line is not one-way, the program
reflects RT values are reflected in the
reverse direction, but makes the
adjustment relative to the end of the
line in the reverse direction.
RT values on a line must be
increasing. If used, RUNTIME must be
greater than the last RT.

NODES SPEED |R| Sets the speed for current link and all
subsequent links in the line (from the
input network or any LINK records),
until the program encounters another
SPEED or TF subkeyword. Only specify
SPEED within a node string.

NODES TF |R| Resets the LINE TIMEFAC value from

the current link until the program
encounters another TF subkeyword or
SPEED .subkeyword.

NODES T IME |R| Sets the operation time for the link
surrounding this keyword.

NODES XY S P D |R| Resets the LINE XYSPEED value from

the prior node until the program
encounters another XYSPD
subkeyword.
Indicates the speed along any
subsequent links that are not in the
input network and that are not in any
LINK statements. XYSPEED must be
great than zero; the program cannot
compute operating characteristics for
links that have a value of zero.

ON E W A Y |?| Flag that indicates how the program

saves a line:
• True — Program only saves the
specified line.
• False — Program saves both the
specified line and its reversed
counterpart.

R U N T IME |R| Scheduled time of the line from the first

node to the last node. If specified, the
program adjusts the time on all the
links in the line so that the total of the
line’s link times matches this value.
NOTE: RT values will alter the way the
program adjusts values. Rather than
using RUNTIME, Citilabs recommends
placing an RT value at the end of the
NODES definition. Both methods result
 in the same overall line time, but using
RT is consistent with other adjustments.

SHORTNAME |S| Optional. An abbreviated name for the

line. Same as USERA5.

T IME FA C |R| Multiplier used to compute times along

the line’s links that have base times
determined from the input network or
any LINK statements. The program
applies this multiplier until
encountering another TIMEFAC, TF, or
SPEED keyword. You must place
TIMEFAC before NODES. The program
uses the last value of TIMEFAC before
NODES. After specifying NODES, use
TF to modify this multiplier.

USERA1 |S| Optional. User-defined string.

SHORTNAME maps to this variable and
cannot be used at the same time.

USERA2 |S| Optional. User-defined string.

USERA3 |S| Optional. User-defined string.

USERA4 |S| Optional. User-defined string.

USERA5 |S| Optional. User-defined string.

USERN1 |R| Optional. User-defined number.

USERN2 |R| Optional. User-defined number.

USERN3 |R| Optional. User-defined number.

USERN4 |R| Optional. User-defined number.

USERN5 |R| Optional. User-defined number.

XY S P E E D |R| Speed for a line’s link if the link does

not exist in the input network and does
have a LINK statement, but both nodes
of the link have valid coordinates
(allowing the program to compute
distances).

When reading a LINE statement, the program initializes LINE processing with the
following steps:
• If this is the first LINE statement, clear all global values, and set global ONEWAY to true.

• If CLEAR is true (no matter where it is specified on the record), clear the line global
parameters, and set global ONEWAY to true.

• Set the line’s working parameters equal to the line’s global parameters.

After reading a LINE statement without errors, if GLOBAL is true, the program saves the
current line parameters in the line’s global area for use by subsequent lines. The
program can use a LINE statement with no NAME and no NODES to reset the line’s global
area. If all FREQUENCYR values are zero, the program resets FREQUENCYR to FREQUENCY
after saving to global, so that global FREQUENCYR is not affected.
Upon encountering each link in a node string, the program determines the time and
distance that the line uses with the following decision logic:
• If the link is found in either a LINK statement or in the input network:
m
If TIME has a value, set link time = TIME

m
Else if SPEED has a value, set link time to distance/SPEED
m
Else set link time to link time * TIMEFAC

• Else if the link is not found but has coordinates:

m
If TIME has a value, set link time to TIME
m
If XYSPEED has a value, set link time to X‑Y distance/XYSPEED
m
Else produce an error

• Else the link can not be determined, so produce an error

TRNBUILD Program > Control statements > LINE > Example

Exam ple
LINE GLOBAL=y CLEAR=y MODE=3 ONEWAY=y TIMEFAC=1.2 ; setup global
LINE NAME=abc FREQUENCY=5,15,20,5 ONEWAY=n, ; basic values
N= 801-802-803 SPEED=23 N=804 805 -1805 806 807, -901,
DELAY=3 N=902,905,1006
LINE NAME=with_times NODES=801 802 803 RT=21.5 NODES=804 805 806,
RT=40 NODES=807 808 809 RT=50 NODES=9001 9002
TRNBUILD Program > Control statements > LINK

LINK
Link data for use by LINE definitions (must precede the LINE statement that includes the
link). Keywords include:
• CLE A R

• D IS T

• GLOB A L

• LIS T LIN K

• MOD E S

• N OD E S

• ON E W A Y

• SPEED

• XY A LL

• XY FA C

LIN K k e y wo rd s

Ke y wo rd D e s c rip tio n

CLE A R |?| Flag that indicates whether the program

sets the link’s global area to all zeroes
before beginning any other statement
processing. Applies no matter where
CLEAR appears on the statement.

D IS T |I| Distance for the link, usually considered

as hundredths of miles, or kilometers. The
value may not exceed 20,000.

GLOB A L |?| Flag that indicates whether the program

saves link values into the link’s global
area.
When reading the statement, the program
initializes link values from the link’s global
area, and then updates current values
based on the statement’s keyword
settings. If GLOBAL is true, the program
updates the link’s global values from the
current link values. The global area
contains time, speed, spdcode, lanes,
oneway, and modes. See “Using
TRNBUILD in Cube Voyager” on
page 1033 for notes about the use of
GLOBAL.

LA N E S |I| Number of directional lanes on the link.

See SPDCODE for more details. The value
must be 1-9.

MOD E S |IVP| Specifies the modes for the link. You may
code any combination of modes that does
 not conflict with the used transit modes. If
you code the keyword more than one time
on the statement, the program uses all the
specified modes.

N OD E S |IVP| Indicates the nodes that compose the link.

Code the link as a pair of nodes
separated by a dash.

ON E W A Y |?| Flag that indicates which links the program

saves:
• True — Program saves A-B and B-A.
• False — Program only saves A-B.

S P D COD E |I| SPDCODE for the link. If you specify

SPDCODE and LANES, the program can
compute the link speed by using the
internal SPDCAP table stored in the input
NETI network. The SPDCAP is
synonymous with SPDCLASS in the
Network program. With speed and
distance (DIST) determined, the time for
the link can be determined. The value
must be 1-99.

SPEED |R| Speed for the link. If specified, the

program does not use SPDCODE and
LANES for speed computations. The value
must be 0-999.

T IME |R| Time, in minutes, for the link. If specified,

the program does not use any keywords
associated with speed. The value must be
0-999.

The LINK statement provides information about links that the program uses for transit
lines and that do not exist in the input network or have values that need to be revised.
The program stores these links separately does not consider them to be part of the
network. Because the program stores these links with other data, searching for them can
be inefficient. Because the program searches every link on a LINE statement,
considerable time could be spent in the search process. You can reduce the search time
if the program reads all the LINK statements at one time and saves them in a contiguous
area. Every link must have at least a distance, a time (or speed), and a specified mode.
TRNBUILD Program > Control statements > LINK > Example

Exam ple
LINK GLOBAL=y CLEAR=y MODES=1-10 ONEWAY=n
LINK NODES=1001-1002 DIST=100 SPEED=22.5
LINK DIST=250 TIME=15.5 NODES= 2003 - 3015 ONEWAY=y
TRNBUILD Program > Control statements > MATRICES

MATRICES
Output matrix definitions. Keywords include:
• N A ME

• MW [ ]

MA T R ICE S k e y wo rd s

Ke y wo rd D e s c rip tio n

N A ME |SV| Name of extracted level-of-service matrix written to FILEO

MATO. Must be unique.

MW |NV| Specifies an expression solved for a matrix row. The program

skims each I-J path to obtain certain values from the path,
which the expression may use. Specifically, expressions may
use the following values:
• BOARDS — Number of transit boardings
• IWAIT — Wait time for the initial boarding
• MODEI — Mode of the link out of I
• MODET1 — First transit mode used
• NODE0* — First node of each transit mode
• NODEL* — Last node of each transit mode
• TIME** — Total time for each mode
• DIST** — Distance for each mode
• XWAIT** — Total wait time for each mode boarded
(excluding IWAIT)
• XPEN — Sum of XPEN values (FACTOR control
statement) assessed in the path

• XFARE — The sum of the XFARE values (from FARE

control) assessed
• MAXXFARE — The highest XFARE assessed
• FARE** — The total mode fare for each mode
• MODEFARE — The accumulation of:
m All mode fares as input via the FARE control
(MODEFARE keyword), and
m All mode fares as input via the FARELINKS control
(FARE keyword)

• MAXMODEFARE — The highest single-mode fare

assessed
• FAREMAT** — The sum of fares as input via FAREMATI
for each mode
• STEPFUNC*** — A function to lookup discrete values in
a curve
* Requires a single argument; the argument is mode.
 ** Requires one, or more, arguments: the arguments indicate
which modes are to be added to form the result. For example:
TIME(1,2,3,5) will return the sum of time for modes 1-3, and
5. If a single argument is used, it may be 1000 (all modes),
1001 (all transit modes), 1002 (all non-transit modes), or 0
(same as 1000). Ranges are not allowed; they are treated as
numeric subtraction. Thus coding TIME (1-5) will be an
error, because the parser will treat that as TIME (-4). TIME (5-1)
will result in TIME(4).
(continued)

MW *** STEPFUNC is a function that scans a set of increasing X

(continued) values to obtain a Y value. The value that is tested against the
X values is the first argument to the function. The value most
likely will be one of the above names with appropriate
arguments. There must be an odd number of arguments to the
function, and the X values must be ascending. The primary
purpose of this function is to extract distance or time based
fares, but it might have other uses. MW[8] in the example
below illustrates how to extract fares based upon distance.
The mode 4 distance will be checked against the X,Y curve
that is supplied in the function arguments. The result will be
either 0, 100, 150, 200, or 300. The function will determine which
X increment the value falls within and return the Y associated
with the lower X. If the value is less than, or equal to, the first X,
the result will be 0. In the example, a distance greater than 200
but less than, or equal to, 300 will result in a fare of 150, and
any distance greater than 500 will result in 300. A boarding fare
could be assessed by coding the first point as 0,fare. (dist(4,5),
...) is valid and could also be coded as (dist(4)+dist(5),...).
Each MW must have an index (if not specified, the default is 1).
TRNBUILD Program > Control statements > MATRICES > Example

Exam ple
MATRICES MW[1] = BOARDS,
MW[2] = TIME(1,2,3,4,5,6,7,8,9,10), ; total transit time
MW[3] = dist(11,13,14,15), ; total walk time
MW[4] = (IWAIT + TIME(0) + XWAIT(0) + XPEN) * 0.01, ; total time
MW[5] = NODEI, ; mode of access
MW[6] = NODE0(8), ; first boarding rail station
MW[7] = NODEL(8), ; last alighting rail station
MW[8] = STEPFUNC(DIST(4), 100,100, 200,150, 300,200, 500,300),
NAME = BOARDS, TOTAL_TIME, TOTAL_DIST, TTIME_MIN, ACCESS,
NAME[6] = RAIL1, RAIL2
TRNBUILD Program > Control statements > MULTIACCESS

MULTIACCESS
Multiaccess assignment keywords, including:
• MA XT IME D IFF

• MA XP CT D IFF

The presence of either of these keywords triggers the multiaccess process discussed in
“Path building” on page 1037.
MU LT IA CCE S S k e y wo rd s

Ke y wo rd D e s c rip tio n

MA XT IME D IFF |R| Maximum time difference (in minutes)

allowed between the best I-J path and
any other I-J path in order to include the
other path in the multiaccess
assignment.

MA XP CT D IFF |R| Maximum time difference (relative to

the best I-J time) allowed between the
best I-J path and any other I-J path in
order to include the other path in the
multiaccess assignment.
TRNBUILD Program > Control statements > MULTIACCESS > Example

Exam ple
MULTIACCESS MAXTIMEDIFF=3, MAXPCTDIFF=5
; any I-J path within 3 minutes of the best time will be included
; any I-J path within 5 percent of the best time will be included
TRNBUILD Program > Control statements > PARAMETERS

PARAMETERS
General parameters. Keywords include:
• B U ILD P A T H S

• FR E QP E R IOD

• LIS T IN P U T

• MA XP A T H T IME

• MA XR U N T IME

• ON LIN E

• P A T H S T Y LE

• S E QS IZE

• U S E R U N T IME

• W A LKS P E E D

• XY FA CT OR

• ZON E MS G

P A R A ME T E R S k e y wo rd s

Ke y wo rd D e s c rip tio n

B U ILD P A T H S |K?| Flag that controls ILOOP processing

and path building:
• True — Default value. Program
processes the ILOOP and
builds paths.

• False — Program skips the

ILOOP and builds no paths.

FR E QP E R IOD |KI| Specifies the processed period of

the day. Process only uses the lines
that contain a
FREQUENCY[FREQPERIOD]. The
value must be 1-5. Default is 1.

LIS T IN P U T |K?| Flag that controls the printing of

control statements:
• True — Subsequent statements
listed to system printer file.
• False — Subsequent
statements not listed to system
printer file.
Insert this keyword to reduce volume
printed by suppressing certain types
of input.

MA XP A T H T IME |KR| Perceived time limit for path

 selection. Program does not save
paths that exceed this value.
Because the path-building routine
processes many combinations of
lines, paths with rather long times will
be examined. You can reduce
computing time by precluded
excessively long routes from
examination. The value may not
exceed 655. Default is 120.

MA XR U N T IME |KR| Maximum run time length. The

program issues a warning for lines
with run times that exceed this value.

ON LIN E |KI| Controls the listing of statements to

the console during input reading.
With a value of 1, the program lists
every statement. Though useful for
debugging, this can take excessive
time. For large input files, set to a
larger value to reduce the number of
statements.

P A T H S T Y LE |KI| Path selection method used.

• 0 — Default value. Selects
paths by saving the best paths
to every node for every mode
that accesses the node.
• 1 — Saves only the single best
path into a node. This method
reduces path-building time
(one-third or one-quarter the
length of the default method)
and uses less memory.
However, this method can
produce problems if certain
mode-to-mode combinations
are precluded, or restricted,
due to transfer penalties.

S E QS IZE |KI| Number of cells used in the path-

building sequencing table. Changing
the value might result in somewhat
faster pathbuilding times, but that
cannot be guaranteed. Normally, it
should not be revised, unless you
are processing relatively small
network, and MAXPATHTIME is set
rather low. Larger values result in
more memory use (3 bytes per
value). The value must be 2000-
32767.

U S E R U N T IME |K?| Flag that controls RUNTIME and RT

values in LINE control statements:
• True — Default value. Program
implements RUNTIME and RT
values.
• False — Program ignores
RUNTIME and RT values.
W A LKS P E E D |KR| Speed used for walk links in the
nontransit segment of the network.
Because there is no specific walk
mode, the program only uses this
value for links with a distance but no
time. The value must be 0.1-99.
Default value is 2.5.

XY FA CT OR |KR| Conversion factor for coordinate

distance to network distance. The
program uses for LINE and
SUPPORT links when appropriate.
The program only applies this factor
to those situations that follow the
input of this keyword. You may
change the value dynamically. The
program automatically sets this
factor when it reads the input network.
The program computes the value by
dividing the sum of the link
coordinate distances by the sum of
the link distances. The keyword
value takes precedence over the
network-computed value, even if the
keyword is input prior to the reading
the network.

ZON E MS G |KI| Frequency that the system writes

zonal timing messages to the
console. This keyword is relevant
only for those who start the system
with RUNTPP. Specify frequency as
number of zones. For example, with a
value of one, the program writes a
message for every zone; with a
value of 10, the program writes a
message for every 10 zones. Larger
values of ZONEMSG can reduce
running times when running the
system in console mode. Default
value is 1.

The keywords on this statement are all “trigger” keys; you need not code the control
word PARAMETERS. You can input the values in any order, and, for most of the keywords,
if they appear multiple times, the program uses the latest value.
TRNBUILD Program > Control statements > PARAMETERS > Example

Exam ple
PARAMETERS MaxRunTime=120 ; flag long lines
MaxPathTime=180 ; no paths greater than 3 hours
WALKSPEED=4.1 ; walk speed in kph
USERUNTIME=n ; ignore LINE RUNTIME and RT values
TRNBUILD Program > Control statements > PHASE1

PHASE1
Initial parameters. Keywords include:
• H W Y T IME

• LIN KD U MP

• MA XN OD E

• W OR KR A M

P H A S E 1 k e y wo rd s

Ke y wo rd D e s c rip tio n

H W Y T IME |KS| Input network variable used for the link

times when building the transit network.
The method for obtaining the actual link
time depends on the name of the variable
specified. The program uses the following
logic to obtain each link’s time:
If HWYTIME=SPDCLASS
if LANES is in the network,
time = dist/speedtab(lanes,spdclass)
else time = 0
Else if HWYTIME=SPEED
time=distance/speed
Else if HWYTIME=network variable
time = variable * 100.
Else (HWYTIME not specified)
if TIME is in the network
time = TIME*100
else time = 0;
End if
The program maintains the time as an
integer value, assumed as xx.xx minutes.

LIN KD U MP |KI| Specifies the number of links to be printed

for inspection. Used primarily for
debugging purposes.

MA XN OD E |KI| Highest node number in the transit

network, if it is to have node numbers
higher than the input network. The value
must be larger than the highest node in the
input network and less than 32,761.

W OR KR A M |KI| Amount of RAM initially allocated to

certain work areas. In most situations, the
default is adequate, and if insufficient, the
program tries to internally adjust it. But
some situations may require a larger initial
allocation. When more initial allocation is
needed, the program terminates with a
message indicating the need to restart
with a larger allocation. The value must be
 10,000-500,000. Default value is 300,000.

The keywords on this statement are all “trigger” keys; you need not code the control
word, PHASE1 need not be coded. These keywords are valid only prior to the opening of
the input network. Therefore, you must input them early in the input stream.
TRNBUILD Program > Control statements > PHASE1 > Example

Exam ple
MAXNODE=22000 HWYTIME=trantime ; increase highest node
PHASE1 MAXNODE=2100
TRNBUILD Program > Control statements > PNR

PNR
Specifies park-and-ride link generation. Keywords include:
• CLE A R

• GLOB A L

• LOT MOD E

• MA XT IME

• MOD E

• N OD E

• ON E W A Y

• S E LE CT

• T IME

• ZON E S

P N R k e y wo rd s

Ke y wo rd D e s c rip tio n

CLE A R |?| Flag that indicates whether to set the

global area to all zeroes before any other
statement processing.
Reset happens regardless of the location
of CLEAR in the statement.

GLOB A L |?| Flag that indicates whether to set PNR

values into the PNR global area.
When reading the statement, the program
sets the values from the link global area,
and then updates current values based on
statement keywords. If GLOBAL is true, the
program updates global values from the
current values. The global area contains
time, cost, oneway, distfac, mode, and
lotmode. See “Using TRNBUILD in Cube
Voyager” on page 1033 for notes about the
use of GLOBAL.

LOT MOD E |I| Mode assigned to the lot link. The value
must not conflict with any transit modes
being used.

MA XT IME |R| Maximum time for any generated zone-to-

node links. If a potential link between a
zone and a PNR node exceeds this value,
the program does not connect the zone to
the node. This is a general parameter; the
program only uses the last value input.
Appropriate values might reduce path-
building time in the PNR access-
development phase.

MOD E |I| Mode assigned to the zone-to-node

 support link developed. The value must
not conflict with any transit modes being
used.

N OD E |IVP| Node to which the program generates an

access link from each zone specified in
ZONES via the PNR access-development
process. That process builds the best
highway-time path from each designated
zone to this NODE using only links that exist
in NETI. Normally, NODE is a transit stop
node. However, at some locations, the
NODE might not be a stop node, but merely
a drop-off node, or the entrance to a
parking lot associated with a transit-stop
node. To accommodate the latter
scenario, append a second node to the
first NODE value (NODE-NODE); the
program generates an additional support
(lot) link between the two nodes. In either
case, the nodes must exist in the highway
network; simply having coordinates for the
nodes will suffice for generating the lot link,
but if the first node does not have NETI
connections, the program cannot generate
a path to it. In the two-node option, the first
node should not be a transit stop node,
and the second node should be. The
program will issue warning messages if
the inputs violate these rules. The program
obtains the lot-link parameters from the
statement’s TIME, ONEWAY, and
LOTMODE values. The program internally
maintains each zone-to-node link and
each generated lot link as a support link.
Citilabs recommends that you enter lot
links as separate support links rather than
appending a second node and having the
program generate a lot link.

ON E W A Y |?| Flag that indicates whether to configure

generated (zone-to-node and lot) links as
one-way.

S E LE CT |?| Flag that indicates whether to limit access-

link generation, possibly speeding the
process:
• True — Program limits access-link
generation to the zones that appear
in the select array (product of
SELECT I and/or J). If the SELECT
statement specifies no I or J, the
select array selects all zones for I or
J.
• False — Program generates access
links for all zones.

T IME |R| Time assigned to the lot link.

ZON E S |IVP| Zones that the PNR access development

process connects to the NODE. The
program builds a set of highway-time
paths from each of the zones. For zones
 that can reach the NODE within the
MAXTIME, the program generates a
SUPPLINK between the zone and the
NODE. The program assigns the
generated link’s mode from MODE and its
time from the path.

After reading any input PNR statements, the program automatically tries to generate PNR
access links. However, you need not input PNR statements to enter PNR-access and lot
links in the transit network. You can input these links directly via SUPPORT statements.
TRNBUILD Program > Control statements > PNR > Example

Exam ple
PNR MODE=12 LOTMODE=13 ONEWAY=Y MAXTIME=30 GLOBAL=Y
; establish general global values for subsequent PNR's
PNR NODE=8001 ZONES=1-15,48,125,138-173
PNR node=9001-10001 ZONES=16-47,358
TRNBUILD Program > Control statements > REPORT

REPORT
Report requests. Keywords and sub-keywords include:
• CA P A CIT Y

• LIN E S

• LIN E S T R IN G

• LIN E V OL
m LINESORT
m MODES
m STOPSONLY

• LIN KV OL
m FULL
m MODES
m STOPSONLY

• N OD E V OL
m MODES

• R U N T IME A D J

• SPEED

R E P OR T k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

CA P A CIT Y |?| Flag that indicates whether to

produce a report of the capacities
stored in the input highway
network’s SPDCAP table.

LIN E S |SV| Sort order of transit-line summary

report. Indicate fields to sort on or
specify “Order” to present report in
original input order. Report fields
include: Name, Mode, Frequency,
Time, Dist, Speed, Boarding and
XFER volumes.

LIN E S T R IN G |S| String mask for lines included in the

line-strings report.
The program reports line strings in
a three-column format: node
accum_time accum_dist. Rows
with empty nodes indicate an
embedded parameter (speed,
time, rt, etc.) The report prints the
lines side-by-side to reduce print
volume, but large networks can
generate a very large report if
many lines are selected.
 Enter a mask comprised of
characters, ?, #, and *:
• # indicates any digit
• ? indicates any character

• * forces a match.
To include * or - in the mask,
enclose the mask within " ". The
program selects the number of
characters equal to the lesser of
the length of the mask or the name.
For example, to see all lines, enter
a single ?. To report lines that
begin with the letter A and have a 3
in the fourth position, enter A??3.

LIN E V OL |?| Flag that indicates whether to

produce line-volume report
showing line boardings, volumes,
and exits resulting from trip
assignment.
The report lists each line along with
a summary of the line’s boardings,
passenger distance, and
passenger hours. The summaries
depend on the assignment
options. The line-node listing
shows all the trip activity (Boards,
Volumes, Exits) at each stop node.

LINEVOL LIN E S OR T |?| Flag that indicates order of line-

volume report:
• True — Write report sorted by
line name
• False — Write report in input
order

LINEVOL MOD E S |IP| Transit modes included in line-

volume report. If not specified,
report includes all transit modes.

LINEVOL S T OP S ON LY |?| Flag that indicates whether to

restrict the line-volume report to
stop-to-stop links only:
• True — Line-volume report
only includes stop-to-stop
links; the report does not
consider intermediate nodes
to be link nodes. If the
program does not
accumulate boards and exits
during assignment, the
program automatically sets
this keyword to true.
• False — Line-volume report
includes all links.

LIN KV OL |?| Flag that indicates whether to

produce link-volume report
showing link volumes, boards, and
exits resulting from trip assignment.
 Report only includes links with
values unless you set FULL to true.

LINKVOL FU LL |?| Flag that indicates whether to

include all links— even zero-volume
links— in the link-volume report:
• True — Include all links.
• False — Default value.
Include only used links.

LINKVOL MOD E S |IP| Transit modes included in link-

volume report. If not specified,
report includes all transit modes.

LINKVOL S T OP S ON LY |?| Flag that indicates whether to

restrict the link-volume report to
stop-to-stop links only:
• True — Link-volume report
only includes stop-to-stop
links; the report does not
consider intermediate nodes
to be link nodes
• False — Link-volume report
includes all links.

N OD E V OL |?| Flag that indicates whether to

produce node-volume report
showing boarding and exiting
activity at nodes. The program
sorts the report by node, mode,
and line. The report provides totals
at each node and for the network.

NODEVOL MOD E S |IP| Transit modes included in node-

volume report. If not specified,
report includes all transit modes.

R U N T IME A D J |?| Flag that indicates whether to

produce report showing network
time versus runtime for lines with a
coded RUNTIME:
• True — Default value.
Produce report.
• False — Do not produce
report.
NOTE: The program always
produces this report for lines with a
run time that exceeds
MAXRUNTIME.

SPEED |?| Flag that indicates whether to

produce a report of the speeds
stored in the input highway
network’s SPDCAP table.

The REPORT statement specifies which reports the program prints and suppresses.
Some reports are automatically suppressed if the program does not complete trip
assignment. If you restrict assignment (do not accumulate all volumes, boards, or exits),
some reports will be incomplete.
NOTE: Some reports can be quite voluminous.
TRNBUILD Program > Control statements > REPORT > Example

Exam ple
REPORT CAPACITY=n SPDCODE=y RUNTIMEADJ=y
REPORT LINKVOL=y FULL=y ;list all links in the network.
REPORT LINEVOL=y, LINESORT=y, STOPSONLY=n
REPORT LINES= Name, Mode, ORDER;
REPORT LINESTRING=MU?## ;report all MUNI numbered lines
REPORT NODEVOL=y MODES=1,3-7,10
TRNBUILD Program > Control statements > SEGLIMITS

SEGLIMITS
Limits nontransit travel segments during path building (not during network construction).
Keywords include:
• MA XD IS T

• MA XT IME

• MOD E S

S E GLIMIT S k e y wo rd s

Ke y wo rd D e s c rip tio n

MA XD IS T |I| Maximum distance (in 1/100 miles) allowed

in a segment.

MA XT IME |R| Maximum time (in minutes) allowed in a

segment.

MOD E S |IP| Modes that comprise the segment.

During path building, some paths may tend to use a successive series of nontransit
links. While each link itself has an acceptable time or distance, the sum of successive
link times may not be acceptable. This may be especially true for walk links. For
example, you might consider a walk time of 15 minutes to be acceptable. If the network
connects two 15-minute walk links, the path could use the links successively and
generate a 30-minute walk segment. A SEGLIMITS statement can preclude this from
happening. You may specify up to 20 SEGLIMITS statements. Each statement contains
the restricting modes, and either a MAXDIST or MAXTIME limit. If the statement specifies
both MAXTIME and MAXDIST, the program generates two segment limits.
TRNBUILD Program > Control statements > SEGLIMITS > Example

Exam ple
SEGLIMITS MODES=101,13 MAXTIME=22.5
; Any combination of mode 101 and mode 13 will be restricted to 22.5 minutes
SEGLIMITS MODES=212 MAXDIST=600 ; No mode 212 link > 6 miles
TRNBUILD Program > Control statements > SELECT

SELECT
Zone and miscellaneous selection. Keywords include:
• A CCE S S MOD E S

• I

• J

• IJ

• S KIP MOD E S

• T R A CE

S E LE CT k e y wo rd s

Ke y wo rd D e s c rip tio n

A CCE S S MOD E S |KIVP| Nontransit modes that the

program may use for the outbound
link from a zone when building
paths.
Use to specify which modes may
be used for initial access. For
example, if the zone has both
walk- and drive-mode outbound
links, you can restrict path
development to just one of those
types by specifying the desired
mode with ACCESSMODES.
Specified values must be valid
nontransit modes.

I |KIPV| Origin zones to be processed.

If not specified, the program
processes all I zones.

J |KIPV| Destination zones to be

processed.
If not specified, the program
processes all J zones.

IJ |Ks| Specific zone-to-zone paths be

reported. The expression may
include any combination of I and J.
The program reports only
processed I-J pairs (that is, origins
and destinations specified in I and
J).

S KIP MOD E S |KIPV| Modes not included in path

building.
Use to preclude a certain type of
access.

T R A CE |Ks| Zone-to-zone paths to be

reported. The expression may
include any combination of I, J and
BOARDS. BOARDS is the number
of transit boardings made during
the path. If the program traces a
path and statements request
level-of-service matrices, the
program also lists LOS values
following the path.
TRNBUILD Program > Control statements > SELECT > Example

Exam ple
SELECT I=1-20,55,37-50,83, J=1-99,512
SELECT TRACE=( (I=1-10 && J=50-75,387 && BOARDS > 2) ||
(J=1-10 && I=50-75,387 && BOARDS > 2) )
SELECT SKIPMODES=12 , IJ=( (i=1-5 & j=100-120) || (i=100-120 & j=1-5) )
SELECT ACCESSMODES=11-16; all zone connect modes compete
TRNBUILD Program > Control statements > SUPPLINK

SUPPLINK
Direct input of nontransit links. Keywords include:
• D IS T

• MOD E

• N OD E S

• ON E W A Y

• SPEED

• T IME

• XY A LL

• XY FA C

This statement is compatible with Cube Base transit line editing, whereas SUPPORT is not
totally compatible. Citilabs recommends using this statement for single links rather than
using SUPPORT. SUPPLINK is a subset of SUPPORT; SUPPLINK does not support some of the
SUPPORT keywords. This section lists the supported keywords.

The program writes FILEO SUPPORTO records as SUPPLINK records.

S U P P LIN K k e y wo rd s

Ke y wo rd D e s c rip tio n

D IS T |I| Distance (in 100th of units) to be assigned to

the link.

MOD E |I| Mode assigned to the link. The value may

not conflict with transit modes being used.

N OD E S |IP| Nodes of a support (nontransit) link. The link

must have a valid distance. See “Logic for
obtaining link distance” on page 1088 for a
description of the logic used to obtain the
distance. N is an alternate form for this
keyword.

ON E W A Y |?| Flag that indicates whether to save link in

one or both directions:
• True — Save the generated links as
one-way links (a-b only).
• False — Default value. Save the
generated links as two-way links (a-b
and b-a).

SPEED |R| Speed used for computing the link time.

T IME |R| Travel time for the link.

XY A LL |?| Flag that indicates whether to obtain link

distances from coordinates:
 • True — Compute link distances directly
from the coordinates, even if the link
exists in the input network.
• False — Default value. Determine
distance from the input network if the
links in the input NETI network,
otherwise use distance specified by
SUPPLINK DIST.

XY FA C |?| Flag that indicates whether to obtain link

distances from coordinates if other methods
fail:
• True — Default value. Compute link
distances from the node coordinates if
the other distance-obtaining
processes fail. See “Logic for
obtaining link distance” on page 1088.
• False — Generate a fatal error if other
distance-obtaining processes fail (that
is, if XYALL=F and the link is not in the
input network and SUPPLINK DIST is
not defined).

When a SUPPLINK statement contains both TIME and SPEED, the program sets link time to
TIME rather than calculating link time from DISTANCE and SPEED.
TRNBUILD Program > Control statements > SUPPLINK > Example

Exam ple
SUPPLINK MODE=13, SPEED=60, N=21-22 DIST=300
SUPPLINK NODES=21-22 MODE=15 DIST=500 TIME=20
TRNBUILD Program > Control statements > SUPPORT

SUPPORT
Direct input of nontransit links. Keywords include:
• CLE A R

• D IS T

• GLOB A L

• LIS T LIN K

• MOD E S

• N OD E S

• ON E W A Y

• SPEED

• XY A LL

• XY FA C

S U P P OR T k e y wo rd s

Ke y wo rd D e s c rip tio n

CLE A R |?| Flag that indicates whether to set the global

area to all zeroes before any other
statement processing.
Occurs no matter where CLEAR appears on
the statement.

D IS T |I| Distance assigned to a link generated in a

node string, if the string generates only one
link.

GLOB A L |?| Flag that indicates whether to update the

support global area with values from the
SUPPORT statement:
• True — The program updates global
area values with the current values set
in the SUPPORT statement.

• False — The program retains values in

the support global area.
The global area contains DIST, LISTLINK,
MODES, ONEWAY, SPEED, XYALL, and
XYFAC.
NOTE: Global values are not compatible
with transit-network editing in Cube Base.
Therefore, CItilabs recommends that you not
use global values.

LIS T LIN K |?| Flag that indicates whether to list all the
generated links. Use primarily for
debugging.

MOD E S |IV| Modes assigned to the generated links on

this statement. The values must not conflict
 with transit modes being used.

N OD E S |IV| String of nodes (links) used as support

(nontransit) links. Each link in the string must
have a valid distance. See “Logic for
obtaining link distance” on page 1088.
Within a node string, the program generates
a link from each positive node to the next
positive node in the string. Negative nodes
indicate intermediate nodes that the
program only uses for computing distance
and time. For example, if you input 100
-101 -102 103 104. the program
generates links 100-103 and 103-104. The
program computes the distance and time for
link 100-103 from links 100-101, 101-102, and
102‑103.
Generated links are valid for the modes
specified in MODES. You can input the same
link on different SUPPORT statements with
different distance and time if you specify
different modes.
A node string terminates at the end of the
SUPPORT statement or at the next keyword.
Input another node string with another
NODES keyword.

ON E W A Y |?| Flag that indicates whether to save link in

one or both directions:
• True — Save the generated links as
one-way links (a-b only).
• False — Default value. Save the
generated links as two-way links (a-b
and b-a).

SPEED |R| Speed used to compute the link times for all
generated links.

XY A LL |?| Flag that indicates whether to obtain link

distances from coordinates:
• True — Compute link distances directly
from the coordinates, even if the link
does exist in the input network.
• False — Default value. Determine
distance from the input network if the
links in the input NETI network,
otherwise use distance specified by
SUPPORT DIST.

XY FA C |?| Flag that indicates whether to obtain link

distances from coordinates if other methods
fail:
• True — Compute link distances from
the node coordinates if the other
distance-obtaining processes fail. See
“Logic for obtaining link distance” on
page 1088.
• False — Generate a fatal error if other
distance-obtaining processes fail (that
is, if XYALL=F and the link is not in the
input network and SUPPORT DIST is
not defined).
TRNBUILD Program > Control statements > SUPPORT > Logic for obtaining link distance

Lo gic fo r o btaining link distance

• If DIST specified (or set in global area) and there is only one link in a string, then set
distance = DIST.

• Else if XYALL=Y, then:

m
If nodes have valid coordinates, compute distance from the coordinates
m
Else generate link error

• Else XYALL=N so the program computes the distance using the first successful method:
1. From A-B link in network
2. From B-A link in network
3. If XYFAC=Y, compute distance from the coordinates
4. Generate link error

End if
TRNBUILD Program > Control statements > SUPPORT > Example

Exam ple
SUPPORT MODES=13, SPEED=60, N=21-22 N=21-22-23 GLOBAL=Y DIST=3
SUPPORT N=21 -22 -23 24 N=24-25 GLOBAL=N CLEAR=Y MODES=11 XYFAC=Y
SUPPORT N=21 -22 -23 24 MODES=13-15 DIST=5 SPEED=0
TRNBUILD Program > Control statements > TRIPS

TRIPS
Specify trip processing. Keywords and sub-keywords include:
• MA T R IX
m ASSIGN, with sub-keywords VOLUMES, BOARDS, EXITS, OLINKS

T R IP S k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

MA T R IX |S| FILEI MATI file used to obtain trip matrix. The

program uses this trip matrix as a filter during
path processing: The program only processes
paths for zonal pairs for which their are trips.
You may specify the file name using two
methods:
• MI.#.m — Preferred method. Program
obtains file name from the FILEI MATI[#]
value.
• MI.m — Program obtains file name from the
one MATI file specified.
For either method, m specifies the name or
number of the processed matrix. For non–TP+
input files, you must specify the desired matrix by
number.
If the subkeyword ASSIGN is true, the program
assigns trips to the network. If the subkeyword is
not coded, there is no zonal filtering.

MATRIX A S S IGN |?| Flag that indicates whether to assign TRIPS

matrix values to the network. When set to true,
program sets all its subkeywords to true by
default.
ASSIGN has several subkeywords:
VOLUMES
|?|
Flag that indicates whether to accumulate
link volumes during assignment.
BOARDS
|?|
Flag that indicates whether to accumulate
separate boarding volumes for each stop
node.
EXITS
|?|
Flag that indicates whether to accumulate
separate exit volumes for each stop node.
OLINKS
|IPV|
Required links in a trip. A trip must contain
the specified links for the program to assign
that trip.
 Specify one or more required links as node
pairs. You may enter a link may be entered
in both directions, or you may enter a
negative B node to indicate selection in
either direction (A-B or B-A). The program
does not check if the links exist before
processing. You may specify support links.
You cannot specify modes or lines.
Link nodes must be adjacent if on a line.
Thus, OLINKS=200‑400 would be invalid if
LINE NODES is 100, 200, -300, 400,
because 200 does not connect directly to
400. But, OLINKS=200-300 would be valid.
If a path segment consists of combined
lines, and only some lines in the segment
use a selected link, the program restricts
assignment to trips assigned to those lines.

Without a TRIPS control statement, the program does not process any trip matrix. Trip
processing restricts paths to only those zonal pairs with actual trips. When the program
encounters the MATRIX keyword, the program sets the default values of ASSIGN and its
subkeywords to false. If the program also encounters ASSIGN, the program sets the
default values of its subkeywords to the same value as ASSIGN. If ASSIGN is set to true,
the program observes any settings of other subkeywords. If ASSIGN is set to false, the
program ignores its subkeywords. Only set the values of ASSIGN subkeywords differently
than the ASSIGN value if you have insufficient memory to accumulate all data at one time.
TRNBUILD Program > Control statements > TRIPS > Example

Exam ple
TRIPS MATRIX=MI.1.3, ASSIGN=y, BOARDS=n,EXITS=n
TRIPS MATRIX=?14.1 ; matrix 1 from xxxx14.DAT -- MINUTP notation
TRIPS MATRIX=MI.1.3, ASSIGN=Y, OLINKS=5000-5001,5100-5101,5101-5100
TRIPS MATRIX=MI.1.3, ASSIGN=Y, OLINKS=5000-5001,5100--5101 ; same
TRNBUILD Program > Control statements > XFERGEN

XFERGEN
Generate transfer support links. Keywords include:
• MOD E

• MA XD IS T

Given this statement, the program generates support links of the specified modes using
only NETI links. The program builds paths from each stop node to all other stop nodes
within the specified distances. The program generates a distance for the support link
and computes the time from WALKSPEED. The program generates one support link for
each connection. For example, if a path from stop 100 to stop 200 uses four NETI links,
the program generates one support link from 100 to 200.
XFE R GE N k e y wo rd s

Ke y wo rd D e s c rip tio n

MOD E |I| Mode assigned to the generated links.

The value must be a nontransit mode.

MA XD IS T |RV255| Maximum distance to search for a stop

node for the mode. The keyword’s index
[i] indicates the mode.

Example: Suppose stop 100 services modes 1 and 3, stop 200 services mode 3 and 6,
and the stops are 50 distance units apart. If MAXDIST[3]=25 and MAXDIST[6]=50, the
program will connect these stops. The largest MAXDIST of any of the serviced nodes
defines the limit for a connection. If you use multiple XFERGEN statements or repeat a
MAXDIST keyword, the program uses the last value. A typical statement might be:
XFERGEN MODE=11, MAXDIST=10*33, MAXDIST[8]=50
; allow longer walk to Mode 8

Use care when specifying MAXDIST; you could generate more links than TRNBUILD can
handle. The link paths will pass through centroids, if that is the best path between
nodes. To examine the generated links, use a SUPPORTO statement to induce the
program to write a file of SUPPLINK records.
TRNBUILD Program > Control statements > XY

XY
Insert or revise coordinates. Keywords and sub-keywords include:
• N OD E
m X
m Y

• XY

XY k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

N OD E |I| Node for which the

statement defines
coordinates. The value
must be between 1 and
MAXNODE (or highest node
in the network).

NODE X |I| X-coordinate for NODE. The

value must be 1-
2147483647.

NODE Y |I| Y-coordinate for NODE. The

value must be 1-
2147483647.

XY |IV| Vector of coordinates for

one or more nodes.
Use this keyword as
alternate to the NODE
keyword. Indicate the first
node in the index and set
the keyword value to pairs
of comma-separated
coordinates (X-coordinate,
Y-coordinate); uses spaces
to separate additional pairs
of coordinates. The
program automatically
increments the node for
additional coordinates.
TRNBUILD Program > Control statements > XY > Example

Exam ple
XY NODE=137, X=234123, Y=327500, NODE=138, X=234123, Y=327510
XY XY[137]= 234123,327500 234123,327510 ;Same as above
TRNBUILD Program > Control statements > ZONEACCESS

ZONEACCESS
Zonal access development (not PNR) parameters. Keywords include:
• GE N E R A T E
m DIRECTION
m LIST
m MAXDIST
m MAXLINKS
m MAXSTOPS
m MODE
m SELECT

• LIN K
m DIST
m MODE
m ONEWAY

ZON E A CCE S S k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

GE N E R A T E |?| Flag that indicates whether to

generate zonal-access support
links.

GENERATE D IR E CT ION |I| Direction of all zonal-access links:

• 1 — Program generates links
from zone to node (origin
access) only.
• 2 — Program generates links
from node to zone
(destination access) only.
• 3 — Default value. Program
generates both origin and
destination links.

GENERATE LIS T |?| Flag that indicates whether to list

generated links as they are
generated.
Useful for debugging, the list
shows the zone, node, distance,
time, and accessible modes at the
node. Because this list could be a
rather, Citilabs recommends
generating the list only with small
networks, or in conjunction with
SELECT. You can also use the
FILEO SUPPORTO statement to
write a file with these links.
GENERATE MA XD IS T |IV255*| Maximum distance of a zonal
access link between a zone and
an access node.
You may enter a distance for each
transit mode. The value must be 0-
500. Default value is 33.

GENERATE MA XLIN KS |I| Maximum number of links

searched beyond the origin zone
during zonal-access path building.
You only need to restrict the path
builder if you developed the input
network with a specific coding
scheme that requires limited
searching. In most cases,
MAXDIST will help to reduce path-
building time, but a reasonable
value for MAXLINKS can also
possibly reduce path-building
time.
The value must be 1-30. Default
value is 20.

GENERATE MA XS T OP S |IV255*| Maximum number of access links

allowed for any zone to each
mode.
The value must be 0-20. Default
value is 5.

GENERATE MOD E |I| Mode assigned to the generated

links.
You must code this keyword. The
value may not conflict with transit
modes being used.

GENERATE S E LE CT |?| Flag that indicates whether to limit

link generation to selected zones.
• True — Program limits zonal-
access link generation to the
zones in the array specified
with the SELECT control
statement and I and J
keywords.
NOTE: If the SELECT statement
specifies no I or J, the array
specifies all zones for I or J.
• False — Program processes
all zones.
Setting to true can possibly speed
up zonal-access link generation.

LIN K |IV| Links accessed during zonal-

access development.
The program adds the specified
links as support links to the
system, and gives them the
appropriate distance, mode, and
time. Do not include any specified
links in SUPPORT statements.

LINK D IS T |I| Distance assigned to all the

 specified links. If DIST is not
coded, program treats link’s
distance as 0.

LINK MOD E |I| Mode assigned to the specified

links. If not specified, defaults to
the mode specified by GENERATE
MODE.

LINK ON E W A Y |?| Flag that indicates direction of

specified links:
• True — Specified links are
one-way.
• False — Default value.
Specified links are two-way.

The ZONEACCESS statement controls access development. During access development,

the program builds minimum-distance paths from selected origin zones to transit stop
nodes. Use this statement to specify zonal-access generation and to specify special
zonal-access links. The functions are independent: Even if the statement does not
generate zonal access, the statement will add specified zonal-access links to the
network. Citilabs recommends using separate statements for each purpose.
During access generation, the program treats each link’s A-node as an equivalent stop
node to the transit modes that stop at the link’s B-node. The program then generates a
zonal-access link directly from the origin zone to the link’s A-node. To use the statement
properly, the transit stop at the link’s B-node should be inaccessible to the access-path-
building routine. That is usually the case, when you use access links to isolate the
mode-of-arrival at a node. However, violating this criteria is not an error; it could be what
you intend.
The longest MAXDIST and the value of MAXLINKS restrict the access-generation path
builder. (The program will not build a path further than the highest MAXDIST from the
zone, nor will the path traverse more than MAXLINKS links from the zone to reach a
node.) After completing the path building, the program ranks all accessible nodes (stop
nodes and/or ZONEACCESS LINK A-nodes) by their distance from the zone. Next, the
program generates access links according to the restrictions of the MAXDIST and
MAXSTOPS values. Finally, the program enters the generated access links SUPPLINK
statements, according to the value of DIRECTION.
TRNBUILD Program > Control statements > ZONEACCESS > Example

Exam ple
ZONEACCESS generate=y,maxstops=1,2,3*4,6,7,8,10, maxdist=10*150 mode=11
ZONEACCESS link=43-22,43-40,MODE=14 dist=050
TRNBUILD Program > Examples and FAQ

Examples and FAQ

This section contains examples of the TRNBUILD program, along with a link to the
Voyager FAQ chapter. Items include:
• Example 1: Build transit network

• Frequently asked questions

TRNBUILD Program > Examples and FAQ > Example 1: Build transit network

Example 1: Build transit network

This step builds a transit network from the input files. It then builds paths and loads trips
onto the transit links. It writes a transit DBF that can be viewed in Network Window.
RUN PGM=TRNBUILD

FILEI NETI = ..\..\dtown\dtown.net ; input highway network

FILEI MATI = ..\..\dtown\od.mat ; input transit trips
FILEO NODEO = trnnode.dbf ; output node file
FILEO LINKO = trnlink.dbf ; output link file
FILEO MATO = trnlos.mat ; output transit LOS values

; ---- use the speed/cap table in network for link speeds

HWYTIME = SPDCLASS

; ----- read the transit route records from an external file

READ FILE= ..\..\dtown\troute.txt

; ----- generate zonal access links using the highway network

; links as possible walk links
ZONEACCESS GENERATE= TRUE MAXLINKS=4 MAXDIST= 255*100, MODE=100

; ----- LOS matrices are to be skimmed and written

MATRICES NAME= TRANTIME,DIST4,
MW[1]=TIME(1,2,3,4,5,6,7,8,9,10),
MW[2]=DIST(4)

; ----- specify a matrix of trips to be used

TRIPS MATRIX= MI.1.ODTRIPS, ASSIGN= TRUE

; ----- request to see certain transit paths (must use transit links)
TRACE=(I=1-5 && J=1-5 && BOARDS>0)

; ----- request reports

REPORT LINES=Name, LINESTRING='*'
REPORT LINEVOL= Y LINESORT= Y LINKVOL= Y FULL= Y
ENDRUN
TRNBUILD Program > Examples and FAQ > Frequently asked questions

Frequently asked questions

Please see TrnBuild in Chapter 17, “Frequently Asked Questions.”
Cube Avenue > Using Cube Avenue

Using Cube Avenue

This section provides information useful when using Cube Avenue:
• Cube Avenue introduction

• Phases
Cube Avenue > Using Cube Avenue > Cube Avenue introduction

Cube Avenue introduction

Cube Avenue is the Cube Voyager program for performing dynamic traffic assignment.
Derived from the Cube Voyager Highway program, which implements static traffic
assignment, Cube Avenue shares the same PHASE structure but has additional
commands and keywords to implement dynamic traffic assignment.
Older traffic models tend to fall into two categories:
• Op e ra tio na l tra ffic mo d e ls

• P la nning mo d e ls

Operational traffic models, such as Cube Dynasim (microsimulation) and SYNCHRO

(signal optimization), are useful for modeling network component interactions as queues
and delays vary during the model period. For example, these models can show how
signal offsets and synchronization can create a “green wave,” or how long queues can
disrupt traffic flows through upstream junctions (“blocking back”). However, these
models are not useful for forecasting routing (if they do so at all).
Microsimulation models also model day-to-day variation by using different random
number “seeds.” Sufficient runs can provide measures of trip time reliability. However,
most analysts only complete enough runs to obtain a representative sample and extract
averages. Of course, random day-to-day variations differ from the way travellers learn by
experimenting with different routes on different days, introducing a systematic,
convergent trend into travel patterns.
Planning models, on the other hand, do capture how drivers’ experiences over long
periods of time allow them to pick optimal travel strategies for regular, frequent trips, such
as trips to work. These models iterate on capacity restraints, finding “Wardrop User
Equilibrium” solutions to the travel assignment problem. These models are sometimes
described as macrosimulation models.
Cube Avenue tries to find a middle ground between these two extremes. Cube Avenue
uses a path builder in a capacity-restraint loop to model drivers finding routes and
modifying those routes based on experience. However, to evaluate the costs generated
by a set of routing decisions, Cube Avenue simulates the movement of vehicles through
the network. Hybrid models, like Cube Avenue, are known as mesosimulation models.
Cube Avenue > Using Cube Avenue > Cube Avenue introduction > General scripting advice

General scripting advice

The dynamic assignment program is still new but there are several points arising from
our experience so far:
• Statically assign the matrix and study the distribution of degree of saturation in the output
network. If there are any nodes or links where demand exceeds supply by a factor of two or
more, you will need to clean up the network and/or matrix before continuing. Typical
actions include checking that the matrix is for the right period and checking that the
capacity coded in the network is correct.

• Citilabs recommends PACKET S=PA, the default Packet Allocation mode, with a packet
size (P A CKE T S IZE ) of 1 or 2.

If using PACKETS=PS, Packet Splitting mode, the target packet size should be at
least as big as the expected number of iterations. If the matrix is large, a bigger value
may be appropriate.
• Avoid small matrix cells. Every non-zero cell must generate packets. But packets consume
computer memory and processor cycles. Therefore a matrix with many small cells can
cause lots of time and RAM to be wasted. Bucket rounding the matrix before assigning it is
probably the easiest way of cleaning a non-sparse demand matrix but, if you have enough
local knowledge of the study area, you may be able to clean the matrix better by hand.
Cube Avenue > Using Cube Avenue > Phases

Phases
This section describes the typical phases in Cube Avenue:
• SETUP phase

• LINKREAD phase

• ILOOP phase

• ADJUST phase

• CONVERGE phase
Cube Avenue > Using Cube Avenue > Phases > SETUP phase

SET UP phase
This phase behaves identically in Cube Avenue and standard Cube Voyager Highway
assignments.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase

LIN KREAD phase

This phase behaves similarly in a Cube Avenue assignment to the corresponding
phase in a Cube Voyager Highway assignment. In particular it executes twice per
iteration (once before phase ILOOP and once before phase ADJUST) but it does not
execute time segment by time segment.
The command, DYNAMIC, is only available in this phase. With this command, you can
vary the values of the C variable by time segment. At present, only C my be varied in
this way; future releases will allow you to vary STORAGE, too. This functionality may be
used, for example, to model tidal flow lanes.
Variables and input fields applicable to this phase include:
• DISTANCE

• LINKCLASS

• LI.SPDCLASS, LI.CAPCLASS

• LI.LANES

• SPEED

• C

• T0

• T1

• STORAGE
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > NOTE: Positive values should be used for DISTANCE,
C, SPEED, and STORAGE. Thus, zero values should be avoided.

NOTE: Positive values should be used for DISTANCE , C , SPEED , and STORAGE . Thus, zero
values should be avoided.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > DISTANCE

DISTANCE

If the user does not set this variable in script, it will be initialized from LI.DISTANCE, if
that variable exists and has a non-negative value. Failing that, it defaults to zero. Zero
distance links are sometimes described as “dummy links.”
As in any network, free-flow time must be provided independently of speed for zero
distance links, and output speeds are not meaningful for them. In Cube Avenue, a link
distance of zero may also cause STORAGE to default to zero (with disastrous
consequences for the modeling).
Distance is usually measured in miles or in kilometers.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > LINKCLASS

LINKCLASS

In Cube Avenue, LinkClass functions as the index for functions TC and COST, as it
does in any other highway assignment. If the script does not set the variable,
LI.LINKCLASS will be used if the variable exists and has a positive value. Failing that, it
defaults to one.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > LI.SPDCLASS, LI.CAPCLASS

LI.SPDCLASS, LI.CAPCLASS

If these field(s) exist, and the values in them are positive, and appropriate speed or
capacity tables are defined in the network, or in the script, they will be used, in
conjunction with Li.Lanes, to look up base speed and capacity values.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > LI.LANES

LI.LANES

The variable Li.Lanes will be taken from the input network. If there is no such field or if
the value in the field is non-positive, a value of one will be used. Note that the field name
required in the input network is “LANES” and that fields with similar names, such as
“NumberOfLanes,” will not be recognized as the number of lanes.
As in any highway assignment, Li.Lanes, may be used as an index into speed or
capacity tables.
In Cube Avenue, LI.LANES may also take part in the default STORAGE calculations.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > SPEED

SPEED

If the user does not set this variable in script, then defaulting will be from Li.Speed if that
exists. If Li.Speed does not exist, but Li.Lanes does, a speed table lookup will be
attempted. If all defaults fail, or if they result in a negative value, Speed will be initialized
to zero.
Note that, during the modeling, SPEED is a dependent variable; the independent
variable is TIME. Thus the defaulting behavior of SPEED is only significant if it is used to
calculate a default for T0.
Speed is in distance units per hour.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > C

This is the flow capacity of the link, in vehicles per model period. Note that this measures
how quickly the link can discharge or accept vehicles. This capacity differs from
STORAGE, which measures how many vehicles can occupy the link simultaneously.
Scripts can use the DYNAMIC command to specify that the value of C varies by time
segment.
If the script does not explicitly set this variable, the value in Li.Capacity is used as the
default. If Li.Capacity does not exist but Li.Lanes does, a capacity table lookup will be
attempted. If none of these values exists, a value of zero will be applied (with disastrous
consequences for Cube Avenue modeling). Finally, if PARAMETERS CAPFAC has been
coded, that factor will be applied.
Essentially, this value is the maximum frequency with which a vehicle can be discharged
from or admitted to a link. Thus, a zero-capacity link can delay packets forever.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > T0

T0

This is the free-flow time for the link, in minutes. It is used during application of the
function, TC. If the user does not set a value in script, the program will look in turn for
Li.T0, Li.Time and Li.Time1, in that order. If it still cannot find a value it will try to use
60*Distance/Speed. If all else fails, a default of zero will be applied.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > T1

T1

This is the link time to be used on the first iteration of assignment, before any calculated
times are available from an ADJUST phase. Note that in Cube Avenue it is applied to
every time segment. It defaults to T0 unless the user explicitly sets the value in script. It
is very common to accept this value, although there may be some merit to using
observed times where these are available.
Cube Avenue > Using Cube Avenue > Phases > LINKREAD phase > STORAGE

STORAGE

This is the number of vehicles that can fill the link. Both queuing and moving vehicles on
the link will use up storage. However, the storage does not directly limit the flow on the
link; so long as vehicles leave the link as fast as new vehicles arrive, the number of
vehicles on the link does not change. Thus every link has two capacities: the standard
capacity, C, restrains flow while STORAGE restrains occupancy.
If the user script does not supply a positive value for STORAGE, the program will try to
extract a value from LI.STORAGE. If a positive value still cannot be found,
LI.LANES*DISTANCE*vpd, where vpd denotes the value of PARAMETERS
VEHPERDIST, will be tried. If all else fails a value of zero will be applied (with the
disastrous consequence that the link will always be full, and hence, impassable).
Note that a link that has any spare storage will admit packets. In particular, if a packet
arrives at a link with some storage available, but the packet’s volume exceeds the
available storage, it will still be admitted to the link. (The link then becomes full, and it
remains full until it has discharged sufficient vehicles to reduce the occupancy back
below 100%.) Thus the maximum number of vehicles that can be observed on a link
may exceed that link’s storage slightly.
Cube Avenue > Using Cube Avenue > Phases > ILOOP phase

ILOOP phase
This phase is concerned with the creation of packets and the determination of routes.
The user script associated with this phase is executed for each time segment, and within
each time segment for every origin. This script should contain one or more
DYNAMICLOAD statements.

A conventional load (that is, a PATHLOAD statement) evaluates an expression (usually

involving matrices) to determine the number of trips, builds paths according to some
attribute minimization criterion, and then it loads the trips into the network’s volume fields.
A dynamic load evaluates an expression (usually involving matrices) to determine the
number of trips, builds paths according to some attribute minimization criterion, but it
defers updating the volume fields until the adjust phase. The trips are placed into
packets, where each packet contains a start time, a volume in one or more volume
fields, and a route. However, the network’s volume fields may only be updated later after
calculating, for each point on the route, when (that is, in which time segment) the packet
arrives there.
Note that on the second and subsequent iterations, packets generated during earlier
iterations are not normally discarded (see note below); they just have their volumes
modified according to the factors generated by the COMBINE methodology in force. For
COMBINE=AVE, the volumes in the packets generated during the current iteration will be
given by {expression value}/{iteration number} and the new volume for old packets will
be ({iteration number} – 1){previous volume}/{iteration number}. All the packets from all
the iterations so far will be simulated during the current iteration’s ADJUST phase.

NOTE: You may elect to generate new packets each iteration, and discard the old ones,
using the PACKETS GENPKTBYITER subkeyword. This is normally used in conjunction with
DYNAMICLOAD BUILDALLPATHS to force regeneration of all possible OD paths each iteration.
Please follow the links for these keywords for more information on usage and application.
Cube Avenue > Using Cube Avenue > Phases > ADJUST phase

ADJUST phase
This phase is executed when the movement of packets through the network is
simulated. Initially, all network link times are given by applying the TC function applied to
the volumes assigned in the previous iteration for the corresponding time segment
(except for the first iteration, when T1 is used).
During the simulation, a “queue” of events is maintained. In addition, there is a queue of
blocked packets waiting to get on each downstream link. There are four kinds of event
that can be stored in the event queue: a packet departs an origin, a packet arrives on a
new link, a packet arrives at its destination, or a packet becomes unblocked on a link.
Initially the event queue contains one event for each packet’s departure from that
packet’s origin and all the link queues are empty. The event queue is sorted on the time
at which the events are scheduled to occur.
The events from the event queue are processed in turn. As each event is processed
more events are added to the queue. For example, when a packet is scheduled to arrive
at a link A from link B, it is verified whether link A will accept the packet (if not it joins link
A’s queue) and an arrival event is scheduled for the next link on the path; before the
event processing is completed, a check is made to see whether any packets can be
released from link B’s queue.
Since every event occurs at a specified time, it is easy to determine whether the next
event occurs in the same time segment as the current one. If not, or if the end of the
model period has been reached, the script associated with the ADJUST phase is
executed for the time segment that has just been completed.
At the end of the entire simulation, some of the results are aggregated to obtain values
relevant to the entire modeled period. It is these aggregate values that are passed to the
Converge phase.
Cube Avenue > Using Cube Avenue > Phases > CONVERGE phase

CON VERGE phase

The CONVERGE phase is only executed once per iteration. It executes exactly the
same as it would in a static highway assignment.
Cube Avenue > Control statements

Control statements
This section describes Cube Avenue-specific control statements:
• DYNAMIC

• DYNAMICLOAD

• FILEO

• PARAMETERS

• PATHLOAD

The control statements available in the Highway program are also available in Cube
Avenue.
Cube Avenue > Control statements > DYNAMIC

DYNAMIC
Changes the value of the capacity variable by time segment. Only use this command
during the LINKREAD phase.
Keywords include:
• C

Ke y wo rd D e s c rip tio n

C |NV99| Defines link capacity by time segment.

Link capacity is initially defined as it
normally would be for a static assignment
(specified with COMP C= in the LINKREAD
phase, read from the input network
variable li.CAPACITY or read from the
internal speed/capacity table). In Cube
Avenue, link capacities are vectored by
time segment. A link’s capacities by
segment are initially set to the static
capacities for all segments.
Use the DYNAMIC statement to set
segment-specific capacities.
For example:
DYNAMIC C[3]=1800, 1000, 1800
results in C taking the value 1800 during
time segments 3 and 5, 1000 during time
segment 4 and its usual value during all
other time segments.
Normally this statement occurs in
conjunction with an IF statement that
applies the statement to the correct link:
IF (A=1005&B=1010) DYNAMIC
C[4]=90

This statement is useful for modeling time-dependent changes in link capacities, such
as reversible lanes, the closing of HOV facilities at specific times of day, the opening of
HOV facilities to general purpose uses at specific times of day, or construction closures.
For example, suppose you have:
• Input network with a default hourly lane capacity coded as CAP

• Cube Avenue model period is 180 minutes with three 60-minute time segments

• In the last hour of the period some shoulder lanes available in the prior two hours are no
longer available

You can set the default capacities for all links in all segments with the static script
statement:
C=li.CAP*li.LANES1*3

Then use the DYNAMIC statement to set capacity in the third time segment when the
shoulder lanes become unavailable:
DYNAMIC C[3]=li.CAP*li.LANES2*3

where LANES1 and LANES2 contain the available lanes during the first two hours and
the last hour, respectively.
Cube Avenue > Control statements > DYNAMICLOAD

DYNAMICLOAD
DYNAMICLOAD is the dynamic analog of the static PATHLOAD statement. Most of the
keywords have the same syntax and meaning as the corresponding keywords of the
PATHLOAD statement, so only the differences are noted in this section.
Furthermore, it is intended to allow some other clauses of the PATHLOAD statement to
be applied to dynamic loading once the relevant functionality has been implemented.
• D E MA N D D IS T R IB = random/uniform

• B U ILD A LLP A T H S = t/f

• D E MA N D IS H OU R LY = t/f

• IN CLU D E J = list

• E XCLU D E J = list

• V OL[ n] = list

• P A T H = time/cost/list

• E XCLU D E GR P = list

• PACKETSIZE = value

• P E N I = list

• P E N IFA CT OR = value

• MW [ n] = TRACE(real, expr, list)

• N OA CCE S S = real

The DYNAMICLOAD statement may only occur in PROCESS PHASE = ILOOP. A static
assignment script must contain one or more PATHLOAD statements but may not
contain a “PARAMETERS MODELPERIOD= SEGMENTS=” clause nor a
DYNAMICLOAD statement. A dynamic traffic assignment must include a
“PARAMETERS MODELPERIOD= SEGMENTS=” clause and at least one
DYNAMICLOAD statement. It may also contain one or more PATHLOAD statements, in
which case simultaneous dynamic and static loadings will occur. See “Combined use of
DYNAMICLOAD and static PATHLOAD” on page 1116 for a description on running
combined DYNAMICLOAD and static PATHLOAD in the same run.
Several keywords of the DYNAMICLOAD statement require time-segmented lists as
inputs (these lists contain one item per time segment). If you enter a single value that
contains one or more occurrences of __TS__, Cube Avenue expands the value into a
list by replacing the __TS__ with the integers representing the time segments, such as
1, 2, and so forth. For example, entering PATH=LW.COST__TS__ is equivalent to
entering PATH=LW.COST1, LW.COST2, LW.COST3, and so forth.

DEM ANDDISTRIB
The DYNAMICLOAD DEMANDDISTRIB= clause may take, as its value, “RANDOM” or
“UNIFORM”. This clause allows the vehicle departure distribution to be either uniform
random (default) or uniform constant. Under the latter condition, packets depart
uniformly spaced across a time segment. For example, 15 minute time segment with 150
packets will have a packet departing every 6 seconds.

BUILDALLPATHS

The DYNAMICLOAD BUILDALLPATHS= keyword is, by default, false.

BUILDALLPATHS can be used in any DYNAMICLOAD statement to ensure all
possible paths are built between all OD pairs.
BUILDALLPATHS is required where volumes in O-D pair(s) vary between iterations,
and are changed to zero for one or more iterations. When an O-D volume is zero, no
paths are generated for that iteration. Thus, BUILDALLPATHS must be set to true to
restore the paths for subsequent iterations.
Citilabs recommends that applications using PACKETS GENPKTBYITER include
BUILDALLPATHS. These are common in applications which apply a toll-diversion
process by iteration.

For example:
DYNAMICLOAD PATH=TIME, BUILDALLPATHS=T, PACKETSIZE=1,
VOL[1]=MW[110+__TS__], EXCLUDEGRP=1 ; loading for free roads
DYNAMICLOAD PATH=TIME, BUILDALLPATHS=T, PACKETSIZE=1,
VOL[2]=MW[120+__TS__] ; loading for toll roads

PATH

The DYNAMICLOAD PATH= keyword may take, as its value, “TIME,” “COST,” or a list
of input link attributes one per time segment:
• In the first two cases, the path will be built to minimize the appropriate time varying function.

• In the last case, a time varying function to be minimized will be constructed by using the
value from the appropriate link attribute in each time segment (that is, LI. Variables or
LW.Variables). One attribute must be declared for each time segment. For example, with
two time segments and custom LW variable CTIME, proper syntax would begin with:
DYNAMICLOAD PATH=LW.CTIME, LW.CTIME, (etc...)

The predicted disutility for a vehicle of traveling down a link is therefore dependent on
the time segment in which the vehicle expects to enter that link. You can use the
macro expansion of _TX to abbreviate the list of link variables.

DEM ANDISHOURLY
The DYNAMICLOAD DEMANDISHOURLY = keyword is, by default, false. It determines
whether the demand volumes for each time segment are supplied as an absolute value
in vehicles or as a rate in vehicles per hour. For example, suppose that there is a
segment of 15 minutes, and the corresponding expression in a DYNAMICLOAD VOL[n]
= clause evaluates to thirty. If DEMANDISHOURLY, then the demand is 30 vph and 7½
vehicles will depart the origin during the time segment. Otherwise thirty vehicles depart
the origin during the time segment, giving a departure rate of 120 vph.

VOL[n]

The DYNAMICLOAD VOL[n] = keyword is similar to the PATHLOAD VOL[n] =

keyword. This clause evaluates expressions for each destination (subject to INCLUDEJ
and EXCLUDEJ clauses) and interprets the result as a demand volume for the specified
volume field. The entered value must be a list of expressions with one entry per time
segment. You can use __TS__ to abbreviate the list, such as VOL[1]=MW[__TS__+3].
When the ILOOP is executed for time segment n, the nth element of the list will be the
one that is evaluated. If necessary, the value is converted to give the number of vehicles
departing during the segment and then compared with the target packet volume to
determine how many packets are generated. At least one packet will be generated for
any IJ pair that has a positive demand. The paths will be assigned routes based on their
departure time and their expectations of travel time and disutility. However, no change to
the volume field values occurs during PROCESS PHASE=ILOOP. Instead actual
loading is deferred until the simulation runs in the PROCESS PHASE=ADJUST.

PACKETSIZE

The DYNAMICLOAD PACKETSIZE = keyword specifies the target number of vehicles

per packet.

NOTE: Citilabs
recommends setting PACKETSIZE to 1 or 2 when in Packet Allocation
mode (PACKETS=PA).

M W [n]

The DYNAMICLOAD MW keyword specifies skims. The value must take the form:
TRACE(time, expression, penalty)

where:
• time is the start time, specified in minutes since the beginning of the model period. It
indicates that the skim should be for vehicles departing their origins at the specified start
time. Negative values indicate that the start time is in the 'warm up' period.

• expression is the expression evaluated and summed for each link on the route.
• penalty is an optional list of turn penalty sets to include in the skim.

You can use the special expression, PATHCOST, to skim the value of the DYNAMIC
PATH clause. If the expression contains the string __TS__, it will be evaluated as a
dynamic expression that varies by time segment.
Cube Avenue > Control statements > DYNAMICLOAD > Combined use of DYNAMICLOAD and static PATHLOAD

Combined use of DYN AMICLOAD and static PAT HLOAD

The combined use of both static and dynamic processes in the same run can be
accomplished but some care should be taken to insure it is implemented correctly and
the user is carrying out what is intended. There are two classes of assignment process
now supported in Cube Voyager: Static and Dynamic. A static assignment process is
what users should be familiar with as the typical assignment process. In Cube Voyager
a static assignment process contains no dynamic elements. If using Cube Avenue to
perform dynamic traffic assignment, the assignment process will include dynamic
elements but may also include static elements. A few rules apply to these two cases
when using Cube Avenue as described below.
Cube Avenue > Control statements > DYNAMICLOAD > Combined use of DYNAMICLOAD and static PATHLOAD > Case 1:
Static assignment

Case 1: Static assignm ent

• There are no instances of “PARAMETERS MODELPERIOD= SEGMENTS=” in the entire

script [this setting is the key that switches modes].

• There must be at least one instance of PATHLOAD in phase ILOOP; there may be more
than one.

• There may not be any instance of PATHLOAD outside phase ILOOP.

• There may not be any instances of DYNAMICLOAD.

• No variables are vectorized by segment and all apply to the model period as a whole.

• There is a single “static” time segment and it runs same as the Highway program has
always run.
Cube Avenue > Control statements > DYNAMICLOAD > Combined use of DYNAMICLOAD and static PATHLOAD > Case 2:
Dynamic assignment

Case 2: Dynam ic assignm ent

• There is exactly one instance of “PARAMETERS MODELPERIOD= SEGMENTS =.”

• There must be at least one instance DYNAMICLOAD in phase ILOOP; there may be more
than one.

• There may be instances of PATHLOAD in phase ILOOP.

• There may not be any instance of PATHLOAD outside phase ILOOP.

• There may not be any instances of DYNAMICLOAD outside of phase ILOOP.

• There is one time segment for each of the segments listed with the SEGMENTS=
PARAMETER and phase ILOOP will be executed for each of them. During each of these
executions of ILOOP, a single item from the list of matrix expressions in each
DYNAMICLOAD statement is evaluated (and paths built, packets created, etc.). No
PATHLOAD statements are executed during any of these executions of phase ILOOP.

• If there are any instances of PATHLOAD, an additional execution of PHASE ILOOP occurs
prior to any of the executions described above. During this execution of phase ILOOP, no
DYNAMICLOAD statements are executed but PATHLOAD statements are. The volumes
assigned are assumed to apply to the model period so the volumes applicable to each of
the time segments get preloaded with PATHLOAD-VOLUME*(length of segment)/(model
period).

• Phase ADJUST is executed for each time segment. The results (except for volumes) are
carried forward to the corresponding execution of ILOOP during the next iteration. After
ADJUST has been executed for each time segment, aggregate values applying to the
model period are calculated from the results individual time segments. These aggregate
results are used for the calculation of convergence statistics. If there are any PATHLOAD
statements in phase ILOOP, then these values (except for the volumes) will be carried
forward to the “static” execution of phase ILOOP during the next iteration.

Note that none of the discussion above depends on the ordering of PATHLOAD and
DYNAMICLOAD statements. It is their presence or absence from the ILOOP PHASE of
the script (as a whole) that is significant.
Cube Avenue > Control statements > FILEO

FILEO
Specific to Cube Avenue FILEO are the following keywords and subkeywords:
• P A CKE T LOG
m AFTERITER
m ARRIVALTIME
m DEPARTTIME
m DESTINATION
m FORMAT
m MUSTMEETALL
m ORIGIN
m SELECTGROUP
m SELECTLINK

The below Highway program output files are no t supported under FILEO if running a
dynamic assignment process under AVENUE. These include:
• E S T MD A T O

• E S T MICP O

• S U B A R E A MA T O

Note that a FILEO PATHO may be specified but it may not have dynamic paths written
to it during a dynamic assignment run under AVENUE. If a DYNAMICLOAD PATHO=T
control is found in the ILOOP PHASE, a fatal error will be generated. Some users have
keys implemented in their application scripts to turn on or off the generation of the
PATHO file. This will allow the script to run with the PATHO file being specified as long
as no dynamic paths are directed to the output file during the dynamic run.
You may skip ahead to:
• Output data

FILE O k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

PACKETLOG |F| Produces the dynamic equivalent

to the static path file. Specified as
FILEO PACKETLOG=filename.
The file is likely to be very large. It
lists every packet, giving the
associated volume and route. It
also gives the times (in hours since
the start of the model period) each
packet arrives and departs from
each node. The difference
 between these two times is the time
that the packet spent queueing.
NOTE: Writing a packet log
requires computer resources:
processor time, RAM, and disk
space. Additional options on the
FILEO PACKETLOG statement can
reduce the number of packets
included in the packet log and thus
reduce the required resources. By
reducing required resources, you
can improve run times, even
leading failed runs to succeed.
However, with all the information in
the file, you can filter displayed
packets with Cube graphics.

PACKETLOG AFTERITER |I| Iteration number when Cube

Avenue begins writing packet log.
By default, Cube Avenue writes the
packet log for each simulation run
(that is, for every iteration),
overwriting the same file and
ensuring that a valid packet log
exists upon completion of a
successful Cube Avenue run.
However, if you know that Cube
Avenue will require at least m
iterations, you can set AFTERITER
to m-1 to save some run time by
not writing the file during the first few
iterations.

PACKETLOG ARRIVALTIME |RPV| List of time intervals. Packet log

only includes packets that arrive at
their destinations during the listed
time intervals. Specify each
interval as an ascending pair of
real numbers— minutes since the
start of the model period.

PACKETLOG DEPARTTIME |RPV| List of time intervals. Packet log

only includes packets that depart
their origins during the listed time
intervals. Specify each interval as
an ascending pair of real numbers
— minutes since the start of the
model period.

PACKETLOG DESTINATION |IV| List of destination nodes. Packet

log only list packets ending at the
listed destinations. By default, log
includes packets to all
destinations.

PACKETLOG FORMAT |S| Either BIN or TXT. By default, the

PACKETLOG is a text file, which
you can display in Cube graphics
or post-process with a user-
defined program, such as a matrix
record-processing script. Binary
format is only suitable for display in
Cube graphics, but binary files are
about 60% smaller.
PACKETLOG MUSTMEETALL |?| Flag indicates type of link set
specified by SELECTLINK and
SELECTGROUP:
• True — Link set defines a
route section: the packet log
only lists packets that pass
every link in the set.
• False — Link set defines a
special area: the packet log
lists any packet that passes
at least one link in the set.
The default value is true.
NOTE: If none of these keywords
(SELECTLINK, SELECTGROUP,
and MUSTMEETALL) is listed, the
packet log does not restrict
packets based on links traveled.

PACKETLOG ORIGIN |IV| List of origin nodes. Packet log

only lists packets starting at the
listed origins. By default, log
includes packets from all origins.

PACKETLOG SELECTGROUP |IPa| List of link groups, defined in

previously executed
ADDTOGROUP commands.
Along with SELECTLINK, defines a
set of links that packets must pass
through for inclusion in the packet
log, based on the value of
MUSTMEETALL.

PACKETLOG SELECTLINK |IPV| List of links. Along with

SELECTGROUP, defines a set of
links that packets must pass
through for inclusion in the packet
log, based on value of
MUSTMEETALL.
Cube Avenue > Control statements > FILEO > Output data

Output data
Cube Avenue produces additional output data over that produced by the Highway
program. The dynamic assignment process implemented in Cube Avenue automatically
appends additional results variables onto the NETO output network using an indexing
convention similar to that used by the Highway program when performing static
assignment. The output NETO network will include all NETI input variables unless
explicitly excluded with the EXCLUDE keyword and any additional variables included
with the INCLUDE keyword and the following dynamic results variables:
• TIMESt_1 and TIME_1

• SPEEDSt_1 and SPEED_1

• VfSt_1, VfSMP_1, VSt_1 and VSMP_1

• VITSt_1

• QUEUEVSt_1

• BLOCKVSt_1

• AVGQDELAYSt_1 and AVGQDELAY_1

Cube Avenue > Control statements > FILEO > Output data > TIMESt_1 and TIME_1

TIM ESt_1 and TIM E_1

For vehicles arriving on a link during a particular time segment, TIMESt_1 stores the
amount of time that the vehicles spent traversing the link segment (averaged over all
such vehicles). TIME_1 is similar, but applies to the model period (excluding any “warm
up” segments).
The reported values are effectively the sum of two components: the base time
calculated from function TC and the queue time resulting from storage and capacity
constraints.
Cube Avenue > Control statements > FILEO > Output data > SPEEDSt_1 and SPEED_1

SPEEDSt_1 and SPEED_1

This field contains the ratio between distance and the time (as defined above). It does
not take turn penalties or junction modelling into account.
Cube Avenue > Control statements > FILEO > Output data > VfSt_1, VfSMP_1, VSt_1 and VSMP_1

VfSt_1, VfSM P_1, VSt_1 and VSM P_1

The volume of traffic entering the link, in volume field f, during time segment, t. VSt_1 is
the result of applying the V function to V1St_1, V2St_1, etc.
At origin zone centroid connectors, the values in the volume fields should correspond to
the appropriate matrix row totals.
Note there are two very different situations that can result in low volumes entering
downstream links (that is, links other than origin zone centroid connectors). If there is
very low demand for travel on the link, the flow will be low because the link is empty. At
the other extreme, a link that is full of traffic may block further vehicles from entering.
The values in the fields labelled with “MP” instead of a time segment number contain
aggregate values for the “model period” (that is, excluding any “warm up” segments).
Cube Avenue > Control statements > FILEO > Output data > VITSt_1

VITSt_1

The number of vehicles on each downstream link at the end of time segment, t, is
recorded in this field. The value is found by summing across all packets of vehicles that
are flowing or queuing on the link. At origin zone centroid connectors, the field value will
be zero, but this is just a convention indicating that data has not been collected for these
links.
Cube Avenue > Control statements > FILEO > Output data > QUEUEVSt_1

QUEUEVSt_1

This measures the average number of vehicles queuing on the link during time segment
t.
Packets of vehicles can be made to queue by either of two mechanisms. First, if the
packet tries to move onto a full link, it will be “blocked,” and it will queue until space
becomes available on the next link. Second, links and turns in the network are
associated with capacities and capacity bottlenecks may delay packets to ensure that
these capacities are not exceeded; the vehicles affected queue while waiting to
proceed, but are not recorded as “blocked.”
Cube Avenue > Control statements > FILEO > Output data > BLOCKVSt_1

BLOCKVSt_1

This records the number of vehicles in the queue that will remain in the queue at the end
of the simulation. The value will always be less than or equal to the queue variable.
Values can only increase in subsequent time segments.
Cube Avenue > Control statements > FILEO > Output data > AVGQDELAYSt_1 and AVGQDELAY_1

AVGQDELAYSt_1 and AVGQDELAY_1

For vehicles arriving on a link during a particular time segment, AVGQDELAYSt_1

stores the queue time resulting from a storage and capacity constraints on the link
segment (averaged over all such vehicles ). AVGQDELAY_1 is simlar, but applies to
the model period (excluding any “warm up” segments).
Cube Avenue > Control statements > PARAMETERS

PARAMETERS
Sets general parameters. Keywords include:
• CA P LIN KE N T R Y

• COMB IN E
m GENPKTBYITER
m ITERLOADINC
m PACKETS

• MA XP T H P E R S E G

• MOD E LP E R IOD
m SEGMENTS

• P KT P T H S IZ

• P R E S E R V E MW

• V E H P E R D IS T

All the parameters from Highway are also available in Cube Avenue. This page only
mentions those parameters that are new or different in Cube Avenue.
P A R A ME T E R S k e y wo rd s

Ke y wo rd S ub k e y wo rd D e s c rip tio n

CAPLINKENTRY |?| <Y> When CAPLINKENTRY=Y

(default) the capacity of the link
limits how quickly vehicles can
enter or leave a link. When
CAPLINKENTRY=N, the link
capacity only limits how quickly
they can leave the link.
Note that the primary difference
between these two regimes is
where the front of a queue
occurs. If CAPLINKENTRY is
off, then the front queue due to a
bottleneck link is at the B node,
but if it is on then the front of the
queue is at the A node.

COMBINE |KS| See “COMBINE” on page 258

for valid subkeywords and
descriptions. Combine type
“EQUI” is not valid for Avenue.
Since the default value of
COMBINE is “EQUI,” COMBINE
must always be specified
explicitly for AVENUE. For most
uses of AVENUE, “AVE” is a
good choice of combine value.

COMBINE GE N P KT B Y IT E R |K?| Generate new packets each

 iteration, and discard
previously-generated packets
at the start of every iteration.
Default is false.
GENPKTBYITER must be
declared immediately after
PACKETS=PA:
PAR COMBINE=AVE,
PACKETS=PA,
GENPKTBYITER=T,
MAXITERS=5
When using GENPKTBYITER,
Citilabs recommends including
DYNAMICLOAD
BUILDALLPATHS. These
control statements are required
where volumes in O-D pair(s)
vary over iterations, and are
changed to zero for particular
iteration(s).
GENPKTBYITER is useful in the
case where the first iteration
includes an O-D pair with zero
volume. The keyword will
ensure packets are generated
for subsequent iterations
should there be volume on that
O-D pair. It will also ensure that
new packets reflect the
changing volumes over
iterations.
These keywords are common
in applications which apply a
toll-diversion process by
iteration.

COMB IN E IT E R LOA D IN C |KI| Must be declared after

PACKETS, and only applicable
for COMBINE=AVE where
PACKETS=PA is selected.
Defaults to zero.
This specifies the number of
iterations between the loading
of packets for subsequent time
segments. This allows for a
partial convergence of the
network for each time segment
before subsequent time
segments are loaded. This in
turn allows the paths for
subsequent time segments to
be generated on a more
realistic set of times and
speeds in the network.
This method is recommended
for congested networks where
the loading of subsequent time-
segment packets onto a
partially converged network
allows a better initial network
estimate for later time-
segments and hence faster
convergence.
 If specified with MAXITERS,
note that:
• ITERLOADINC must be
declared before
MAXITERS.

• When ITERLOADINC > 0,

instead of a total number
of iterations, MAXITERS
specifies the maximum
number of iterations for
each time segment,
resulting in a total number
of iterations equal to
(number of time
segments – 1) *
ITERLOADINC +
MAXITERS. At the very
minimum, (number of time
segments – 1) *
ITERLOADINC + 1
iterations are performed
to allow for every time
segment to be loaded
and simulated at least
once.
After MAXITERS iterations have
been performed for each time
segment, the simulation results
for that time segment are
saved. For subsequent
iterations path builds are not
performed, and the simulation
result for saved time segments
are restored in order to ensure
every time segment is
simulated only MAXITERS
times. This reduces the total
simulation time.

COMB IN E PACKETS |KS| Only applicable for

COMBINE=AVE. Selects
between packet splitting and
packet allocation modes.
Defaults to PA.
• PA — Packet allocation
mode. In this mode a new
best path is calculated for
each iteration, and
packets are divided
evenly among the paths
from each iteration. The
same path can appear
as best path in multiple
iterations and therefore
this path will get multiple
share of the packets (one
share for each iteration
the path appeared as
best path).
NOTE: When
PACKETS=PA/RPA,
Citilabs recommends
 setting PACKETSIZE to 1 or
2.
• PS — Packet splitting
mode. This is the
traditional MSA method
where a best path is
calculated for a packet.
On subsequent iterations
a new best path is
calculated and the
packet’s volume is split
across all available
paths. Using this method
results in higher memory
usage and simulation
time due to the greater
number of packets in
subsequent iterations.
• RPA — Random Packet
allocation mode. In this
mode a new best path is
calculated for each
iteration, and from this set
of paths (which may
include the same path
several times if it is
continually a best path) a
path is selected using a
uniform distribution for
simulation. This method
results in a memory
optimized simulation due
to there being only the
initial single set of
packets that moves
between paths as
required.

MAXPTHPERSEG |KI| Upper bound on the number of

path builds executed for a
given time segment, iteration,
and origin. Defaults to 1.
If the number of distinct packet
departure times is less than this
value, Cube Avenue builds
paths for each packet— each
packet’s node list is based on
accurately built paths.
Otherwise, Cube Avenue
executes this many path builds,
distributed evenly through the
time segment. Each packet’s
node list is based on the
nearest path build, in terms of
departure time.
Though this value can affect the
packet’s route, the packet's
simulated departure remains
unchanged. If PACKETS=PA is
specified, MAXPTHPERSEG
must be equal to 1, and any
other value will results in a fatal
error being issued.
MODELPERIOD |S| The value of MODELPERIOD is
the length of the model period
in minutes.
The value of the subsidiary
segments clause is a list of
time segment durations, also in
minutes. The length of the list
determines the number of time
segments. It is the presence, or
absence, of a segments clause
that determines whether Cube
Voyager runs Highway or
Avenue. If the segments list is
present, the ILOOP phase must
contain a DYNAMICLOAD
statement, but need not (and,
usually, should not) contain a
PATHLOAD statement. If the
segments list is absent, the
ILOOP phase must contain a
PATHLOAD statement but must
not contain a DYNAMICLOAD
statement.

MOD E LP E R IOD SEGMENTS |R*| Subkeyword for

MODELPERIOD.
The sum of the values in the
segments list must be greater
than or equal to the model
period. If the sum of the
segments is strictly greater than
the model period, the extra time
forms a kind of “warm-up”
period before the “true”
modeling begins. Thus, when
the “true” model period begins,
there will already be vehicles
driving on roads in the network
interior.

PKTPTHSIZ |KI| Maximum number of nodes that

a packet keeps in RAM.
Packets use computer RAM
when simulated. Windows
imposes a 2 gigabyte limit on
the total memory available to a
program. To save memory,
packets can swap their route
information between RAM and
temporary disk files.
If encountering Avenue
performance issues (such as
disk swapping), Citilabs
recommends setting
PKTPTHSIZ to 20. PKTPTHSIZ
is ignored when less than 6.

PRESERVEMW |KIVPa| Option to allow for preserving

the contents of the specified
MW array (or arrays) across
time segments within an
iteration.
For example:
 PRESERVEMW=42-47,52 will
preserve MW arrays 42 through
47, along with 52.

VEHPERDIST |KR| This is the number of queuing

vehicles that can sit in one lane
of roadway one distance unit
long. The value is only used for
the calculation of default
storage, so if storage is
supplied explicitly in script, or in
the input network, the
parameter value does not
matter.
Remember that the implied
vehicle spacing must be
greater than the average length
of a vehicle; storage must
include the average gap
between the vehicles (vehicles
do not queue bumper to
bumper).
The default value of this
parameter is 181.81. If the
distance unit is kilometers, then
181.81 vehicles per kilometer
gives a vehicle every 5.5
meters. 181.81 vehicles per
mile does not yield an
appropriate vehicle length.
(181.81 vehicles per kilometer
is 295.38 vehicles per mile.)
The HCM2000 recommends
that the following values be
used, in the absence of local
observed values:
• Freeway: 120 veh/mi/ln =
75 veh/km/ln
• Rural Highway: 210
veh/mi/ln = 130 veh/km/ln

• Arterial: 210 veh/mi/ln =

130 veh/km/ln
Cube Avenue > Control statements > PATHLOAD

PATHLOAD
PATHLOAD is the static assignment path builder from the Highway program. See
“PATHLOAD” on page 270 for a description of this command statement and its
associated keywords and usage.
If a PATHLOAD statement is present in a Cube Avenue run, an extra initial execution of
the ILOOP is performed for every iteration. During this execution, all variables take values
associated with the model period; PATHLOAD statements are executed but DYNAMICLOAD
statements are not executed.
During dynamic simulation, the static loads (generated from PATHLOAD statements) are
present (and constant) in every time segment. The capacity, which is available for
packets, is reduced by the static loading. See “Combined use of DYNAMICLOAD and
static PATHLOAD” on page 1116 if implementing both command statements in the
same run.
The following Highway PATHLOAD keywords and their subkeywords are not supported if
using static PATHLOAD statements in a dynamic assignment process with DYNAMICLOAD
in effect.
• E S T MO

• PAT HO
Cube Avenue > Theory

Theory
This section discusses the theory behind Cube Avenue:
• Cube Avenue algorithm

• Cube Avenue calculations

• Functions and built-ins

Cube Avenue > Theory > Cube Avenue algorithm

Cube Avenue algorithm

Cube Avenue is a simulation embedded into Cube Voyager highways to allow dynamic
traffic assignment. It is designed to enable the prediction of time-varying costs and flows
given a time-varying demand for travel.
The time modeled is divided into two major periods: a warm-up period, during which the
network is filled with traffic, and the model period, over which network statistics are
aggregated. Furthermore the time is also divided into smaller time-slices. The demand
for travel is assumed to be approximately constant during each time slice, but to vary
between time slices.
Initially the link and junction times are taken to be the same for all time segments (and
are taken to be the values from the input data files). However, once modeling begins, the
segment-by-segment times are recalculated independently. So, on the second and
subsequent iterations, there will be different estimates of delay for vehicles arriving on a
link (or at a stop=line) for each time segment.
When dynamic demand is required for some origin-destination pair for some time
segment, it is divided into a number of packets of vehicles. Each packet has a start time
and a number of vehicles in each volume field. It also has a route for each iteration of
assignment. The route is calculated based on the current estimate of each time
segment’s delays and on the estimated time of arrival of the packet at each point on its
route.
On the second and subsequent iterations, the routes from previous iterations are not
discarded (unless PACKETS GENPKTBYITER is in effect). Instead the packet volumes travel
along each route in proportion to the lambda values for the appropriate iteration.
Cube Avenue > Theory > Cube Avenue algorithm > Packet paths and volumes

Packet paths and volumes

Dynamic user equilibrium is achieved through two different methods: Successive
Averages (PS) and Packet Allocation (PA and RPA). These methods are available in
the LOOP phase (see below) when COMBINE is set to AVE, and chosen with the PACKETS
keyword (see “PARAMETERS” on page 1124).
- Starting from Cube 6.4, the original packet allocation methodology
Packet Allo catio n (PA)
has been updated. In this mode a new best path is calculated for each iteration, and
packets are divided evenly among the paths from each iteration. The same path can
appear as best path in multiple iterations and therefore this path will get multiple share of
the packets (one share for each iteration the path appeared as best path).

Packet vo lum es o ver fo ur iteratio ns, under Packet Allo catio n m o de

- In this mode a new best path is calculated for each

Rando m Packet Allo catio n (RPA)
iteration, and packets are switched to the new best path, with probability inverse to the
iteration number.
Packet vo lum es o ver fo ur iteratio ns, under Rando m Packet Allo catio n m o de

NOTE: In packet allocation modes (PA and RPA), a new 'best path' is calculated on each
iteration, but no additional packets are generated. The existing packets are re-allocated
to the new best path. Unless PACKETS GENPKTBYITER is in effect, new packets are never
introduced. Thus, the computational demands of this mode are far lower than Packet
Splitting. When using Packet Allocation mode or Random Packet Allocation mode,
Citilabs recommends setting PACKETSIZE to 1 or 2.

- Packet Splitting (or Successive Averages) is the default through

Packet Spliting (PS)
Cube 5.0. On each iteration, a new best path is generated along with new packets.
Traffic volume is equally distributed between all packets. Because this legacy mode
loads new packets every iteration, its memory and computational demands can be high.

Packet vo lum es o ver fo ur iteratio ns, under Packet Splitting m o de

Cube Avenue > Theory > Cube Avenue algorithm > ILOOP & ADJUST

ILOOP & ADJUST

During the ILOOP phase, the path-building algorithm is invoked to calculate routes, and
any flows resulting from the movement of packets during previous iterations are
removed from the volume fields. Unlike a static load, no flows are assigned to the
network at this stage in the process.
The ADJUST phase runs the simulation. The simulation is run in continuous time (not
segment-by-segment). Packets emerge from their origin zones at their start times and
start moving along their routes. As they leave flows behind them in the network’s volume
fields.
Packets must take at least the link time to traverse a link. They must also take at least
the turn time to traverse a turn.
Each link has a storage capacity. At any time, if a packet wishes to move into a link, it
must compare the total volume of packets in transit on the destination link. The packets
in transit on a link are the packets traveling on the link and the packets queuing on the
link. If the volume of packets in transit exceeds the storage of the destination link, the
packet that is trying to move is blocked and remains queued on its current link until
space becomes available.
Furthermore, each link capacity or turn capacity is represented as a “gate.” Given a flow,
a gate will work out a busy time proportional to the flow and inversely proportional to the
capacity. If a packet arrives at a gate and the gate was unoccupied for the
corresponding busy time, it can pass straight through (but the gates most recent
occupied time becomes now). Otherwise the packet will be delayed until the sum of the
busy time with the time at which the gate was most recently occupied. Such packets are
queued on the link preceding the gate, but they are not considered to be blocked.
Cube Avenue > Theory > Cube Avenue calculations

Cube Avenue calculations

This section describes Cube Avenue calculations:
• Volumes

• Times

• Speeds
Cube Avenue > Theory > Cube Avenue calculations > Volumes

Volumes
During the ILOOP phase, the matrix cells in the demand trip matrix are calculated and
split into packets. Paths are calculated for each packet and the packets are written to (a
temporary file on) disk. On the second and subsequent iterations, the packets are
appended to the existing disk file; the paths etc. from previous iterations are retained.
At the start of the simulation (that is, the ADJUST phase), all the link volume fields, for all
time segments, for the current iteration are cleared to zero. The packets are read from
disk and the stored values of flow are multiplied by the appropriate factor.
As the simulation progresses, the packets are released onto the network and move
along their predetermined paths. As they move from link to link the network volume fields
are updated as follows:
• When a packet departs the origin, the volume for the origin zone centroid connector is
updated.

• When a packet moves from a link to another link, the volume fields for the second link, and
for the turn between the two links, are updated. Note that the volume fields are updated for
a single time segment; the segment in which the first link is left.

• When a packet arrives at a destination no volume fields are updated.

An update to the volume fields for a given link or turn in a given time segment proceeds
as follows:
• First the packet is examined to determine which of the 1000 possible volume fields are
present.

• The values of V1, V2, …, V1000 are increased by the values stored in the packet.

• If the volumes are for a link, the function, V, is executed to update the total volume; if the
volumes are for a turn, the function, T, is used instead. Note that in the absence of a user-
defined function, these functions default to simple summation over all volumes.

At the end of the iteration, the convergence tests decide whether Cube Avenue should
continue or stop. If the latter choice is made, the volumes will be written to the output
network.
Cube Avenue > Theory > Cube Avenue calculations > Times

T imes
Logically, Cube Avenue maintains two components of link time (called flow time and
block time) and one component of turn time for each time segment. The link time is the
sum of the flow time and the block time.
Prior to any calculations, flow times for all time segments are initialized to the T1 values
read from the input network (or set by code in phase LINKREAD). Similarly turn times
are initialized from the “EstimatedDelay” values stored in the intersection file, and from
times in the turn penalty file. Any turns where these defaults do not yield a value are
initialized to zero. Block times are initialized to zero. The network time fields are
calculated as the sum of the blocked and flow times.
There are two kinds of turns in Cube Avenue: unmodeled and modeled. Unmodeled
turns are those where there is no modeling or where there is a fixed turn penalty.
Unmodeled turns never change their time and they do not apply capacity “gates” to
regulate the movement of packets from their preceding link. Modeled turns are those
with function turn penalties or with intersection models. In both cases the times are
updated for each time segment on each iteration but in the former case the capacities
neither change from segment to segment nor from iteration to iteration.
During path building, the link times are taken from the network time field. The costs are
taken by applying the cost function to these fields.
Prior to simulation, all blocked times are zeroed. As the simulation progresses the
packets move from link to link. Sometimes the packets take longer than the sum (flow
time + turn time) to do so. The program tracks in which time segments these excess
vehicle minutes occur.
Before a segment begins, the queues for each modeled turn are noted. In the first time
segment these are taken from the “InitialQueue” values stored in the intersection file. In
subsequent time segments they are found by looking at the packets simulated to be
waiting to make the relevant movement.
After a segment has been simulated, the blocked time for the segment becomes the
average excess minutes per vehicle, incurred during the segment. The flow times are
updated by running the appropriate TC functions for the segment volumes. The turn
times are updated by running the intersection model with the previously noted initial
queues and the turning volumes obtained from the simulation.
The time fields in the network for the segment are now updated to be the sum of blocked
and flow times. Any user code for the ADJUST phase is executed.
Cube Avenue > Theory > Cube Avenue calculations > Speeds

Speeds
The link speeds are not used during the path building or simulation. They are calculated
immediately prior to network output as Speed = 60 Distance / Time. Note that the
speeds do not take turn times into account.
Cube Avenue > Theory > Functions and built-ins

Functions and built-ins

All the script variables that would normally be available in a highway assignment script
are still available. However there are some new script variables, and the interpretation of
some other script variables is modified. This section describes only the new or changed
variables:
• Storage

• TimeSegment

• SegmentStart

• Period

• Time, Cost, Vol, and AVGQDELAY

Cube Avenue > Theory > Functions and built-ins > Storage

Storage
There is a new script variable, STORAGE, that may be set during the LINKREAD
phase. Refer to the description in “LINKREAD phase” on page 1103.
Cube Avenue > Theory > Functions and built-ins > TimeSegment

T imeSegment
This is the time segment number. The user script may not assign values to this variable.
It takes the value zero during a static assignment, or during the static phase of a
combined assignment. It takes values 1, 2, 3, etc. as the dynamic time segments are
being processed.
TIMESEGMENT is iterated differently depending on the Avenue phase. Be aware that:
• The ILOOP phase loops through only the dynamic time segments, and thus will work
correctly with any TIMESEGMENT conditionals.

• The ADJUST phase is also executed within a dynamic time segment loop, but finishes with
TIMESEGMENT being set to 0. During this static time segment, a final run-through the
PHASE=ADJUST statements is performed.
Cube Avenue > Theory > Functions and built-ins > SegmentStart

SegmentStart
This is the time in minutes between the start of the modeled period and the start of the
time segment currently being processed. User script may not assign values to this
variable. It takes the value zero during a static assignment, or during the static phase of
a combined assignment. Note that this is a signed value, with negative numbers
indicating the current segment is a “warm-up” segment and non-negative values
indicating that this segment is within the model period.
Cube Avenue > Theory > Functions and built-ins > Period

Period
This is the duration of the period currently being processed in minutes. User script may
not assign values to this variable. It is the duration of the model period during a static
assignment, or during the static phase of a combined assignment. It is the duration of the
current time segment when time segments are being processed.
Cube Avenue > Theory > Functions and built-ins > Time, Cost, Vol, and AVGQDELAY

T ime, Cost, Vol, and AVGQDELAY

Internally, these link arrays become two-dimensional, with one dimension referring to the
time segment and the other referring to the link number. In the output network, the values
referring to different time segments will be given different names (see “Output data” on
page 1121).
When script is being executed, it will be in the context of the model period, or of the
current time segment as appropriate.
However, some care needs to be taken when calculations involve both “ordinary” link
arrays and these time-segment vectors of link arrays. For example, a common way of
handling costs for multi user class assignment is to calculate costs into a work variable:
LW.TRUCK_COST=DISTANCE+TIME
LW.CAR_COST=DISTANCE/2+TIME*1.5

In a Cube Avenue dynamic assignment, this will result in both link variables having the
cost values applicable to the last time segment. (Although the values for each time
segment in turn will be assigned to the link variables, they are not vectored, and the
costs associated with one time segment overwrite those associated with the previous
one.) To correctly calculate costs by user class, more work variables must be used:
IF (TIMESEGMENT=1)
LW.TRUCK_COST1=DISTANCE+TIME
LW.CAR_COST1=DISTANCE/2+TIME*1.5
ENDIF
IF (TIMESEGMENT=2)
LW.TRUCK_COST2=DISTANCE+TIME
LW.CAR_COST2=DISTANCE/2+TIME*1.5
ENDIF

Note here that TIMESEGMENT=2 is explicitly tested, instead of indirectly with an ELSE
statement. The last time segment normally iterated in an ADJUST phase is 0 — which is
not a desired in this example.
The new variables can be used in a DYNAMICLOAD statement. For example:
DYNAMICLOAD PATH=LW.TRUCK_COST__TS__
Cube Avenue > Examples

Examples
This section contains examples of Cube Avenue scripts:
• Example 1: Program

• Example 2: Add parameters

• Example 3: LINKREAD

• Example 4: Simplifying LINKREAD

• Example 5: Centroids

• Example 6: ILOOP

• Example 7: ADJUST

• Example 8: Enhancing ADJUST

• Example 9: Packet logs

• Example 10: Tuning parameters

• Example 11: Reducing segment and volume lists

Cube Avenue > Examples > Example 1: Program

Example 1: Program
Call Cube Avenue just as you call other Cube Voyager programs, with “RUN PGM=....”
Place all statements and keywords that control the run in a “RUN... ENDRUN” block.
You can specify an output print file after a “PGM=AVENUE PRNFILE=” statement.
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”
FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"
FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
ENDRUN
Cube Avenue > Examples > Example 2: Add parameters

Example 2: Add parameters

This example adds some parameters to the Cube Avenue script:
• MAXITERS specifies the maximum number of iterations.

• COMBINE specifies the method of combining iterations together. In this case, the method is
AVE, successive averages. AVE is the recommended method for equilibrium dynamic
assignment.

• MODELPERIOD specifies the duration of the modeled time period, in minutes.

• SEGMENTS specifies a list of durations for each modeled time segment.

In this example, the sum of the segments exceeds the model period. Cube Avenue
treats the excess time as a “warm up” prior to the model period.
In addition, this example seeds the random number generator. Seeding the random
number generator makes results repeatable between multiple runs of the same
assignment. The internal random number generator randomly draws a departure time for
each packet departing in a given interval.
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE="{SCENARIO_DIR}\OUT.PRN“
FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"
FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
PARAMETERS MAXITERS=10, COMBINE=AVE,
MODELPERIOD=90, SEGMENTS=30,30,30,30, ;30 min warm-up
X=RANDSEED(165) ; seed random numbers
ENDRUN
Cube Avenue > Examples > Example 3: LINKREAD

Example 3: LINKREAD
Just as in the Highway model, Cube Avenue reads the input network and uses either
user expressions or default rules to initialize important link variables. This example
shows:
• DISTANCE — Used with other variables to calculate default T0 and STORAGE values.

• SPEED — Used with DISTANCE to calculate default T0 values.

• T0 — Free-flow link travel time.

• STORAGE — Number of vehicles that can physically fit on a link (should not be zero).

• LINKCLASS — Function index number for calculating congested time and cost.

• C — Flow rate capacity, in vehicles per model period. You might need to convert from
hourly capacities.
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”
FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"
FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
PARAMETERS MAXITERS=10, COMBINE=AVE,
MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up
PHASE=LINKREAD
DISTANCE=LI.FEET/5280 ;converting to miles
SPEED=LI.MPH
T0=60*DISTANCE/SPEED ;time in minutes
C=LI.LANES*LI.LNCAP*1.5 ;scale to model period
STORAGE = DISTANCE*LI.LANES*LI.VEHPERLNMI
IF (STORAGE=0) STORAGE=9999999
LINKCLASS = LI.FTYPE
ENDPHASE
ENDRUN
Cube Avenue > Examples > Example 4: Simplifying LINKREAD

Example 4: Simplifying LINKREAD

Not every link variable needs an explicit expression. For example, if the input network
has values for LANES and DISTANCE, then Cube Avenue can compute STORAGE
using the formula VehPerDist * LANES * DISTANCE. (The default value for VehPerDist
is 181.81.)
Citilabs recommends using different STORAGE values for arterials and freeways. In
Cube, you can define a network variable named STORAGE. Input network fields named
STORAGE, CAPACITY, and TIME override any default calculations for these variables.
Because the network’s input capacity is specified in vehicles per hour, the example uses
the CAPFAC parameter to scale the value to the model period duration.
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”
FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"
FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up
PHASE=LINKREAD
;Automatically use STORAGE from network, which was
;calculated in Cube editor window based on HCM:
; freeway storage = 120 vehicles/ln-mi
; arterial storage = 220 vehicles/ln-mi
;Also use TIME from network for T0
; as well as input CAPACITY for C
;Accordingly DISTANCE and SPEED are not used
ENDPHASE
ENDRUN
Cube Avenue > Examples > Example 5: Centroids

Example 5: Centroids
Centroid connectors connect zones to the network; they do not represent physical road
features. Therefore, in Cube Avenue, you must define these links to have infinite (that is,
very large) capacity, infinite storage, and zero travel time.
Because links with zero capacity and storage can cause problems in dynamic
assignment, you must find such links and give them large capacity and storage values,
also.
This example assigns all centroid connectors LINKCLASS=2 using the ZONES
variable.
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”

FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"

FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up
PHASE=LINKREAD
;Automatically use STORAGE from network, which was
;calculated in Cube network editor based on HCM:
; freeway storage = 120 vehicles/ln-mi
; arterial storage = 220 vehicles/ln-mi
;Also use TIME from network for T0 as well
; and input CAPACITY for C
IF (A<=ZONES||B<=ZONES) LINKCLASS=2
IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999
IF (LINKCLASS==2||C==0) C=9999999
IF (LINKCLASS==2) T0=0
ENDPHASE

ENDRUN
Cube Avenue > Examples > Example 6: ILOOP

Example 6: ILOOP
During each main iteration, Cube Avenue loops through all the input zones, creates
packets for assignment, and builds dynamic (time-varying) paths.
The statement DYNAMICLOAD PATH=COST tells Cube Avenue to build dynamic paths using
congested travel costs by time segment. By default, this is the same as TIME, which is
initially the free-flow link travel time.
The input matrix for this example contains three tables, one for each half hour of the
model period. The statement PACKETSIZE=1 groups the input vehicle trips into
packets with a target size of one vehicle (recommended for the default Packet Allocation
mode). The tables listed in VOL[1] specify the matrix to use for each time segment,
including warm-up.
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”
FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"
FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up
PHASE=LINKREAD
IF (A<=ZONES||B<=ZONES) LINKCLASS=2
IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999
IF (LINKCLASS==2||C==0) C=9999999
IF (LINKCLASS==2) T0=0
PHASE=ILOOP
DYNAMICLOAD PATH=COST, PACKETSIZE=1,
VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3
ENDPHASE
ENDRUN
Cube Avenue > Examples > Example 7: ADJUST

Example 7: ADJUST
When a script calls one or more DYNAMICLOAD statements, Cube Avenue simulates the
movement of packets through the network during the ADJUST phase.
After simulating packets and recording link volumes, Cube Avenue uses delay functions
to calculate congested travel times by segment. By default, Cube Avenue adjusts all
links using the standard BPR formula:
TC[1] = T0 *(1 + 0.15* (V/C) ^ 4)
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”

FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"

FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up
PHASE=LINKREAD
IF (A<=ZONES||B<=ZONES) LINKCLASS=2
IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999
IF (LINKCLASS==2||C==0) C=9999999
IF (LINKCLASS==2) T0=0
PHASE=ILOOP
DYNAMICLOAD PATH=COST, PACKETSIZE=1,
VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3
PHASE=ADJUST
ENDPHASE

ENDRUN
Cube Avenue > Examples > Example 8: Enhancing ADJUST

Example 8: Enhancing ADJUST

The standard BPR formula, which does not degrade link performance significantly until
volumes exceed capacity, is inadequate for Cube Avenue, where assignment volumes
never exceed capacity.
This example implements a performance function from Chapter 30 of the Highway
Capacity Manual 2000. In this example:
• LI.DO represents free-flow signal delay.

• LI.J represents a calibration parameter coded directly into the network, based on facility
type.

• LINKCLASS=2 represents centroid connectors, which should not degrade performance.

The example introduces a custom COST function that incorporates vehicle operating
costs and tolls into route-choice behavior. The units of COST are monetary.
; Do not change filenames or add or remove FILEI/FILEO
; statements using an editor. Use Application Manager.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”

FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"

FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up
PHASE=LINKREAD
IF (A<=ZONES||B<=ZONES) LINKCLASS=2
IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999
IF (LINKCLASS==2||C==0) C=9999999
IF (LINKCLASS==2) T0=0
PHASE=ILOOP
DYNAMICLOAD PATH=COST, PACKETSIZE=1,
VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3
PHASE=ADJUST
Function TC[1]=T0+LI.D0+(0.25*30)*((V/C-1)+
SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/30^2)))
Function TC[2]=T0
Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL
Function COST[2]=TIME
ENDPHASE

ENDRUN
Cube Avenue > Examples > Example 9: Packet logs

Example 9: Packet logs

With the FILEO PACKETLOG statement, Cube Avenue generates an output log file
containing simulated packet movements. This example modifies the output file with
several options:
• ORIGIN / DESTINATION — Lists origins and destinations of output packets

• DEPARTTIME / ARRIVALTIME — Lists departure and arrival times (in seconds) of output
packets

• SELECTLINK — Lists links that output packets must pass through

• SELECTGROUP — List link groups that output packets must pass through

• MUSTMEETALL — Set to F, specifying that links specify an area; hence output packets
must pass through at least one of the specified links, but not necessarily all of the links

• AFTERITER — Delays writing the packet log until the specified iteration

• FORMAT — Specifies that the output be written to a binary log file rather than default text
format
RUN PGM=AVENUE PRNFILE="{SCENARIO_DIR}\OUT.PRN"

FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"

FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.LOG",
ORIGIN=1-10, DESTINATION=1-10,
DEPARTTIME=1800-3600, ARRIVALTIME=1800-3600,
SELECTLINK=(L=101-1903*), SELECTGROUP=3,
MUSTMEETALL=F, AFTERITER=9, FORMAT=BIN
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up
PHASE=LINKREAD
IF (A<=ZONES||B<=ZONES) LINKCLASS=2
IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999
IF (LINKCLASS==2||C==0) C=9999999
IF (LINKCLASS==2) T0=0
IF (LI.TOLL>0) AddToGroup=3
PHASE=ILOOP
DYNAMICLOAD PATH=COST, PACKETSIZE=1,
VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3
PHASE=ADJUST
Function TC[1]=T0+LI.D0+(0.25*30)*((V/C-1)+
SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/30^2)))
Function TC[2]=T0
Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL
Function COST[2]=TIME
ENDPHASE
ENDRUN
Cube Avenue > Examples > Example 10: Tuning parameters

Example 10: Tuning parameters

Cube Avenue generates packet flows that depart intermittently throughout the model
period, and builds time-varying paths for these flows. This computation-intensive
process can result in slow run times.
You can use the parameter MaxPthPerSeg to limit the number of paths that Cube
Avenue builds for each origin-destination pair in each time segment. This example has a
segment duration of 30 minutes. A MaxPthPerSeg value of 10 forces packets within
three-minute intervals to use the same path. This reduces the number of built paths and
improves computation time, but can introduce model granularity.
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”

FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"

FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.LOG",
ORIGIN=1-10, DESTINATION=1-10,
DEPARTTIME=1800-3600, ARRIVALTIME=1800-3600,
SELECTLINK=(L=101-1903*), SELECTGROUP=3,
MUSTMEETALL=F, AFTERITER=9, FORMAT=BIN
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=30,30,30,30, MaxPthPerSeg=10
PHASE=LINKREAD
IF (A<=ZONES||B<=ZONES) LINKCLASS=2
IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999
IF (LINKCLASS==2||C==0) C=9999999
IF (LINKCLASS==2) T0=0
IF (LI.TOLL>0) AddToGroup=3
PHASE=ILOOP
DYNAMICLOAD PATH=COST, PACKETSIZE=1,
VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3
PHASE=ADJUST
Function TC[1]=T0+LI.D0+(0.25*30)*((V/C-1)+
SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/30^2)))
Function TC[2]=T0
Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL
Function COST[2]=TIME
ENDPHASE
ENDRUN
Cube Avenue > Examples > Example 11: Reducing segment and volume lists

Example 11: Reducing segment and volume lists

When using many time segments, segment and volume lists can become long and
unwieldy.
The SEGMENTS parameter supports the repetition (*) operator. If the time segments
are of equal duration, you can specify them using the syntax:
SEGMENTS=N*DUR

where:
• N is the number of modeled time segments

• DUR is the duration of each segment

In addition, when the “_TS_” notation is used within MW brackets for VOL, Cube
Avenue substitutes the expression with an MW vector that contains the number of time
segments (replacing “_TS_” with the time segment’s index).
RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.PRN”
FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET"
FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT"
FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.LOG",
ORIGIN=1-10, DESTINATION=1-10,
DEPARTTIME=1800-3600, ARRIVALTIME=1800-3600,
SELECTLINK=(L=101-1903*), SELECTGROUP=3,
MUSTMEETALL=F, AFTERITER=9, FORMAT=BIN
PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5,
MODELPERIOD=90, SEGMENTS=4*30, MaxPthPerSeg=10
PHASE=LINKREAD
IF (A<=ZONES||B<=ZONES) LINKCLASS=2
IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999
IF (LINKCLASS==2||C==0) C=9999999
IF (LINKCLASS==2) T0=0
IF (LI.TOLL>0) AddToGroup=3
PHASE=ILOOP
MW[1]=mi.1.1
MW[2]=mi.1.1,MW[3]=mi.1.2,MW[4]=mi.1.3
DYNAMICLOAD PATH=COST, PACKETSIZE=1,
VOL[1]=MW[__TS__]
PHASE=ADJUST
Function TC[1]=T0+LI.D0+(0.25*15)*((V/C-1)+
SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/15^2)))
Function TC[2]=T0
Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL
Function COST[2]=TIME
ENDPHASE

ENDRUN
Cube Cluster > Using Cube Cluster

Using Cube Cluster

This section provides information about using Cube Cluster. Topics include:
• Cube Cluster introduction

• Cube Cluster control statement summary

• Working with Cube Cluster

Cube Cluster > Using Cube Cluster > Cube Cluster introduction

Cube Cluster introduction

A computer cluster is a group of loosely coupled computers that work together closely
so that in many respects they can be viewed as though they are a single computer. The
components of a Cluster are commonly, but not always, connected to each other
through fast local area networks. Clusters are usually deployed to improve speed and/or
reliability over that provided by a single computer, while typically being much more cost-
effective than single computers of comparable speed or reliability.
Clusters are typically configured for either high availability or high performance. High
availability clusters are configured for redundancy and make use of redundant nodes to
provide continuous service when primary nodes fail. This type of cluster would
commonly be used for a Web server for high volume web sites where continuous
access is in demand.
High-performance clusters increase performance by splitting a computational task
across many different nodes in the cluster. These clusters are most common in scientific
computing. High-performance clusters are optimal for workloads that require the
processes on separate computer nodes to communicate actively during the
computation. This includes computations where intermediate results from one node’s
calculations affect future calculations on other nodes.
Cube Cluster implemented in Cube Voyager allows you to create your own high-
performance computer cluster to distribute the workload of your Cube Voyager model
run across multiple computing nodes. Each computing node consist of a single
computer processor so assembling your own computer cluster is as simple as
networking several existing computers together on a local area network. Many office
environments already have such local networks of computers in place which can be
utilized to support Cube Cluster. Alternatively, dedicated machines could be connected
together on a local network to form an independent modeling cluster for dedicated
modeling work independent of regular office computing. Still a third and potentially
superior alternative would be to purchase a dedicated multiprocessor machine with each
processor acting as a cluster node so that all of the computation and data sharing is
contained in one local machine and is not dependent on you local network connections.
Cube Cluster can be used to significantly reduce model run time by distributing steps in
the model flow that are not dependent on one another and executing them
simultaneously on distributed or parallel processing nodes. Most travel demand models
will have some steps that are choke points in the model flow: additional following steps
require the outputs of these steps before they can be run. Most travel demand models
will also have many steps that can be run at the same Itime if independent processing
nodes are available. Some reconfiguration of the model flow may be required to group
those steps together that can be run simultaneously.
Cube’s Application Manger flow chart view of your model provides a convenient tool for
identifying the model steps in an application that can be distributed. Model step
dependencies are easily visible from the data flows presented in the flow chart. An
example is shown in the figure below. This is a fairly typical transit network development
and skimming (level of service) process that might be present in many models. Transit
network definitions and skim matrices are produced for two periods (peak and off peak
travel) and for two separate modes of access (drive and walk only). Each of these steps
is independent of each other. Assume that each of these steps run in approximately 9 to
11 minutes. This implies a total run time for this group of about 40 minutes if run
sequentially as is the normal practice. If four processing nodes are available so that
each step is distributed to a separate node using Cube Cluster, then all four steps would
be executed simultaneously. The result under Cube Cluster would be that the run time
for the group would now be limited to approximately the time of the longest running
individual step in the group or about 11 minutes. This is a time saving of 29 minutes or a
reduction in run time for the group of about 72%. If this transit group is nested in a model
feedback loop which also exists in many models then the whole model process would
be saving about 29 minutes for every iteration of the model feedback loop.
Cube Cluster > Using Cube Cluster > Cube Cluster introduction > Typical transit skimming process: Period by access

T ypical transit skimming process: Period by access

Citilabs undertook some performance testing of Cube Cluster utilizing a recently
completed client model implement in Cube Voyager that has high model run time due to
the size of the region and the complexity of the model structure. The test utilized readily
available off the self computer hardware that was rented from a computer rental firm. It
was felt that this level of hardware would be reasonably representative of the type of
hardware that our typical clients would already have in place. Ten identical computer
workstations were rented and loaded with the beta version of Cube Voyager and Cube
Cluster. The results of the run time test are shown in the figure below for varying
numbers of processing nodes. Also shown are the theoretically ideal run times if all
processors could be utilized at all times during the model runs. The difference between
the two curves is the result of model steps that cannot be distributed and some
increases in I/O time attributed to assembly results from multiple process node back to a
common working folder.

There are two forms of distributed processing available in Cube Voyager:

• Intrastep distributed processing (IDP)
This type of distributed processing works by breaking up zone based processing in a
single step into zone groups that can be processed concurrently on multiple
computing nodes. Currently only the Matrix and the Highway programs are available
for IDP. IDP works for most type of Matrix (zone based, not RECI) and Highway
processing as long as each zone can be independently processed (see “Procedures
that disable intrastep distributed processing” on page 1172 for a discussion of the
types of process not supported by IDP).
• Multistep distributed processing (MDP)
This type of distributed processing works by breaking up blocks of one or more
modeling steps and distributes them to multiple computing nodes to process. This
 can be used for any program in Cube Voyager as well as user-written programs with
the caveat that the distributed blocks and the mainline process must be logically
independent of each other. For example, you can not run skimming procedures at the
same time or before you have updated the speeds in the network you intend to skim.
However, you can assign peak and off-peak period transit networks concurrently in
most models. Understanding these basic relationships and dependencies in a model
is very important to successfully implementing MDP.
Cube Voyager uses a simple file based signaling method for communication between
the main process and the sub-processes. Because of the zone independent
requirement on IDP and the step independent requirement on MDP, it requires carefully
planning and setup by the user to implement this system. The main process will check if
a sub-process is available before assigning a task to it and check the sub-process run
return code for errors. However, any crashes on a sub-process computer will cause the
main process to wait forever and will need to be manually terminated by the user on the
main as well as the sub-process computers. This should not be a problem if used with
models in “production” mode that should not have any syntax or logic errors.
For distributed processing to work, the main process and all the sub-processes must
have access to a shared drive on a computer network so that they can share data. The
main process and all the sub-processes must map the shared drive to the same drive
letter (the Subst system command can be used to map a local drive to another drive
letter that matches the other processes) and they all must start with the same work
directory, unless the CommPath feature is used. This is because input and script files
are referenced by drive letter and directory location during a run and if they are
unavailable in that location, the run will fail.
Running on a network drive could significantly slow down a run for disk intensive
applications depending on the computer network’s throughput capacity so there may be
little runtime benefit or take even longer when using DP on certain steps. Therefore, it is
important to “tune” the DP setup to get the best performance. In general, DP works well
for computation-intensive applications (for example, doing hundreds of matrix
computations for each zone in a mode choice step) but will result in less time savings for
disk intensive procedures (for example, combining 3 matrix files into one matrix file).
Cube Cluster > Using Cube Cluster > Cube Cluster control statement summary

Cube Cluster control statement summary

Co ntro l s ta te me nt D e s c rip tio n

DISTRIBUTE Global control for DP options.

DistributeMULTISTEP Initiates MDP script block in Pilot

unless the global switch is off.

EndDistributeMULTISTEP Ends a MDP script block in Pilot.

Wait4Files Sets a wait condition to insure all

MDP steps of a block are
completed prior to running
subsequent model steps

The following control statements are available in the Cube Voyager Matrix and Highway
programs to implement IDP

Co ntro l s ta te me nt D e s c rip tio n

DistributeINTRASTEP Initiates IDP of the current Matrix or

Highway step.
Cube Cluster > Using Cube Cluster > Working with Cube Cluster

Working with Cube Cluster

Implementing Cube Cluster should generally be performed after model development
and calibration/validation. When you are satisfied with the results of your model or model
process when running on a single processing node then implement Cube Cluster to
distribute sub-process of your model and fine-tune the distribution process to achieve
the optimal or satisfactory run time reduction.
The DISTRIBUTE statement in Cube Cluster globally controls the DP options:
DISTRIBUTE INTRASTEP=[T/F] MULTISTEP=[T/F]

The default is T (true) for both types of DP (INTRASTEP=T, MULTISTEP=T) when a

Cube Voyager run is started. If turned off, distributed processing will not be invoked
even if there are DistributeINTRASTEP and DistributeMULTISTEP statements in the
following script.
Subsequent sections discuss:
• File and folder permissions in a distributed environment

• Limitations with Random Number Generation

• Using Cluster with HIGHWAY

• Intrastep distributed processing (IDP)

• Multistep distributed processing (MDP)

• Procedures that disable intrastep distributed processing

• Using IDP for steps that summarize zonal values

Cube Cluster > Using Cube Cluster > Working with Cube Cluster > File and folder permissions in a distributed environment

File and folder permissions in a distributed environment

When setting up a distributed process across a network using Cube Cluster, you must
ensure that all read/write permissions are properly set across the machines in the
cluster.
Citilabs recommends mapping the model folder to a shared drive letter and setting all file
paths in the model application relative to this drive location. Set the working directories of
the Cube Voyager instances running in wait mode on each cluster node to this common
drive location. With this configuration, all the file I/O references in the scripts that run
from any of the node processors will correctly reference the model folder. The node
machines and the main control machine must have read/write permission to the mapped
model folder.
For machines configured with multiple user accounts that have different permission
settings, users logged in without full administrator privileges on the main or node
machines can cause access problems. Users logged in without full privileges usually do
not have full read and write permissions to folders created on the same machine but with
a different login ID unless permissions are explicitly given.
Cube Cluster > Using Cube Cluster > Working with Cube Cluster > Limitations with Random Number Generation

Limitations w ith Random N umber Generation

If a distributed model uses random numbers, each cluster node will have its own random
number generator, and thus its own random series. This is because the nodes run in
separate processes.
Suppose the model’s random seed starts at zone 1 with:
IF (i==1) X=RANDSEED(12345)

If this model is distributed, the final results will be different than the standalone case, for
the cluster nodes not using zone 1 will use different seeds.
However, each node’s random numbers could be explicitly spawned from the same
seed (or, the necessary random series could be otherwise generated ahead of time).
For example:
X=RANDSEED(12345)

All cluster nodes executing this command will use the same random series. This
potentially defeats the purpose of using random number generation to begin with.
Citilabs recommends against using Cluster with models with random generation, unless
absolutely necessary.
Cube Cluster > Using Cube Cluster > Working with Cube Cluster > Using Cluster with HIGHWAY

Using Cluster w ith HIGHWAY

When using Cluster with highway, note that:
• If a distributed model computes link work (LW) arrays in the ILOOP phase, the results will
be incorrect outside of the current I zone. This is because each distributed node will have
its own copy of the arrays and they are not combined at the end of the iteration. Cluster
requires link work arrays to be computed in the ADJUST phase, and used in the ILOOP
phase. This is the standard usage. The only exception is when the array is computed and
used within the same I zone only.

• Use of Cluster can have a very small effect on volumes generated by the HIGHWAY
program. During the ADJUST phase, when iteration volumes are combined, the final
assigned volumes might vary slightly over different numbers of cluster nodes.
Please see the PARAMETERS COM BINE EQUI sub-keyword, which controls the Standard
equilibrium processing in Highway. When ENHANCE is set to 2 (Bi-conjugate Frank-
Wolfe algorithm), the effect is most noticeable. The differences are less pronounced
with ENHANCE = 1 (Conjugate Frank-Wolfe algorithm), and extremely minimal with
ENHANCE = 0 (standard Frank-Wolfe algorithm, the default for EQUI).

The difference in all cases is negligible, and an unavoidable aspect of floating point
arithmetic when distributed over cluster nodes. If this is an issue for your application,
Citilabs recommends standardizing the number of cores for the model.
Cube Cluster > Using Cube Cluster > Working with Cube Cluster > Intrastep distributed processing (IDP)

Intrastep distributed processing (IDP)

To implement IDP, add the following statement in the appropriate Matrix or Highway
script (within the Run/EndRun block):
DistributeINTRASTEP ProcessID='TestDist',
ProcessList=1-4,
MinGroupSize=20, SavePrn=T

This statement will invoke intrastep distributed processing in the program unless the
global switch is off. Before running the job in the main computer, all the sub-process
computers participating in the DP must be started and in the wait mode with the correct
file name to wait for. The ProcessID and the process numbers in the ProcessList are
used to make up the name of the wait file. See “Utilities” on page 1181 for tools and
examples of how to start multiple instances of Cube Voyager in WAIT mode with the
appropriate settings prior to starting a distributed run.
The ProcessID is the prefix for the file names used to communicate with the sub-
processes. ProcessList is a list of sub-processes to use for DP. It is a list of numbers
and put in as individual numbers or ranges (for example, ProcessList=1,5,10-20,25).
Each sub-process must be assigned a unique process number.
MinGroupSize is the minimum distributed zone group size. If there are more sub-
processes than there are zone groups of this size, then some sub-processes will not be
used. For example, if there are 100 zones and MinGroupSize is 20 and ProcessList=1-
10, only 4 sub-processes will be used to process 20 zones each and the main process
will process 20 zones itself.
SavePrn is a switch to control if the sub-process print files should be saved or not. The
default is F (false) for this keyword. The IDP process automatically merges the script
generated information (from Print statements etc.) and error messages from sub-
process print files into the main print file so there is little reason to save the sub-process
print files except for debugging purposes.
With the example of ProcessID='TestDist' and ProcessList=1-4 above, four sub-
processes will be used. The script files that each of the sub-process is looking for is
{ProcessID}{Process#}.script. So in this example, the 4 sub-process will start with the
following script file to look for:
Sub 1 : TestDist1.script
Sub 2 : TestDist2.script
Sub 3 : TestDist3.script
Sub 4 : TestDist4.script
Cube Voyager must be started on each of the processor nodes for each of the sub-
processes and the above script names and common working directory set and then
press the Wait Start button to go into wait mode. Cube Voyager can also be started with
command line parameters:
Voyager TestDist1.script /wait

This will put Cube Voyager in the wait mode automatically. If the current directory is the
work directory, then no drive/path is needed when specifying the script file name,
otherwise, full path name should be used when specifying the script file.
If the processor nodes of your cluster are separate single processor computers
connected via a local network then you will need to start an instance of Cube Voyager
on each of the computers in your cluster and set the appropriate script name for that
node. Each processor node in the cluster should correspond to one of your process
numbers set with the ProcessList= keyword. For example, on the first computer in the
cluster, Cube Voyager would be launched and placed into wait mode after setting the
Input Job File and the common working directory. Note that the common working
directory when using networked processing nodes must be mapped on all processing
nodes to the same physical location which is the working directory. If the processing
nodes are all nodes on a common multiprocessor machine then multiple instances of
Cube Voyager can be started and put into wait mode directly on the multiprocessor
machine and the working directory can simply be the model folder on the multiprocessor
machine. Note also that both these conditions can apply. A computer cluster for
distributed processing could be a mixture of a multiprocessor machine with several
processing nodes connected to additional single or multiprocessor machines across a
local area network. See “Utilities” on page 1181 for additional information on getting
multiple instances of Cube Voyager open and configured in wait mode.

When all the sub-processes are in wait mode, start the Cube Voyager run like a normal
run in the main computer.
Cube Cluster > Using Cube Cluster > Working with Cube Cluster > Multistep distributed processing (MDP)

Multistep distributed processing (MDP)

To implement MDP, add the following statement in the CLUSTER script at the beginning
of the distributed script block:
DistributeMULTISTEP ProcessID='TestDist', ProcessNum=5

Also, add the following statement in the CLUSTER script at the end of the distributed
script block:
EndDistributeMULTISTEP

This statement will invoke MDP in Pilot unless the global switch is off. Before running the
job in the main computer, the sub-process node participating in this MDP must be
started and in the wait mode with the correct file to wait for. See “Utilities” on page 1181
for additional information on getting multiple instances of Cube Voyager open and
configured in wait mode. The Pro cessID and the Pro cessNum number are used to make
up the name of the wait file. Pro cessID is the same as defined above for IDP. Pro cessNum
is a single process number since the steps are distributed to one process only.
When a block of operations is distributed to another processing node, the main
computer will continue running the script without waiting for the sub-process on this other
processing node to finish. It is the user’s responsibility to check for sub-process
completion before using output files generated by the sub-process. When a sub-
process is done, it will create a file named {ProcessID}{Process#}.script.end. Use the
W ait4Files command to wait for the .end file to be created in Pilot. For example:
Wait4Files Files=TestDist1.script.end, TestDist2.script.end,
TestDist3.script.end, CheckReturnCode=T,
UpdateVars=vname,Matrix.xname, PrintFiles=Merge, DelDistribFiles=T

Alternately, you may represent Files as a comma-separated, non-spaced list of files in a

Pilot variable:
MYFILES=’TestDist1.script.end,TestDist2.script.end,TestDist3.script.end’

Wait4Files Files=@MYFILES@, CheckReturnCode=T,

UpdateVars=vname,Matrix.xname, PrintFiles=Merge, DelDistribFiles=T

The Files keyword specifies a list of all the files to wait for and the CheckReturnCo de
keyword specifies if the return codes from the sub-processes should be checked. When
true, the whole run will stop if a sub-process returns with a code 2 (fatal) or higher.
The UpdateVars keyword specifies a list of global variables computed in Pilot and logged
from individual programs that should be merged back from the sub-process run. Any
variables with the first part of the name matching an UpdateVars name will be merged
back. For example, for UpdateVars=vname,Matrix.xname, variable
vname1,vnameabc,Matrix.xnamevar etc. will all be merged back to the main process.
Care must be taken to merge back ONLY the variables that need to be returned to the
main process. Consider the following example:
ThisVar=1
DistributeMULTISTEP ProcessID='TestDist', ProcessNum=5
Run pgm=Matrix
...
EndRun
Run pgm=Network
...
EndRun
EndDistributeMULTISTEP

ThisVar=2

Wait4Files Files=TestDist5script.end, CheckReturnCode=T,

UpdateVars=ThisVar, PrintFiles=MERGE, DelDistribFiles=F

During execution, after the W ait4Files statement, the variable ThisVar will have the value
of 1. This is because the subprocess inherits a copy of all the global variables to start
with (ThisVar=1), so even though the subprocess never modifies the value of ThisVar,
the update process will change ThisVar back to 1. The setting of ThisVar to 2 in the
main process will be overwritten in this case.
The PrintFiles keyword controls the disposition of the print files from the sub-processes. It
can be “MERGE,” “MERGESAVE,” “DELETE,” or “SAVE.” MERGE means the print
files will be merged back into the main print file then deleted. MERGESAVE means to
merge the files but not delete them. DELETE means no merge but delete them and
SAVE means no merge but save them. The default is SAVE.
The DelDistribFiles keyword controls the disposition of the MDP temporary
communication files. The default is true, meaning to remove all temporary files.
Cube Cluster > Using Cube Cluster > Working with Cube Cluster > Multistep distributed processing (MDP) > Examples

Exam ples

Intrastep distributed processing:

Run pgm=Matrix
FileI MatI=...
FileO MatO=...
DistributeINTRASTEP ProcessID='TestDist',ProcessList=1-4
...
EndRun

Multistep distributed processing:

DistributeMULTISTEP ProcessID='TestDist', ProcessNum=5
; the following 3 steps will be distributed to another processing node
Run pgm=Matrix
...
EndRun
Run pgm=Network
...
EndRun
Run pgm=Highway
...
EndRun
EndDistributeMULTISTEP
; run the following 2 steps while the sub-process is doing the 3 steps above
Run pgm=Public Transport
...
EndRun
Run pgm=Fratar
...
EndRun
; wait for the sub-process to finish before continuing
Wait4Files Files=TestDist5.script.end, CheckReturnCode=T
; continue running on successful end of the sub-process 5
Run pgm=Network
...

Using both Intra and Multi Step Distribution with 12 processing nodes (main, GroupA 1-
4, GroupB 1-4, GroupC 2-4) to do AM, PM and Off-Peak assignments in parallel:
DistributeMULTISTEP ProcessID='GroupA', ProcessNum=1
; the following 2 steps will be distributed to sub-process GroupA1
Run pgm=Matrix
DistributeINTRASTEP ProcessID='GroupA',ProcessList=2-4
...
EndRun
Run pgm=Highway
DistributeINTRASTEP ProcessID='GroupA',ProcessList=2-4
...
EndRun
EndDistributeMULTISTEP
DistributeMULTISTEP ProcessID='GroupB', ProcessNum=1
; the following 2 steps will be distributed to sub-process GroupB1
Run pgm=Matrix
DistributeINTRASTEP ProcessID='GroupB',ProcessList=2-4
...
EndRun
Run pgm=Highway
DistributeINTRASTEP ProcessID='GroupB',ProcessList=2-4
...
EndRun
EndDistributeMULTISTEP
; run the following 2 steps while the sub-processes are running
Run pgm=Matrix
DistributeINTRASTEP ProcessID='GroupC',ProcessList=2-4
...
EndRun
Run pgm=Highway
DistributeINTRASTEP ProcessID='GroupC',ProcessList=2-4
...
EndRun
; wait for all the sub-processes to finish before continuing
Wait4Files Files=GroupA1.script.end, GroupB1.script.end,CheckReturnCode=T
Run pgm=Network
...
Cube Cluster > Using Cube Cluster > Working with Cube Cluster > Procedures that disable intrastep distributed processing

Procedures that disable intrastep distributed processing

In addition to the requirement of independent zone processing in IDP, the following
commands/options will cause IDP to turn off automatically due to data storage,
calculation or input/output requirements that would overtake any benefits that IDP would
provide:
• Highway program
m
Cube Avenue (dynamic traffic assignment)
m
REPORT VDTSPD
m
LOG

• Matrix program
m
FREQUENCY
m
RENUMBER

m
REPORT MARGINREC
m REPORT MARGINS
m
FILEI RECI
m
LOG

The following commands work in IDP mode but their behavior may be different in IDP:
• ABORT — The main process and any subprocess that encountered this command will abort
that process but other processes will continue to execute until the end. The main process
will then abort the run.

• EXIT— The main process and any subprocess that encountered this command will stop the
current ILOOP phase for that process but other processes will continue to execute until the
end of the ILOOP phase.

• ARRAY/SORT— Each process has its own arrays so the arrays will have to be filled in and sort
on each process.

• and IF (I=Zones) type statements to perform certain calculation/initialization/summary

IF (I=1)
processing only once per ILOOP phase will not work because not all processes will
process zone 1 and the last zone. Change the checks to use the following 3 new system
variables to determine if it is the first zone processed, the last zone processed and what is
the current process number:

• FIRSTZONE —
The first zone processed in the current processor. It will be 1 for a normal (non-
DP) run and will be the first zone to process in a DP run or a run with the SELECTI
keyword. For example, ‘IF (I=FirstZone)’ to perform initialization on the first zone
 processed.

• LASTZONE — The last zone processed in the current processor. It will be “zones” in a normal
run and will the last zone to process in a DP run or a run with the SELECTI keyword. For
example, “IF (I=LastZone)” to perform finalization on the last zone processed.

• THISPROCESS — The current process number. It will be -1 for a normal run, 0 for the DP main
controller, and the process number in a DP sub-process. With this a script can tell if it is
running in non-DP mode (ThisProcess = -1), it is running as the main (ThisProcess = 0), or
it is running as a node (ThisProcess > 0).
Cube Cluster > Using Cube Cluster > Working with Cube Cluster > Using IDP for steps that summarize zonal values

Using IDP for steps that summarize zonal values

In general, any step that summarizes zonal values may not use intrastep DP because
zones are processed in independent processes. However, under certain circumstances,
a step may be restructured to utilize IDP. For example, if a step summarize occupied
single family dwelling units (SFDU) by zone type and writes out a RECO file with a
record for each zone type:
; original script, sum occ. SFDU by ZoneType
run pgm=matrix
zdati=lu.dbf, z=zone ; has fields ZoneType and SFDU
reco=lusum.dbf, fields=ZoneType,SFDU
array SFbyType=9,SFOcc=9
zones=3000
if (i = 1) ; initial occupancy table
SFOcc[1]=0.91 SFOcc[2]=0.92 SFOcc[3]=0.93
SFOcc[4]=0.94 SFOcc[5]=0.95 SFOcc[6]=0.96
SFOcc[7]=0.97 SFOcc[8]=0.98 SFOcc[9]=0.99
endif
SFbyType[zi.1.ZoneType]=SFbyType[zi.1.ZoneType]+zi.1.SFDU*SFOcc[zi.1.ZoneType]
if (i = zones) ; write RECO at last zone
loop zt=1,9
ro.ZoneType=zt
ro.SFDU=SFbyType[zt]
write reco=1
endloop
endif
endrun

This step can be restructured into two steps, one to get the summary for each Cluster
node and a second step to combine the multiple data records for each zone type into a
single record for each zone type:
; Cluster script

run pgm=matrix
DISTRIBUTEINTRASTEP PROCESSID='TESTDIST', PROCESSLIST=1-3
zdati=lu.dbf, z=zone ; has fields ZoneType and SFDU
; write to temp reco file, use more precision on SFDU field
reco=tlusum.dbf, fields=ZoneType(3.0),SFDU(13.5)
array SFbyType=9,SFOcc=9
zones=3000
if (i = FirstZone) ; can not use if (i=1)
SFOcc[1]=0.91 SFOcc[2]=0.92 SFOcc[3]=0.93
SFOcc[4]=0.94 SFOcc[5]=0.95 SFOcc[6]=0.96
SFOcc[7]=0.97 SFOcc[8]=0.98 SFOcc[9]=0.99
endif
SFbyType[zi.1.ZoneType]=SFbyType[zi.1.ZoneType]+zi.1.SFDU*SFOcc[zi.1.ZoneType]
if (i = LastZone)
loop zt=1,9
ro.ZoneType=zt
ro.SFDU=SFbyType[zt]
write reco=1
endloop
endif
endrun

; extra step to combine RECO back to one record per ZoneType

run pgm=matrix
zdati=tlusum.dbf, z=ZoneType,sum=SFDU
reco=lusum.dbf, fields=ZoneType(3.0),SFDU(10.2)
zones=9
; write out the combined dbf record in the first zone processed
loop zt=1,zones
ro.ZoneType = zt
ro.SFDU = zi.1.SFDU[zt]
write reco=1
endloop
exit
endrun
Cube Cluster > Control statements

Control statements
This section describes the control statements for Cube Cluster:
• DISTRIBUTE

• DISTRIBUTEMULTISTEP

• ENDDISTRIBUTEMULTISTEP

• WAIT4FILES

• DISTRIBUTEINTRASTEP
Cube Cluster > Control statements > DISTRIBUTE

DISTRIBUTE
The DISTRIBUTE statement globally controls the DP options to turn on/off intrastep or
multistep distribute processing. Keywords include:
• MU LT IS T E P

• IN T R A S T E P

D IS T R IB U T E k e y wo rd s

Ke y wo rd D e s c rip tio n

MULTISTEP |?| Global

MULTISTEP DP
on/off

INTRASTEP |?| Global

INTRASTEP DP
on/off
Cube Cluster > Control statements > DISTRIBUTEMULTISTEP

DISTRIBUTEMULTISTEP
Invoke multistep distributed processing. Keywords include:
• P R OCE S S ID

• P R OCE S S N U M

• COMMP A T H

D IS T R IB U T E MU LT IS T E P k e y wo rd s

Ke y wo rd D e s c rip tio n

PROCESSID |S| Prefix for the file names used to

communicate with the sub-processes.
In addition to a string constant, a Pilot
string variable can be used to set the
ProcessID by putting it within @
characters (for example,
ProcessID=@MyID@).

PROCESSNUM |I| Single process number since the

steps are distributed to one process
only. In addition to a single numeric
constant, a Pilot numeric variable can
also be used to set the process
number dynamically (for example,
ProcessNum=MyProcess).

COMMPATH |S| Common path for checking for

availability of processors. Defaults to
null (working directory used).
The common path is only used for
initial communication with the node.
The node switches its work directory
to be the same as the main process
before running the multistep (or
intrastep) distributed process. After
completing the steps, the node reverts
to waiting for the communication file in
the COMMPATH directory.
This will work regardless of the
location of the script file and the work
directory of the main process. Nodes
can be waiting in the COMMPATH
directory, then when a model run
requests the node it will switch to the
work directory for that particular model
and run the steps. When it is done, it
will go back and wait for further
commands in the COMMPATH
directory.
Cube Cluster > Control statements > ENDDISTRIBUTEMULTISTEP

ENDDISTRIBUTEMULTISTEP
Statement to end current MULTISTEP subprocess.
Cube Cluster > Control statements > WAIT4FILES

WAIT4FILES
When a block of operations is distributed to another computer, the main computer will
continue running the script without waiting for the sub-process to finish. It is the user’s
responsibility to check for sub-process completion before using output files generated by
the sub-process. When a sub-process is done, it will create a {ProcessID}
{Process#}.script.end file. Use the Wait4Files command in the Pilot program to wait for
the .end file to be created. Keywords include:
• FILE S

• CH E CKR E T U R N COD E

• D E LD IS T R IB FILE S

• P R IN T FILE S

• UPDAT EVARS

W A IT 4FILE S k e y wo rd s

Ke y wo rd D e s c rip tio n

FILES |S| Specifies a list of all the files to wait for. In addition to a
string constant, a Pilot string variable can be used to set
the file names by putting it within @ characters (for
example, Files=@MyFile@).
The variable can be a comma-separated list of files with
no spaces; for example:

MYFILES=’Node1.script.end,Node2.script.end’

Wait4Files Files=@MYFILES@,
CheckReturnCode=T, DelDistribFiles=T

CHECKRETURNCODE |?| Specifies if the return codes from the sub-processes

should be checked. When true, the whole run will stop if a
sub-process returns with a code 2 (fatal) or higher.

DELDISTRIBFILES |?| Controls the disposition of the MDP temporary

communication files. The default is true, meaning to
remove all temporary files.

PRINTFILES |S| Controls the disposition of the print files from the sub-
processes. It can be “MERGE,” “MERGESAVE,”
“DELETE,” or “SAVE.” MERGE means the print files will be
merged back into the main print file then deleted.
MERGESAVE means to merge the files but not delete
them. DELETE means no merge but delete them and
SAVE means no merge but save them. The default is
SAVE.

UPDATEVARS |S| Specifies a list of global variables computed in Pilot and

logged from individual programs that should be merged
back from the sub-process run. Any variables with the first
part of the name matching an UpdateVars name will be
merged back. For example, for
UpdateVars=vname,Matrix.xname, variable
vname1,vnameabc,Matrix.xnamevar etc. will all be
merged back to the main process.
Cube Cluster > Control statements > DISTRIBUTEINTRASTEP

DISTRIBUTEINTRASTEP
Programs : Matrix, Highway
Invoke intrastep distributed processing. Currently only available in Matrix and Highway.
• COMMP A T H

• MIN GR OU P S IZE

• P R OCE S S ID

• P R OCE S S LIS T

• SAVEPRN

D IS T R IB U T E IN T R A S T E P k e y wo rd s

Ke y wo rd D e s c rip tio n

COMMPATH |S| Common path for checking for

availability of processors. Defaults
to null (working directory used).

MINGROUPSIZE |I| Minimum distributed zone group

size. If there are more sub-
processes than there are zone
groups of this size, then some sub-
processes will not be used. For
example, if there are 100 zones and
MinGroupSize is 20 and
ProcessList=1-10, only 4 sub-
processes will be used to process
20 zones each and the main
process will process 20 zones itself.

PROCESSID |S| The ProcessID is the prefix for the

file names used to communicate with
the sub-processes.

PROCESSLIST |I| List of sub-processes to use for DP.

It is a list of numbers and put in as
individual numbers or ranges (for
example, ProcessList=1,5,10-20,25).
Each sub-process must be
assigned a unique process number.

SAVEPRN |?| Switch to control if the sub-process

print files should be saved or not.
Cube Cluster > Utilities

Utilities
This section describes:
• Cluster executable

• Utility functions
Cube Cluster > Utilities > Cluster executable

Cluster executable
You may use the cluster.exe utility program to start multiple processing nodes on the
local machine. In this section there is information on:
• Cluster Dialog Box

• Running Cluster from the Command Line

• Starting processing nodes in Cube Cluster

Cube Cluster > Utilities > Cluster executable > Cluster Dialog Box

Cluster Dialog Box

Go to File > To o ls > Cluster No de M anagem ent to open the Cluster Node Management
dialog box.

• Select the W o rk D ire c to ry and P ro c e s s ID of the desired Cluster processes. Click B ro ws e to

pick a folder from the local system, or remote network.

• Under P ro c e s s Lis t, enter the applicable Process IDs.

• In Time to Wait for Response, enter the number of seconds Cube Cluster should wait for a
response from a node before determining that the node is unavailable.

• Click List Nodes to return the status of all processing nodes within the chosen Work Directory.

• Click Start Nodes to start all listed processing nodes (remote or local). Or, click S ta rt S e le c te d to
only start the selected node(s).

• Click Close Nodes to close all listed processing node (remote or local). Or, click Clo s e S e le c te d
to only close the selected node(s).

• Check H id e N e w N o d e s to minimize cluster nodes to the system tray. The nodes will be
hidden after they are Started. This is the same as clicking Hide on the associated Voyager
instance. Hiding is useful when the user wishes to minimize window clutter. (For more, see
page 15).
Cube Cluster > Utilities > Cluster executable > Running Cluster from the Command Line

Running Cluster from the Command Line

You can also run this program from a Windows command line. Therefore, you can run
the program from either a .bat batch file or from a Cube Voyager * command call. The
syntax for the command line is:
Cluster [ProcID] [ProcList] [Start/Starthide/Close/List] [Exit]

These command line options correspond to the Cluster dialog box shown above.
Cube Cluster > Utilities > Cluster executable > Starting processing nodes in Cube Cluster

Starting processing nodes in Cube Cluster

Prior to starting a distributed-processing run using Cube Cluster, individual instances of
Cube Voyager must be running and set to wait mode with the appropriate script file
name and work directory for the run. A Cube Cluster processing node corresponds to a
single, properly configured instance of Cube Voyager running and waiting. Processing
nodes can either be additional processors on the local computer (local nodes) or
processors on remote computers connected to the main computer over a local network
(remote nodes). You can start an instance of Cube Voyager manually by running the
Voyager.exe program in the Cube Voyager program directory and setting the script and
working directory, or by running the Cluster.exe program as described in “Cluster
executable” on page 1181.
You cannot start instances of Cube Voyager on remote nodes over a network. You must
start remote nodes directly on the remote machines. Typically, you must physically go to
each machine and run either the Voyager.exe or the Cluster.exe program on that
machine. Alternatively, you can use the COMMPATH keyword to send information to
active instances of Cube Voyager, which are open and running on remote processing
nodes. Use COMMPATH to send changes in script and working directory names to waiting
instances of Cube Voyager without having to physically visit each machine and make
changes manually.
You use COMMPATH only for initial communication with the node. The node will switch its
work directory to be the same as the main process before running the multistep
distributed process. After completing the steps, the node reverts to waiting for the
communication file in the COMMPATH directory. Citilabs recommends starting an instance
of Cube Voyager on each remote processor that you will use, setting the work directory
to a common path like z:\wait, and leaving them run. Then, you can use this value as the
COMMPATH keyword value.
Cube Cluster > Utilities > Utility functions

Utility functions
A number of utility functions were added to the Cube Voyager system to allow more
flexibility in performing distributed processing:
• FilesExist('file1|file2|file3...') — This function will check for the existence of one or more
files. The function takes one string argument (constant or variable) and if there are more
than one file to check, they are put into one string and separated by '|'. The return value is
the number of files that exist. If none of the files exist, then the return value will be zero.
This can be use instead of the Wait4Files command if you only want to check if a node is
done but don’t want to wait for it to get done.

• NumReadyNodes('ProcessID','ProcessList') — This function will check for availability of a

list of Cube Cluster nodes. The second argument is a string with the list of process
numbers to check. The return value is the number of ready nodes. For example,
NumReadyNodes('TestDist','1-5,10,15-20') or
NumReadyNodes(MyProcess,MyProcessList)

• FirstReadyNode('ProcessID','ProcessList') — This function will check for availability of a list

of Cube Cluster nodes and return the process number of the first available node. The
second argument is a string with the list of process numbers to check. The processes are
checked in the input order and can go from low to high or high to low so if the list is '6-2'
and all processes (2-6) are available, the result will be 6. For example,
FirstReadyNode('TestDist','1-5,10,15-20')

The following is an example for using the NumReadyNodes function when there are two
separate groups of Cube Cluster nodes that may be available to participate in a DP run,
the script wants to select the one with the most available nodes:
IF (NumReadyNodes(‘DP1’,’1-10’) > NumReadyNodes(‘DP2’,’11-20’))
MyProcessID=’DP1’
MyProcessList=’1-10’
ELSE
MyProcessID=’DP2’
MyProcessList=’11-20’
ENDIF

RUN PGM=Matrix
DistributeIntraStep ProcessID=@MyProcessID@, ProcessList=@MyProcessList@
Utilities > Shortest Path

Shortest Path
This section describes the Shortest Path calculation utilities included in Cube Voyager.
Topics include:
• Introduction

• Keywords and Usage

• Examples
Utilities > Shortest Path > Introduction

Introduction
If the user desires to run the path function a multiple number of times, the GUI-driven
shortest path build tool in Cube Base may not be a preferable method (see “Highway
path display” on page 265 of the Cube Base Reference Guide).
Therefore, a Cube Voyager program has been developed to run the path function
directly. With this, the user can input the following parameters directly in the script:
1. Cost Specification

2. File format (.DBF or .TXT)

3. Additional trace value

4. Include expressions

5. Path limiting parameters:

a. Maximum Path Cost
b. Maximum number of paths
c. Minimum number of paths
d. Number of times to increase the maximum cost to get minimum number

6. Turn Penalty

7. Turn Volume

8. Multiple Origin/Destination fields (new feature)

With the help of this Voyager program, the user can save the files in two formats, i.e.
.DBF and .TXT.
Utilities > Shortest Path > Keywords and Usage

Keywords and Usage

This section provides basic usage information on the Cube Voyager shortest path
function. Topics include:
• Expressions for Origin and Destination

• Path Limit Options

• Saving Output Files

Utilities > Shortest Path > Keywords and Usage > Expressions for Origin and Destination

Expressions for Origin and Destination

The path building function allows using expressions in the origin and destination field.
For example: the use of range of numbers like "1, 3, 5-10" will be similar to "District = 1,
3, 5-10" or "N = 1, 3, 5-10". This will also allow the use of expressions based on any
node attributes like "PTSTOP=1".
For detailed example scripts, please see Examples.
Utilities > Shortest Path > Keywords and Usage > Path Limit Options

Path Limit Options

These parameters control the cost and number of destinations for paths. If a user
specifies a value of 0 for any of these parameters, it means that there is no limit to the
number of paths.
For a high-level overview of how these options work, see Behavior of Path Limit Options.
For detailed example scripts, please see Examples.
• — This option limits the paths on the basis of the maximum cost and any
MA XP A T H COS T
path over the limit will not be included in the display or the output file. But the maximum
cost may or may not increase depending upon the number of paths less than maximum
cost (see next).

• / MA XP A T H P E R OR IGIN — These options force the number of paths to be

MIN P A T H P E R OR IGIN
displayed/written to a file from an origin on the basis of a maximum/minimum number sorted
by cost. However, this only applies when a maximum cost is specified. Also, if the number
of paths with costs less than maximum cost is below the minimum number, maximum cost
will be increased subsequently a number of times to get to the minimum number (see next).

• — This option also allows the user to specify the number of times the
MA XCOS T IN CR E A S E
maximum path is allowed to increase in order to meet a minimum number of paths.
Utilities > Shortest Path > Keywords and Usage > Path Limit Options > Behavior of Path Limit Options

Behavio r o f Path Lim it Optio ns

An example of these enhancements is explained below including how the parameters

such as: the maximum path cost, minimum paths, maximum paths and the number of
times to increase the maximum path cost to get the minimum number are configured.
Assum ptio ns:

• Origin 1 has paths to destination 5, 6, 7, 8, 9, 10 with costs of 15, 16, 17, 18, 19, 20
respectively

• Origin 2 has paths to destination 5, 6, 7, 8 , 9, 10 with costs of 25, 26, 27, 28, 29, 30
respectively

• Origin 3 has paths to destination 5, 6, 7, 8, 9, 10 with costs of 55, 66, 71, 81, 91, 99
respectively

• Origin 4 has paths to destination 5, 6, 7, 8, 9, 10 with costs of 55, 66, 87, 88, 98, 99
respectively

• Parameters
m
Maximum Path Cost = 28, Minimum Paths = 3, Maximum Paths = 5, Number of times to
increase the maximum path cost to get minimum number = 2
Results:

• Origin 1 outputs paths to 5, 6, 7, 8, 9 (the maximum paths is reached)

• Origin 2 outputs paths to 5, 6, 7, 8 (reached the maximum cost and the number of paths is
above the minimum paths).

• Origin 3 outputs paths to 5, 6 ,7. Since no path is below the maximum cost, the maximum
cost is increased 1 time from 28 to 56 that results in 1 path (5), so the maximum cost is
increased a second time from 56 to 84 that results in getting 4 paths (5, 6, 7, 8) but only 3
paths are displayed that have lowest cost.

• Origin 4 outputs paths to 5, 6. Since no path is below the maximum cost, the maximum cost
is increased 1 time from 28 to 56 that results in 1 path (5), so the maximum cost is
increased a second time from 56 to 84 that results in getting 2 paths (5, 6). Even though it
is still less than the number of minimum paths, it has reached the limit of number of times to
increase the maximum cost allowed so it cannot increase the maximum cost anymore.

One practical example of using the path limit option is to find PT access points from a
zone. For example, the objective is to identify all the PT stop nodes within 0.28 miles
with a maximum of 5 stops from each origin. If the function identifies the number of PT
stops as less than 3 within 0.28 miles, the function will then search within 0.56 miles, and
subsequently 0.84 miles until it gets the minimum of 3 PT stops.
Utilities > Shortest Path > Keywords and Usage > Saving Output Files

Saving Output Files

The outputs resulting from the path build function can be saved to text (.txt) or in
database (.dbf) file formats. The output file will contain the path cost trace information for
each origin and destination selected by the user.
• — Output text files are in comma separated (.CSV) format with the fields
T e xt (.T XT ) file s
Origin, Destination, Node and Cost as the column headers. If additional trace is specified,
an extra field will be added after Cost. This file will include all the intermediate nodes and
their respective Cost factor to reach the desired destination.

• — For the output files as .DBF, the fields ORG, DST, NODE, COST1
D a ta b a s e (.D B F) file s
and COST2 will be included. The COST2 field will always be available in the .DBF format,
even when no additional trace is specified. Note that when appending to a .DBF file, the
existing file must have the fields listed above already in it (or basically, it should be a file
that was created previously by the same path save function).

In your script, you may specify the PRINTM ODE=SUM M ARY command. Cube will print only
the last line (destination line) in the output print file instead of the whole path. This
provides the path cost information for each path without detailed data on each node
used on the path. The path-building process will be significantly faster, producing a
much smaller print file. See “Example 2 — use of SUMMARY parameter” on page 1193.

NOTE: Path-building speed is maximized with SUM M ARY enabled, and without the
additonal trace value (AddTrace ). The summary option is also the only way to build node-
to-node paths, which overcomes the 32,000 zone limit and allows building paths a
maximum cost or distance from the origin.

As the user runs the script, the results of the program run will be either appended or
overwritten depending upon the user requirements. In this way, the user can get the
outputs for the different sets of origins and destinations in the same output file and obtain
the past cost trace information for each origin and destination selected by the user.
Utilities > Shortest Path > Examples

Examples
Examples include:
• Voyager Script

• Command Line & Voyager System Command

Utilities > Shortest Path > Examples > Voyager Script

Voyager Script
The path building may be invoked within a Voyager script with:
RUN PGM=CUBE
[CtrlFile=commandfile] Parameters='/Command /CloseWhenDone /Minimize /NoSplash'

If a CtrlFile is not specified, control commands can be placed between the RUN and
ENDRUN statement of the script. The commands will be copied to a temporary file first
and passed to Cube as the first parameter.
There must be only one CtrlFile , itself a script. The Command File can have blank lines
or comment lines (;) in it. Each statement must be within a FUNCTION and
ENDFUNCTION (or ENDPROCESS) statement. It is designed to work like Voyager
script, but no COMPUTE, IF and LOOP type statements are allowed. Multiple
FUNCTION/ENDFUNCTION blocks can be used in the Command File and they will be
executed by Cube one at a time.
An example Command File for shortest path build function is below. Note that the
BUILDPATH function option is required to enable the path building mode.
Utilities > Shortest Path > Examples > Voyager Script > Example 1 — Multiple destination fields from a single origin

Exam ple 1 — M ultiple destinatio n fields fro m a single o rigin

function=BUILDPATH
; required parameters:

neti=" C:\...\path.net" ; input the network file

pathprinto=" C:\...\pathlist.dbf" ; the output file (in .dbf or .txt)
CostSpec="Distance+Cost" ; the flexibility to use the expression

;optional parameters:
fileformat=dbf ; dbf or txt, default to txt
filemode=append ; append or overwrite, default to overwrite
LinkSelection="SPDCLASS < 50" ; use of expression
AddTrace="LINKGRP1" ; use of expression
MaxPathCost=13
MinPathPerOrigin=4
MaxPathPerOrigin=6
MaxCostIncrease=2
turnpeni="C:\...\path.pen" ; the turn penalty file
turnvoli="C:\...\turnvol.dbf" ; the turn volume file
UsePenSets=4 ; default to 1 if turnpeni specified, otherwise it is ignored
UseTurnVols=true ; default to true if turnvoli specified, otherwise ignored

; each Destination keyword below will build a set of paths and save to
; output file
Origin="District=5"
Destination="District=1"
Origin="13" Destination="11"
Destination="12" ; use of multiple destination fields from a single origin
close
endfunction
Utilities > Shortest Path > Examples > Voyager Script > Example 2 — use of SUMMARY parameter

Exam ple 2 — use o f SUM M ARY param eter

RUN PGM=CUBE Parameters ='/Command /CloseWhenDone /Minimize /NoSplash'
FUNCTION = BUILDPATH
neti="tana_sp_with_maz_taz_connectors.net"
pathprinto="fullpathsum.txt"
CostSpec="METERS" ;impedance
fileformat=txt
MaxPathCost = 4800
PRINTMODE=SUMMARY
;from origin to each destination specified
Origin="1-80000"
Destination="(N%100000 > 10000) & (N<1000000)"
close
endfunction
ENDRUN
Utilities > Shortest Path > Examples > Command Line & Voyager System Command

Command Line & Voyager System Command

The Command Line syntax for running the path building function is ([x] means it is
optional):
Cube commandfile /Command [/CloseWhenDone] [/Minimize] [/NoSplash]

Consequently, to invoke the path-building function from a script file (*.S) or a text file
(*.txt), the following syntax may be used:
*"C:\program files (x86)\Citilabs\Cube\Cube.exe" commandfile /Command
[/CloseWhenDone] [/Minimize] [/NoSplash]

If Cube is in the system path, then just "*Cube.exe ..." should work without specifying the
full path to Cube.exe. The following two approaches may be used to invoke the shortest
path build function. The user needs to have the control file as (*.S), (.txt) or any ASCII
file format. Then, run the respective command in Cube.
• *"C:\Program Files (x86)\Citilabs\CubeVoyager\Voyager.exe" "C:\...\Pathbuildtest.S" /Start

OR
• *"Cube.exe" C:\...\Pathbuildtest.txt /Command /CloseWhenDone /Minimize /NoSplash

An example script (Pathbuildtest.S or Pathbuildtest.txt) is below. Note that the

BUILDPATH function option is required to enable the path building mode.

function=BUILDPATH
; required parameters:

neti="C:\...\UNLOADED.NET"
pathprinto="C:\...\pathlist1.dbf"
CostSpec="Distance"; expression

; optional parameters:
fileformat=dbf ; dbf or txt, default to txt
filemode=append ; append or overwrite, default to overwrite
LinkSelection="Distance > 0" ; expression
AddTrace="LINKGRP1" ; expression
MaxPathCost=13
MinPathPerOrigin=4
MaxPathPerOrigin=6
MaxCostIncrease=2
turnpeni="C:\...\path.pen"
turnvoli="C:\...\turnvol.dbf"
UsePenSets=4 ; default to 1 if turnpeni specified, otherwise ignored
;UseTurnVols=true ; default to true if turnvoli specified, otherwise ignored
; each Destination keyword below will build a set of paths and save to output file
Origin="District=1"
Destination="District=1000"
Origin="2" Destination="1000"
;Destination="12"
close
endfunction
Utilities > Link Consolidation

Link Consolidation
This section describes the Link Consolidation function available by invoking Cube.exe
from a Voyager script.
Sections include:
• Introduction

• Keywords and Usage

• Example
Utilities > Link Consolidation > Introduction

Introduction
The Cube.exe Link Consolidation function works the same as the tool in Network
Window (see “Link consolidation” on page 507 of the Cube Base Reference Guide).
This consolidation function may be called by invoking Cube.exe from a Voyager script.
The Function will consolidate a series of links with same characteristics, and no cross
streets, into a single link. When the network is displayed in true shape mode (connected
to a shapefile by means of a VPR file), consolidating the links will also update the
shapefile to maintain the true shape display linkage.
Utilities > Link Consolidation > Keywords and Usage

Keywords and Usage

The link consolidation is invoked from a Voyager script beginning with:
RUN PGM=CUBE PARAMETERS='/command /CloseWhenDone /Minimize /NoSplash'
function=LINKCONSOLIDATE

• FU N CT ION LIN KCON S OLID A T E function option is required to enable the link consolidation
mode.

• Under the P A R A ME T E R S keyword, you may specify:

m
/ c o mma nd puts Cube in command mode and is required.
m
/ Clo s e W he nD o ne , / Minimize , and / N o S p la s h are optional, but recommended when running
from Voyager.

• The script must terminate with E N D FU N CT ION .

Additional keywords for Link Consolidation include:

• NET I— the input binary network (*.NET). Or, a Visual Project File (*.VPR) associating a
binary network and true shape linkages if applicable.
m
With true shape, the consolidation will also update the shapefile to maintain the true
shape display linkage. However, the true shape display must have a sequence field
specified, since a consolidated link will be linked to more than one shape and the order
of the shapes must be specified in the sequence field.

• NET O — filename of the consolidated output network (*.NET)

• T URNPENI — filename of the input turn penalties (*.PEN) associated with the network, if
applicable.

• T URNPENO — filename of the output turn penalties (*.PEN), updated to reflect the new
connecting nodes. Optional.

• LOGFILE O — optional filename (*.LOG) for logging the consolidation

• Each link attribute (field) of the input network may be associated with a mode to specify
what value goes into the consolidated link. The consolidation mode keywords below define
the type of consolidation for each link attribute.

NOTE: Linkattributes without an associated consolidation mode will default to the

mode specified in the DEFAULTNUMMODE or DEFAULTTEXTMODE keywords.
For character attributes, all options except MATCH, FIRST, LAST, MIN, MAX, MIN0,
and MAX0 are treated as the same as FIRST.
m
— The attribute must be the same for the links to be consolidated (for example,
MA T CH
NUMLANES).
 It is not required to have any attribute set to MATCH even though it is unusual. In
that case, any series of links with no cross streets (all inside nodes are connected
to two links only) will be consolidated.
m
SUM — Total the values from all the links in the series (for example, DISTANCE)
m
FIR S T — Use the value from the first link in the series
m
LA S T— Use the value from the last link in the series (except blank values for character
attributes)
m
MIN — Use the minimum value from all the links in the series
m
MA X — Use the maximum value from all the links in the series
m
AVE — Use the average value from all the links in the series
m
MIN 0— Use the minimum value from all the links in the series except 0 values (except
blank values for character attributes)
m
MA X0— Use the maximum value from all the links in the series except 0 values (except
blank values for character attributes)
m
AVE0 — Use the average value from all the links in the series except 0 values
m
COU N T — A count of the number of links that are consolidated. The original values in the
links will be destroyed so it is best to create a new attribute to store the count
m
— Compute the distance weighted average on distance/unit type attribute
W E IGH T 1A V E 0
(for example, SPEED) from all the links in the series, except 0 values
m
— Compute the distance weighted average on unit/distance type attribute
W E IGH T 2A V E
(for example, signals per mile) from all the links in the series
m
— Compute the distance weighted average on unit/distance type attribute
W E IGH T 2A V E 0
(for example, signals per mile) from all the links in the series, except 0 values

• — the default consolidation mode for numeric attributes, when

D E FA U LT N U MMOD E
unspecified (see list above)

• D E FA U LT T XT MOD E — the default consolidation mode for text attributes, when unspecified
(see list above)
Utilities > Link Consolidation > Example

Example
In this script, an input binary network is consolidated with a true shape linkage.

RUN PGM=CUBE PARAMETERS='/command /CloseWhenDone /Minimize /NoSplash'

function=LINKCONSOLIDATE
neti="UnConsolidateNet.vpr" ; or simply a .net without true shape
turnpeni="UnConsolidate.pen" ; optional
turnpeno="Consolidate.pen" ; optional
neto="Consolidate.net"
logfileo="Consolidate.log" ; optional
DefaultNumMode=Max ; or Match,Sum,First,Last etc.
DefaultTxtMode=Last ; or Match,First,Last etc.
Match = FUNC_ClS,LANES
Sum = DISTANCE, TIME
First = FROMID
Last = TOID
Min = CAPACITY
Max = AREATYPE
Ave = COUNT
; Min0 = ; excluding 0 values
; Max0 = ; excluding 0 values
; Ave0 = ; excluding 0 values
Count = SEGMENTS ; count of consolidated links
Weight1Ave0=SPEED; Distance weighted ave, distance/unit type e.g.speed (miles per
hr) always excluding 0 values
Weight2Ave =SIGNAL_DENSITY ; Distance weighted ave, unit/distance type e.g. signal
per mile
Weight2Ave0=TOLL ;unit/distance weighted ave, excluding 0 values
endfunction
ENDRUN
Utilities > Build Network from Feature Class

Build Network from Feature Class

This section describes the Build Network from Feature Class tool available by invoking
Cube.exe from a Voyager script.
Sections include:
• Introduction

• Keywords and Usage

• Examples
Utilities > Build Network from Feature Class > Introduction

Introduction
The Cube.exe Build Network from Feature Class function works similarly to the tool in
Data Manager (see “Build network from shape file” on page 171 of the FCube Base
Reference Guide). Cube performs this function when called from a Voyager script.
The command-mode tool will generate a Cube network from the line information in a GIS
shapefile (.SHP) and its associated data. The output network is a binary network
(.NET). The tool does not currently support reading and outputting geodatabases.
Utilities > Build Network from Feature Class > Keywords and Usage

Keywords and Usage

The build network function is invoked from Cube Voyager with:
RUN PGM=CUBE [CtrlFile=commandfile] PARAMETERS='/Command /CloseWhenDone /Minimize
/NoSplash'

Or, it may be invoked from the Windows command line :

Cube commandfile /Command [/CloseWhenDone] [/Minimize] [/NoSplash]

The optional CtrlFile is itself a Voyager script, and lists the Voyager commands required
for the network building. If a CtrlFile is not used, control commands can be placed
between the RUN and ENDRUN statement in the script. They will be copied to a temp
file and passed to Cube as the first parameter.
The CtrlFile can have blank lines or comment lines (;). Each function must be within a
FUNCTION and ENDFUNCTION (or ENDPROCESS) statement. It is designed to work
like TP+ script but no Compute, If, Loop-type statements are allowed.
Below are the commands for supporting the Build Network function.
• — this command must follow RUN PGM, or be the first
FU N CT ION S H A P E 2N E T W OR K
command in the CtrlFile. This is required to enable the build network from shape mode.

• With the P A R A ME T E R S keyword, or at the Windows command line, you may specify:
m
/ c o mma nd puts Cube in command mode and is required.
m
/ Clo s e W he nD o ne , / Minimize , and / N o S p la s h are optional, but recommended when running
from Voyager.

• The script must terminate with E N D P R OCE S S or E N D FU N CT ION .

Keywords for Build Network are listed below. (You may also skip ahead to an
Examples).
• SHPI — The path and name of the input line shapefile (SHP). Two SHPIs may be optionally
specified, one containing points, and the other lines.

• — Optional input binary network (.NET). When specified, nodes from NETI will be
NET I
used. Otherwise, if there is a point shape file (SHPI), then it will be used with the node
number field specified in POINTNODENUMFIELD (see below).
• — Field in the point file containing node numbers. Required if you specify a
P OIN T N OD E N U MFIE LD
point file. Optional; no default value.
• — Specify T to join the point shapes and line shapes together using the ID,
J OIN LIN KN OD E
FROM_ID, and TO_ID fields. This option is useful when the ID fields do not contain node
numbers, such as shape files exported from TransCAD software. Default is F.
 When selected and the line shape has a zero-value A-node, Cube Base searches
the point file for the record where the point file’s ID field matches the line file’s
FROM_ID, and uses that record’s node number. Similarly if the line shape has a
zero-value B-node, Cube Base searches the point file for the record where the point
file’s ID field matches the TO_ID, and uses that record’s node number. If Cube Base
finds no matching ID field in the point file, then Cube Base searches for nodes by
location.
If selected, do not set ANODEFIELD to FROM_ID and do not set BNODEFIELD to TO_ID.
NOTE: This property is available only if you specify a point file, the point file contains
an ID field, and the line file contains both FROM_ID and TO_ID fields.

• NET O— The path and name of the output network to be created. The destination will be a
standalone binary network (.NET).

NOTE: The build network tool only uses the node data for determining the node
numbers. It does not import node attributes into the output network.

• — Field in the line file that contains the A-node. Default values are A, ANODE
A N OD E FIE LD
and FROM_ID in that precedence.
If you specify a field other than A, Cube Base renames that field A in the output
network. If a field named A already exists, Cube Base renames that field A0 in the
output file. (In this case, if A0 exists, Cube Base renames that field A1, and so on.)
If the specified field contains a nonzero number, Cube Base assigns that number to
the node. If the field contains a zero and you do not specify a point file, Cube Base
automatically assigns a sequential number to the node.
• — works like ANODEFIELD described above. Default values are B, BNODE
B N OD E FIE LD
and TO_ID in that precedence.

• LE V E LFIE LD — Integer field that contains the shape level. Optional; no default value.
If specified, Cube Base only connects shapes that have the same level unless
specific connection criteria are met. Cube Base can accommodate levels between 0
and 254.
Use this field if the shapefile defines multiple shapes (not all connected to a single
node) at all intersections between shapes—for example, if the shapefile breaks two
intersecting lines into four lines.
Cube Base ensures that each trip entering an intersection can exit. Each level
containing an inbound link must contain an outbound link, and each level containing
an outbound link must contain an inbound link. Furthermore, the reverse link of a two-
way link does not count as a matching inbound or outbound link to itself. If necessary,
Cube Base connects shapes at different levels, provided there are four or more
shapes connected at a single point.
• — T or F. Select True to clear all values in the A-node and B-node fields
CLE A R A B V A LU E S
within the input line file. (See A N OD E FIE LD and B N OD E FIE LD ). Cube Base either finds node
numbers in the point file, if specified, or within the shape data. Otherwise, it automatically
assigns sequential numbers.
Cube will save the updated version of the input line file, along with the output network.
Default is F.
• D IR E CT ION OP T ION— the direction of output links. Use 1 for All one-way, 2 for All two-way,
and 3 for D IR E CT ION FIE LD below. Default is 1.
• D IR E CT ION FIE LD — the direction indicator field name if D IR E CT ION OP T ION (above) is 3.
The value of DIRECTIONFIELD for each input link determines how Cube Base
processes it when building the network:
m
If value is 1, the output link is one-way in the indicated direction (A to B).
m
If value is -1, the output will be a one-way link in the opposite direction (A to B order
reversed).
m
If value is 2, the output will be two-way; ie, two one-way links are written with opposing
directions.
• The output will also be two-way when the value is 0, and ZE R OA S 2W A Y (see below) is
set to T.
Cube Base renames this field to REV in the output file. If a field named REV already
exists, Cube renames that field REV0 in the output file. (Likewise, if REV0 also exists,
Cube renames that field to REV1, and so on.)
• ZE R OA S 2W A Y — Set to T to process shapes with a value of 0 in the indicator field
(D IR E CT ION FIE LD ) as two-way links. Default is F.

• — when set to T, Cube will consolidate values from direction-specific

CON S OLID A T E A B B A
fields when converting shapefile networks with bi-directional link-records into Cube's
network format (of one link-record per direction). It requires the D IR E CT ION FIE LD (above) to
determine which of the resulting records receive either the AB or BA values.
Default is F.
When set to T, you must specify ABM ASK and BAM ASK to select the fields for
consolidation:
m
Each mask must either s ta rt or e nd with a single wildcard, represented by an asterisk (*)
m
Consolidation occurs when both masks match a unique field with a common root.
m
If the consolidated root is an invalid field name (starts with a number or is a reserved
word like LONG) it is prefixed with a 'C'.
m
Duplicate field names resulting from consolidation are resolved by appending an
incrementing numeric value.
• A B MA S K — see CON S OLID A T E A B B A above. Default is AB_*

• B A MA S K — see CON S OLID A T E A B B A above. Default is BA_*

• — Select T to add a field, named DISTANCE, to the output network and

A D D D IS T A N CE FIE LD
store the shape’s true distance (the sum of all segments). Default is F.
Cube Base calculates the distance based on the global coordinate system (that is,
the shapefile coordinate system with the scale and layer offset applied).
If a field named DISTANCE already exists, Cube Base renames that field
DISTANCE0 in the output file. (In this case, if DISTANCE0 exists, Cube Base
renames that field DISTANCE1, and so on.)
Requires DISTANCESCALE (below).
• — Required by A D D D IS T A N CE FIE LD (above). Numeric factor to apply to the
D IS T A N CE S CA LE
shape’s distance. Default is 1.
• — Maximum distance between endpoints of shapes for Cube Base to
N OD E GR OU P IN GLIMIT
consider them a single node. Specified in global coordinate units. Default is 1.
Cube Base attempts to merge any node without a node number to an existing node. If
no existing node falls within this distance, Cube Base adds a new node.
• — Highest zone number in the output network. This value does not affect the
H IGH E S T ZON E
network-building process. Default is 0.

• — Starting number that Cube Base uses when adding new nodes. Must
S T A R T IN GN E W N OD E
be greater than the highest node number in the input file. Default value is 100 greater.
Utilities > Build Network from Feature Class > Examples

Examples
Example 1
In this standalone script (without command file), network shp2net.net is generated from
input shape file shp2net.shp.
RUN PGM=CUBE Parameters='/Command /CloseWhenDone /Minimize /NoSplash'
function=SHAPE2NETWORK
shpi="p:\dtown\shp2net.shp"
neto="p:\dtown\shp2net.net"
AnodeField=A
BnodeField=B
LevelField=""
ClearABValues=T
DirectionOption=1
DirectionField=""
AddDistanceField=Y
DistanceScale=2.22
NodeGroupingLimit=1
StartingNewNode=1000
HighestZone=30
endfunction
Utilities > Build Network from Feature Class > Examples > Example 2

Example 2
Node data from network or point shape layer can be used in the batch
SHAPE2NETWORK process. If there is a NETI then its nodes will be used, else if there
is a point shape file, then it will be used with the node number field specified in
PointNodeNumField.
RUN PGM=CUBE Parameters='/Command /CloseWhenDone /Minimize /NoSplash'
function=SHAPE2NETWORK
neti="p:\dtown\base.net"
shpi="p:\dtown\shp2net.shp"
neto="p:\dtown\shp2net.net"
AnodeField=A

etc...

endfunction
Utilities > Build Network from Feature Class > Examples > Example 3

Example 3
function=SHAPE2NETWORK
shpi="p:\dtown\nodes.shp" ; point shape
shpi="p:\dtown\shp2net.shp" ; line shape
neto="p:\dtown\shp2net.net"
PointNodeNumField="NODENUM"
AnodeField=A

etc...

endfunction
Utilities > UB2TPP

UB2TPP
Utility program UB2TPP can be used to convert FTA New Start User Benefit matrix files in
SUMMIT binary format to standard TP+/Cube Voyager format.
The following control statements are available in the Cube Voyager UB2TPP utility
program.

S ta te me nt D e s c rip tio n

FILE I Specify input SUMMIT UB file

FILE O Specify output TPP/Cube Voyager

file

P A R A ME T E R S Set static parameters

Utilities > UB2TPP > FILEI

FILEI
Inputs data file.
MATI

Ke y wo rd D e s c rip tio n

MATI |KF| Specifies the filename of the binary

user benefit file created by the FTA
SUMMIT program
Utilities > UB2TPP > FILEO

FILEO
Outputs data files.
MATO VARO

Ke y wo rd D e s c rip tio n

MATO |KF| Specifies the filename of the converted

TP+/Cube Voyager binary matrix file.

VARO |KF| Optional. Specifies the filename of the

user benefit VARO file. The VARO file
contains the variable information from
the user benefit file header.
A sample of the VARO file is listed
below:
UBTRNCOEF=2.34567
UBAUTOCOEF=8.7654336
UBPURPOSE='Pabcde'
UBTOD='DataTi'
UBALTNAME='Another a test
header (11223344556677) with
sixty characters'
The VARO file can be used in another
Cube Voyager program (for example,
Matrix) by “reading” the file in, for
example:
run pgm=matrix
filei mati=t10_36.mat
read file=ubout.var
mw[1]=mi.1.1*UBAUTOCOEF
endrun
Utilities > UB2TPP > PARAMETERS

PARAMETERS
Sets general parameters.
HEADERONLY

Ke y wo rd D e s c rip tio n

HEADERONLY |?| <F> is a switch to indicate that only

the header information is to be written
to the MATO and VARO files. The
MATO file must be specified even if
HEADERONLY=T.
Utilities > TPP2UB

TPP2UB
Use the TPP2UB utility program to convert standard binary TP+/Cube Voyager format
matrices to FTA New Start User Benefit matrix files in SUMMIT binary format.
The following control statements are available in the Cube Voyager TPP2UB utility
program.

Co ntro l s ta te me nt D e s c rip tio n

FILE I Specify input TP+/Cube Voyager input file

and the user benefit variable file.

FILE O Specify output binary user benefit file.

P A R A ME T E R S Set static parameters.

Utilities > TPP2UB > FILEI

FILEI
Inputs data files.
MATI VARI

Ke y wo rd D e s c rip tio n

MATI |KF| Specifies the filename of the binary

TP+/Cube Voyager matrix file to be
converted.

VARI |KF| Specifies an optional variable file that

contains the variable information for the
user benefit file header.
Utilities > TPP2UB > FILEO

FILEO
Outputs data files.
MATO

Ke y wo rd D e s c rip tio n

MATO |KF| Specifies the filename of the converted

binary user benefit file.
Utilities > TPP2UB > PARAMETERS

PARAMETERS
Set general parameters. The program must have values for all PARAMETERS. They
may be coded directly with the PARAMETERS statement, they may be read in on the
VARI file which was the result of a VARO file from UB2TPP or they may be read in on a
VARI file that is hand coded.
TRNCOEF
AUTOCOEF
PURPOSE
TOD
ALTNAME
P A R A ME T E R S k e y wo rd s

Ke y wo rd D e s c rip tio n

ALTNAME |KS| User Benefit ALTNAME

value

AUTOCOEF |KS| User Benefit AUTOCOEF

value

PURPOSE |KS| User Benefit PURPOSE

value

TOD |KS| User Benefit TOD value

TRNCOEF |KS| User Benefit TRNCOEF

value
Utilities > SYNCHIMP

SYNCHIMP
Use the SYNCHMP utility program to convert SYNCHRO data to Cube Voyager
intersection data format.

NOTE: Cube has a SYNCHRO data import wizard accessible from the File > Tools menu.

The following control statements are available in the Cube Voyager SYNCHMP utility
program.

Co ntro l s ta te me nt D e s c rip tio n

FILE I Specify input SYNCHRO files.

FILE O Specify output Cube Voyager files.

P A R A ME T E R S Set static parameters.

Utilities > SYNCHIMP > FILEI

FILEI
Inputs data files.
LAYOUTI
LANESI
PHASINGI
TIMINGI
VOLUMEI
FILE I k e y wo rd s

Ke y wo rd D e s c rip tio n

LANESI |KF| Specifies the filename of the input

SYNCHRO
LANES file.

LAYOUTI |KF| Specifies the filename of the input

SYNCHRO
LAYOUT file.

PHASINGI |KF| Specifies the filename of the input

SYNCHRO
PHASING file.

TIMINGI |KF| Specifies the filename of the input

SYNCHRO
TIMING file.

VOLUMEI |KF| Specifies the filename of the input

SYNCHRO
VOLUME file.
Utilities > SYNCHIMP > FILEO

FILEO
Outputs data files.
NODEO
LINKO
JUNCDATAO

Ke y wo rd D e s c rip tio n

JUNCDATAO |KF| Specifies the filename of the

output intersection data file.

LINKO |KF| Specifies the filename of the

output link file.

NODEO |KF| Specifies the filename of the

output node file.
Utilities > SYNCHIMP > PARAMETERS

PARAMETERS
Sets general parameters. The values of these parameters are stored in the associated
SYNCHRO input CSV data files.
PLANID
VOLDATE
VOLTIME
UNITS
P A R A ME T E R S k e y wo rd s

Ke y wo rd D e s c rip tio n

PLANID |KS| Specifies the PLAN ID value in the

TIMING file.

VOLDATE |KS| Specifies the date value in the

VOLUME file.

VOLTIME |KS| Specifies the time value in the

VOLUME file.

UNITS |KS| Specifies the units of the LANES file.

Valid values are meters or feet.
Utilities > Saturn conversion

Saturn conversion
The SaturnPath utility program converts output from the Saturn assignment program into
a Cube Voyager path file.
The Cube installation program installs this program in the Cube directory (C:\Program
Files\Citilabs\Cube\SaturnPath.exe in standard installations). You can access this
program through Windows Explorer, the Command line or a batch file.
This section discusses:
• Running from program window

• Running from command line

Utilities > Saturn conversion > Running from program window

Running from program window

If you access SaturnPath from Windows Explorer, you will open the program window.

The window contains two fields and several command buttons:

• Input Saturn Path File — Enter the existing file containing the Saturn output.

• Output Voyager Path File — Enter the new file you want to create containing a Cube Voyager path
file

• Browse — Click to search for the file in a file browser.

• — Click to run the utility and convert the specified input into a Cube Voyager-
Convert
formatted path file and write the results to the specified output file.

• Close — Click to close the program window.

• — Click to show statistics about the Saturn file (number of paths,

Show Saturn File Statistics
minimum and maximum zone number, node number, class number, route number, flow, and
number of nodes in path).
Utilities > Saturn conversion > Running from command line

Running from command line

When called from a command line or batch file, SaturnPath accepts up to three
parameters:
• Input file containing Saturn paths

• Output file to write Cube Voyager paths

• Start flag (set to GO to start automatically)

If you specify all three parameters (setting the start flag to “GO”), the program
automatically starts converting the input file. If there are no errors during the conversion,
the program automatically writes the output file. If the specified output file does not exist,
the program will close automatically, too; otherwise, the program will prompt to overwrite
the file.
If you do not specify all three parameters, the program window will open, with fields
showing any parameter values that you did specify.
Frequently Asked Questions > Pilot and general syntax

Pilot and general syntax

1. How do I do token replacement?

2. How do I generate unique link ID strings using numeric values from A and B nodes?
Frequently Asked Questions > Pilot and general syntax > How do I do token replacement?

How do I do token replacement?

Any statement outside of the RUN PGM = and ENDRUN block (see RUN ... ENDRUN) is a
TPMain statement. We can use TPMain statements to set global variables, check
results, run loops etc. Do the following substitution:
INHWYNET="c20c.net"
OUTHWYNET="c20ctpp.net"

RUN PGM=NETWORK
FILEI NETI=@INHWYNET@
FILEO NETO=@OUTHWYNET@
ENDRUN

RUN PGM=HWYLOAD
FILEI NETI=@OUTHWYNET@
.....
ENDRUN

We can put all the substitution at the beginning of the file and change them there before
running the script. Alternatively, we can put the substitution strings in a separate file and
use the READ statement (Chapter 3, “General Syntax”) to insert it at run time:
READ FILE=sub.txt
RUN PGM=HWYNET
FILEI NETI=@INHWYNET@
.....
Frequently Asked Questions > Pilot and general syntax > How do I generate unique link ID strings using numeric values from
A and B nodes?

How do I generate unique link ID strings using numeric

values from A and B nodes?
Voyager provides a set of Character functions to allow conversion and manipulation of
character (or string or text) variables:
FORMAT(x,w,d,str) ; Format number (x) with width=w, decimals=d, format=str
TRIM(str) ; Delete trailing spaces from str
LTRIM(str) ; Delete leading spaces from str
DUPSTR(str,n) ; Duplicate str n times; result must be less than 100 chars
VAL(str) ; Return the numeric value contained in str

; Convert the variable v to a string that is w characters wide,

; with d decimal places. n must be less than 30; d less than n - 2.
STR(v,w,d)

; Extract a substring from str, beginning at position b,

; and continuing for n characters. b must be greater than 0.
SUBSTR(str,b,n)

; Return the position in str2 where str begins. If str does not exist in
; str2, the value is 0. Both strings are case sensitive.
; Note: str is either a character constant '...', or a character variable
STRPOS(str,str2)

; The following statement will generate a unique link ID string for each
; link:
LINK_ID= LTRIM(STR(LI.1.A, 5, 0)) + '_' + LTRIM(STR(LI.1.B, 5, 0))
Frequently Asked Questions > Fratar

Fratar
1. How do I specify SETPA with both target values and growth factors for the same purpose?
Frequently Asked Questions > Fratar > How do I specify SETPA with both target values and growth factors for the same
purpose?

How do I specify SETPA with both target values and

growth factors for the same purpose?
This has to be done using separate SETPA statements. See the following example:
; assuming gf() and tot() are previously defined lookup functions
; zone 3 is specified using growth factor
; other zones are specified using target values

setpa pgf[1]=gf(1,j), agf[1]=gf(2,j), include=3

setpa p[1]=tot(1,j), a[1]=tot(2,j), exclude=3
setpa mw[1]=mi.1.1
Frequently Asked Questions > Highway

Highway
1. What does V1_1 represent in a loaded network?

2. How do I set global turn penalties using direction codes?

3. Can Highway summarize calculated ratios such as summing volume/count ratios by lanes,
speed class, or rmse by volume group?
Frequently Asked Questions > Highway > What does V1_1 represent in a loaded network?

What does V1_1 represent in a loaded network?

V1_1 is the first volume set for assignment run 1. V_1 is the combined volume for all
volume sets for assignment run 1; it is generally the sum of all the volume sets (V1_1,
V2_1, V3_1 etc.), but the user can specify which volumes are to be combined in Highway
(with FUNCTION V=). There is more than one volume set when we do multi-class
assignment (LOV, HOV etc.), or assign a selected link matrix in a separate volume set.
If we use a loaded network as input to Highway again and perform another assignment,
the volume, speed etc. will be appended to the network file as V1_2, V_2 etc.
Frequently Asked Questions > Highway > How do I set global turn penalties using direction codes?

How do I set global turn penalties using direction

codes?
The following script will take a network with direction codes and generate a turn penalty
file with penalty records for all movements involving direction-coded links. One needs to
set the maximum direction code which will be included in the penalty file and provide a
direction-coded network. The resulting penalty file is saved in "test.pen". One will then
enter appropriate values for the penalty functions at the beginning of the file.
This script will go through the whole network and write out a file of turn penalty records
for all movements that have direction codes in both links with a set number of 1. A
function name makes up the from- and to- direction code (Ffftt). For example, the
function name for movements from dir. code 2 to 1 is F0201.
The script also writes out the list of functions at the beginning of penalty file so the user
can set the penalty for each from-to direction combination.
This script works with direction codes up to 99; otherwise. it will need to be modified.
maxcode=99 ; set maximum direction code to be included in penalty file
inputnet='dircode.net' ; input network

; Create a temporary network with only links that have a valid direction
; code. Assume dircode is an attribute in the link database and contains
; direction codes from 1 to maxcode

run pgm=network
neti=@inputnet@
neto=temp.net
if (dircode <= 0 || dircode > @maxcode@) delete
endrun

run pgm=hwyload
neti=temp.net
array FuncUsed=@maxcode@@maxcode@; dimension the array to cover all from-
; to direction code(@maxcode@x@maxcode@)

phase=linkread

; save dircode from the input file in a link work array

lw.dcode=li.dircode

phase=iloop

if (i=1) ; only do it for zone 1

loop c1=1,numlinks ; loop through all the links (from link)
if (b[c1] > Zones) ; if bnode is not a zone
loop c2=1,numlinks ; loop through all the links again for the to link
; if to-link connected to from-link, and not the reverse of from-link
if ((b[c1] = a[c2]) && (a[c1] != b[c2]))
; compute the combine code, flag the function as being used, and print out
; the penalty record
N=lw.dcode[c1]*100+lw.dcode[c2]
FuncUsed[N]=1
print form=6.0,file=penalty.pen,list=a[c1],b[c1],b[c2],' 1 F',(N+10000)(4.0T)
endif
endloop
endif
endloop

print form=6.0,file=penalty.pen,list='\n' ; write a after the last line

; now write the list of functions used
loop N=1,@maxcode@@maxcode@
if (FuncUsed[N] = 1)
print form=6.0,file=function.pen,list='F',(N+10000)(4.0T),'=0'
endloop
print form=6.0,file=function.pen,list='\n' ; write a after the last line
endif
endrun

; Use the copy command to combine the function and penalty records into
; one file. If penalty functions are already defined in a file, that file
; can be combined with the generated penalty records to make a complete
; penalty file for loading.

*copy function.pen+penalty.pen test.pen

Frequently Asked Questions > Highway > Can Highway summarize calculated ratios such as summing volume/count ratios
by lanes, speed class, or rmse by volume group?

Can Highway summarize calculated ratios such as

summing volume/count ratios by lanes, speed class, or
rmse by volume group?
Highway can do the summaries by coding in a LOOP (see “LOOP ... ENDLOOP” on
page 253) to go through all the links and accumulated values on them, but you have to
make sure you do it in the last iteration. With equilibrium assignment, it is not easy to
identify the last iteration since it may reach equilibrium before MAXITERS is reached.
An easier way is to do it in Netwo rk after the Highway step. You can accumulate any type
of values (volumes, counts by lane and only if there are counts etc.) in the LINKMERGE
phase in temporary variables ( _name ). You must use temporary variables; anything
else will be treated as a link variable and zeroed out for each link, and will also be written
out if there is an output network. You can then compute ratios etc. and report them in the
SUMMARY phase.
Frequently Asked Questions > Generation

Generation
1. Why do I get an incorrect result when using PTOT and ATOT in the Adjust Phase of
GENERATION to balance P and A?

2. Why do I get "Duplicate Phase=Iloop" error in Generation?

Frequently Asked Questions > Generation > Why do I get an incorrect result when using PTOT and ATOT in the Adjust
Phase of GENERATION to balance P and A?

Why do I get an incorrect result when using PTOT and

ATOT in the Adjust Phase of GENERATION to balance
P and A?
PTOT and ATOT calculate marginal totals dynamically. In the Adjust Phase, each
computation of P and A implies a loop over all zones. If a balance equation is specified
as the following
A[2]=PTOT(2)/ATOT(2)*A[2]

Then ATOT(2) will be recalculated for each zone. A[2][1] will be adjusted correctly. But
for zone 2 and on, ATOT(2) is no longer the sum of original A[2][i]. Therefore the ratio of
PTOT(2)/ATOT(2) is not a constant. The correct way to specify a balance equation with
PTOT and ATOT is:
TEMPFAC=PTOT(2)/ATOT(2)
A[2]=TEMPFAC*A[2]

For more on ATOT and PTOT, see “COMP” on page 692.

Frequently Asked Questions > Generation > Why do I get "Duplicate Phase=Iloop" error in Generation?

Why do I get "Duplicate Phase=Iloop" error in

Generation?
"Phase=Iloop" is optional in Generation. Voyager will add a "Phase=Iloop" statement to
indicate the start of the Iloop phase when it detects a valid Iloop statement the first time. If you
coded an Iloop statement before the "Phase=Iloop" line, the program returns the "Duplicate
Phase=Iloop" error.

It is recommended that "Phase=Iloop" not be used; instead, let the program determine
where the Iloop phase should start.
Frequently Asked Questions > Network

Network
1. How do I re-compute link distances in Voyager?

2. How do I renumber nodes in a network?

3. How can I search for the closest node to an intersection record, and transfer information
from that intersection to the node record?
(This question is listed as a M atrix topic).
4. How are speed and capacity tables handled in Cube Voyager?

5. How can I include coordinates in link records?

6. How do I access reverse link attributes in Voyager?

7. How can I compute a new node attribute using coordinates?

8. How can I remove invisible links that have no coordinates from a network?

9. How do I get congested speed as an attribute?

10. Is there a way to output two-way link records from a network to text or DBF file?

11. Why is the footer plotted different from my specification?

12. How do I make global changes in a network?

13. How do I build and un-build networks from/to ASCII files?

14. Can Network read TRANPLAN networks in binary (UNIX) and ASCII formats?

15. Is there a sample setup for calculating two-way volume?

16. How do I compute a new attribute indicating one-way links in Voyager?

17. How do I use Network to compare Volumes and VMT's on two networks and report the
frequency of percentage differences?

18. Is there a function in Voyager to merge networks based on a condition?

19. How do I merge a zonal data file into the node portion of a Voyager network?

20. How do I flag or delete unconnected nodes globally?

Frequently Asked Questions > Network > How do I re-compute link distances in Voyager?

How do I re-compute link distances in Voyager?

Use the Netwo rk module and do distance computation in the linkmerge phase:
DISTANCE=SQRT(( A.X - B.X ) * ( A.X - B.X ) + ( A.Y - B.Y ) * ( A.Y - B.Y ))
Frequently Asked Questions > Network > How do I renumber nodes in a network?

How do I renumber nodes in a network?

This can be done in Netwo rk with the LOOKUP function. The following example
illustrates the process:
; create a lookup file for node renumbering
; new# old#
copy file=renumber.txt
101 1
102 2
103 3
104 4
105 5
106 6
107 7
108 8
109 9
110 10
endcopy

run pgm = network

neti = input.net
neto=output.net

; specify a lookup function, return 0 if no exact match

lookup name=renum, file=renumber.txt, interpolate=f, fail=0,0,0

phase=input filei=ni.1
if (renum(n)<>0) n=renum(n)
endphase

phase=input filei=li.1
if (renum(a)<>0) a=renum(a)
if (renum(b)<>0) b=renum(b)
endphase

endrun
Frequently Asked Questions > Network > How are speed and capacity tables handled in Cube Voyager?

How are speed and capacity tables handled in Cube

Voyager?
The values in the speed and capacity table are stored in the Voyager network in a
separate area of the file. Each individual link only has the speed class (SPDC) and
capacity class (CAPC) codings. The actual speed and capacity values are looked up
dynamically from the speed and capacity tables based on the speed class, capacity
class and number of lanes for a particular link; they are not stored as attributes in the link
data itself. The speed and capacity tables allow up to 99 classes. To verify the speed
and capacity tables, add the following statement to your first Netwo rk step:
REPORT CAPACITY=T, SPEED=T

The REPORT statement will generate a report on the speed and capacity table. If you
want to obtain the actual speed and capacity value for a link you can use the
SPEEDFOR(lanes,spdclass) and CAPACITYFOR(lanes,capclass) functions in
Netwo rk to obtain them.
Frequently Asked Questions > Network > How can I include coordinates in link records?

How can I include coordinates in link records?

Node coordinates are not part of link records. However, Netwo rk allows one to reference
the x and y coordinates for the a and b nodes by a.x, a.y, b.x and b.y in a LINKMERGE
phase. To put them in a LINKO file, follow the below example to create new link
attributes so you can use them in the LINKO :
run pgm=network
neti=...
linko=name, form=..., format=txt, include=a,b,a_x,a_y,b_x,b_y, ...
a_x=a.x
a_y=a.y
b_x=b.x
b_y=b.y
Frequently Asked Questions > Network > How do I access reverse link attributes in Voyager?

How do I access reverse link attributes in Voyager?

In Netwo rk , the LINKMERGE phase loops through the link database, and only the
attributes of the current link (in all LINKI's) can be referenced. To access reverse link
attributes, one can read in the same network twice and switch the a_node and b_node
of NETI [2] so that the reverse link in NETI[2] has the same a_node and b_node as the
current link in NETI[1]. The following example illustrates how to access reverse link
volume to compute the total link volume:
run pgm=network
neti=input.net, input.net
neto=output.net
merge record=f

phase=input, filei=li.2
_temp=a
a=b
b=_temp
endphase

phase=linkmerge
totv=li.1.v_1+li.2.v_1
endphase

endrun
Frequently Asked Questions > Network > How can I compute a new node attribute using coordinates?

How can I compute a new node attribute using

coordinates?
To do node attribute processing in Netwo rk , place the statements in the NODEMERGE
phase; otherwise, all statements default to the LINKMERGE phase. The following
example computes two new node attributes, XH and YH, equal to a hundred times of the
X and Y coordinates, respectively.
PHASE=NODEMERGE
XH=100*X
YH=100*Y
ENDPHASE

PHASE=LINKMERGE
; link processing statements
ENDPHASE
Frequently Asked Questions > Network > How can I remove invisible links that have no coordinates from a network?

How can I remove invisible links that have no

coordinates from a network?
Links are invisible when the coordinates of the a_node and/or b_node are zero. In those
cases, Cube cannot display the links. The follow sample code shows how to remove
invisible links from a network:
RUN PGM=NETWORK
NETI=BASE.NET
NETO=NEW.NET
if ((a.x=0 && a.y=0) || (b.x=0 && b.y=0)) DELETE
ENDRUN
Frequently Asked Questions > Network > How do I get congested speed as an attribute?

How do I get congested speed as an attribute?

You can compute the congested speed in Netwo rk after your assignment (or in Cube).
Use the equation:
CSPEED = DISTANCE / TIME_1 * 60

This assumes TIME_1 is the congested time. If you do an assignment using a loaded
network as input, the new volume, time etc. will be sub-fixed with 2 and 3 etc. (such as
TIME_2, V_2). Also, please pay attention to the units of the variables involved. The
above equation assumes DISTANCE and TIME_1 are in miles and minutes, and the
resulting SPEED is in mph.
Frequently Asked Questions > Network > Is there a way to output two-way link records from a network to text or DBF file?

Is there a way to output two-way link records from a

network to text or DBF file?
Use the following script to write a network out in a two-way link format. If the attributes of
a link and its reverse link are the same, only one record will be written out with a
directional flag set to 2. Otherwise the link will be written out as one-way link with the
directional flag set to 1. It reads the same network file as two separate NETI’s and
reverses the A and B for the second NETI such that in the LinkMerge phase, data
attributes for both directions are available at the same time. The example then uses the
COMPARE command to determine if the links are the same in opposite directions.
RUN PGM=NETWORK

NETI=TEST.NET,TEST.NET ; same network as 2 NETI files

LINKO=TESTLINK.DBF ; output as link records in DBF format
NODEO=TESTXY.DBF
MERGE RECORD=F

PHASE=INPUT, FILEI=LI.2 ; reverse the A and B in file 2

_TEMP=A
A=B
B=_TEMP
ENDPHASE

PHASE=LINKMERGE
COMPARE RECORD=1-2 ; compare link record 1 with 2
IF (_COMPARE = 0) ; if same
IF (A < B) ; if low to high, write out 2-way link
REVERSE=2
ELSE
DELETE ; delete high to low side of 2-way link
ENDIF
ELSE
REVERSE = 1 ; if not same write as 1 way
ENDIF
ENDRUN

; This step will build the network back from the DBF files
RUN PGM=HWYNET
LINKI=TESTLINK.DBF, RENAME=REVERSE-REV ; set the REV attributes
NODEI=TESTXY.DBF
NETO=TEST2.NET
ENDRUN
Frequently Asked Questions > Network > Why is the footer plotted different from my specification?

Why is the footer plotted different from my

specification?
The following FOOTER line will cause a problem because Netwo rk treats each space, "-
" and "," as field separators.
FOOTER=BASE YEAR 1997 NETWORK
TREASURE VALLEY I-84 CORRIDOR STUDY

Netwo rkwill treat BASE as one field, YEAR as another field etc. It also sees the "-" in I-84
and assumes that it is a range but it doesn't know what “I” is. Anytime you want to
specify a string of characters with imbedded spaces or other special characters, you will
need to enclose them within " ". So changing the statement to:
FOOTER="BASE YEAR 1997 NETWORK",
" TREASURE VALLEY I-84 CORRIDOR STUDY"

should work in specifying FOOTER[1] and FOOTER[2].

Frequently Asked Questions > Network > How do I make global changes in a network?

How do I make global changes in a network?

In terms of making global changes in a network, you may want to look at the global
calculation capabilities in Cube Network Window. It allows you to make changes to the
network globally or inside/outside/crossing a user-defined polygon area. You can also
make changes based on some condition in the data record. See the Network Window
chapter in the Cube Base Reference Guide.
You can also perform calculations in the NODEMERGE and the LINKMERGE phases in
the Netwo rk module of Cube Voyager.
Frequently Asked Questions > Network > How do I build and un-build networks from/to ASCII files?

How do I build and un-build networks from/to ASCII

files?
You can build and un-build networks from/to ASCII file using Voyager's Netwo rk module.
To build a network, use the LINKI and NODEI keywords in the FILEI statement to
specify the filenames along with the VAR keyword to specify the variables and their
locations. To output the network in ASCII, use the LINKO and NODEO keywords in the
FILEO statement. You can also use the PRINT statement to write ASCII records to a file
in whatever formats you wish.
Frequently Asked Questions > Network > Can Network read TRANPLAN networks in binary (UNIX) and ASCII formats?

Can Network read TRANPLAN networks in binary

(UNIX) and ASCII formats?
Voyager can read a UNIX format TRANPLAN binary network file directly. You can also
read the ASCII file just like any other link data file; you will need to define the fields for
Voyager’s Netwo rk module to build a new network from ASCII records. The following is a
sample on how to build a network from TRNAPLAN ASCII file (use the same file for
LINKI and NODEI). This same code is available as a module template in Cube in the
Text Editor window under the Insert dropdown:
RUN PGM=NETWORK

FILEI LINKI={filename},VAR=A,1-5,B,6-10,ASGNGRP,11-11,DISTANCE,12-15,
SPEED1,17-20,SPEED2,21-24,DIRCODE,25-26,LINKGRP1,27-28,
LINKGRP2,29-30,LINKGRP3,31-32,CAPACITY,33-38,VOLUME,39-44,REV,45-45,
SELECT=(SUBSTR(RECORD,1,1)!='N'),
NODEI={filename},VAR=N,2-6,X,9-17,Y,20-28, SELECT=(SUBSTR(RECORD,1,1)=='N')
FILEO NETO={filename}

ZONES={max zones}
IF (SPEED1 > 0) TIME1=DISTANCE/SPEED1*60
IF (SPEED2 > 0) TIME2=DISTANCE/SPEED2*60

ENDRUN
Frequently Asked Questions > Network > Is there a sample setup for calculating two-way volume?

Is there a sample setup for calculating two-way volume?

The Highway module has an option to output the two-way volumes in the output network.
If you want to add the two-way volume information to the network after the assignment is
done, you can use the following script to set a 1-way/2-way flag in the link as well as
combine the 1-way volumes into a 2-way volume. It reads the same network file as two
separate NETI inputs, and reverses the A and B for the second NETI. Thus in the
NETMERGE phase, the data attributes for both directions are available at the same
time.
RUN PGM=NETWORK

NETI=LOAD.NET, LOAD.NET
NETO=LOD1.NET
MERGE RECORD=F ; DO NOT MERGE RECORDS

; Reverse end nodes of each link in NETI[2]

PHASE=INPUT, FILEI=LI.2
_TEMP=A
A=B
B=_TEMP
ENDPHASE
PHASE=LINKMERGE

; Index # of ways
IF (LI.2.A=0)
NUMWAYS=1 ; Oneway
ELSE
NUMWAYS=3 ; Twoway
ENDIF

; Calculate total volume on both direction

TOTV=LI.1.V_1+LI.2.V_1
ENDPHASE

ENDRUN

You can also use Cube to compute the 2-way volume by adding a new link attribute
(e.g. TOTV) and compute with the following equation for all links. (See the Network
Window chapter in the Cube Base Reference Guide).
TOTV=V_1 + V_1.R
Frequently Asked Questions > Network > How do I compute a new attribute indicating one-way links in Voyager?

How do I compute a new attribute indicating one-way

links in Voyager?
The following example illustrates how to compute a new attribute (ONEWAY) indicating
one-way links. The idea is to have the information on both directions available for the
current link. So we read in the input network twice and reverse A and B nodes of
NETI[2] in the NODEMERGE phase. Now the link attributes of both directions are
available to the current link. When a link is not on a network, its A and B nodes are both
zero. Therefore, by checking the A node value of the reverse links we can flag all one-
way links.
run pgm=network
neti=input.net, input.net
neto=output.net
merge record=f

phase=input, filei=li.2
_temp=a
a=b
b=_temp
endphase

phase=linkmerge
if (li.2.a == 0) ONEWAY=1
endphase

endrun
Frequently Asked Questions > Network > How do I use Network to compare Volumes and VMT's on two networks and report
the frequency of percentage differences?

How do I use Network to compare Volumes and VMT's

on two networks and report the frequency of percentage
differences?
The follolwing sample script illustrates how to compare Volumes and VMT's on two
networks and report the frequency of percentage differences.
The script compares link volumes and VMT's on two network files. Frequency of percent
difference in link volumes by volume group and that in VMT's by speed class are
reported.
; Volume on base (B) network -- L1.V_1
; Volume on subject (S) network -- L2.V_1
; Volume differences (S-B) -- VOL_DIFF
; VMT differences (S-B) -- VMT_DIFF
; Volume diff percentage (S-B)*100/B -- VOL_PCTDIFF
; VMT diff percentage (S-B)*100/B -- VMT_PCTDIFF
;
RUN PGM=NETWORK
NETI[1]=BASE.NET
NETI[2]=SUBJECT.NET
NETO=DIFF.NET
MERGE RECORD=F
; create a temporary variable '_COUNT' to accumulate link
: counts
_COUNT=1
VOL_DIFF=L2.V_1-L1.V_1

; calculate percent differences of link volumes

; min out at -1000% and max out at 1000%
VOL_PCTDIFF=MAX(MIN((VOL_DIFF*100)/MAX(L1.V_1,0.001),1000),-1000)
CROSSTAB VAR=_COUNT, ROW=L1.V_1, RANGE=0-100.0,100.1-500.0,500.1-1000.0,
1000.1-5000.0,5000.1-10000.0,
10000.1-100000,0.0-100000.0,
COL=VOL_PCTDIFF, RANGE=-1000--100.1, -100--50.1,
-50--20.1, -20--10.1, -10--0.1, 0.0, 0.1-10, 10.1-20,
20.1-50, 50.1-100, 100.1-1000,
-10-10.0,-20.0-20,-50.0-50,-100.0-100,
-1000.0-1000

; Comparison of VMT
BASE_VMT=L1.V_1*L1.DISTANCE
SUBJ_VMT=L2.V_1*L2.DISTANCE
VMT_DIFF=SUBJ_VMT-BASE_VMT

; calculate percent differences of VMT

; min out at -1000% and max out at 1000%
VMT_PCTDIFF=MAX(MIN((VMT_DIFF*100)/MAX(BASE_VMT,0.001),1000),-1000)
CROSSTAB, VAR=_COUNT, ROW=L1.SPDCLASS, RANGE=1-10-1,1-10,
COL=VMT_PCTDIFF, RANGE=-100--50.1, -50--20.1, -20--10.1,
-10--0.1, 0.0, 0.1-10, 10.1-20,
20.1-50, 50.1-100, 100.1-1000,
-10-10.0,-20.0-20,-50.0-50,-100.0-100,
-1000.0-1000

ENDRUN
Frequently Asked Questions > Network > Is there a function in Voyager to merge networks based on a condition?

Is there a function in Voyager to merge networks based

on a condition?
This can be done using Netwo rk . In this example, input network #1 has a condition field
(link_attribute) indicating whether data will be merged from that network, or from network
#2. The example assumes that the links in net2.net are a subset of the links in net1.net.
run pgm=network
neti=net1.net, net2.net
neto=net3.net
merge record=f

phase=linkmerge

if (li.1.link_attribute=0)
; link_attribute=li.1.link_attribute
linkclass=li.1.linkclass
capacity=li.1.capacity ; should list all link attributes
:
:
else
linkclass=li.2.linkclass
capacity=li.2.capacity
:
:
endif

endphase

endrun
Frequently Asked Questions > Network > How do I merge a zonal data file into the node portion of a Voyager network?

How do I merge a zonal data file into the node portion of

a Voyager network?
Open the zonal data file as an input node file. Since all input node files to Netwo rk must
have a 'N' field, we must rename the zone field to 'N'. If it is an ASCII file, just name the
zone field 'N' in field definition.
; For ASCII zonal files
run pgm=network

neti=dtown.net
nodei[2]=zonedata.txt,
var=n, beg=1, len=5, ; name the zone field 'N'
var=sfdu, beg=6, len=12,
var=mfdu, beg=13, len=21
neto=dtown_zdat.net

endrun

If the file is a DBF, then rename ZONE to N using the RENAME sub-keyword. For
example:

; For DBF zonal files

run pgm=network

neti=dtown.net
nodei[2]=zonedata.dbf, rename=zone-n ; rename the zone
; field to 'N'
neto=dtown_zdat.net

endrun
Frequently Asked Questions > Network > How do I flag or delete unconnected nodes globally?

How do I flag or delete unconnected nodes globally?

The following script can optionally flag all unconnected nodes with a new node field
(UNUSED=1) or delete them.
run pgm=network
neti=simple.net
list=a(6), file=used_n.dat
list=b(6), file=used_n.dat
endrun

run pgm=network
neti=simple.net
nodei[2]=used_n.dat, var=n
neto=new.net
merge record=f
phase=nodemerge
; if (n2.n==0) UNUSED=1 ; to flag unused nodes only
if (n2.n==0) delete ; delete unused nodes
endrun
Frequently Asked Questions > Matrix & Distribution

Matrix & Distribution

1. How can I search for the closest node to an intersection record, and transfer information
from that intersection to the node record?

2. How can I convert a Voyager matrix to ASCII format without any zero-value cells skipped in
the output file?

3. How do I do non-50/50 balancing of PA matrices?

4. How do I split a zone into four sub-zones?

5. What do the statistics in a FREQUENCY report mean?

Frequently Asked Questions > Matrix & Distribution > How can I search for the closest node to an intersection record, and
transfer information from that intersection to the node record?

How can I search for the closest node to an intersection

record, and transfer information from that intersection to
the node record?
This example uses the M atrix program to find the closest node of an intersection record
with no node number and write out a new file with node number and name attribute
and/or other attributes in the node database.
First, create the sample RECI file with x, y, and street names using Pilo t commands.
copy file=reci.dat
2050 3550 A Street & B Street
1550 3050 Pacific Ave. & Park Way
2050 3050 I-580 NB off & Keller Ave.
endcopy

Then, use Netwo rk to create a node data file:

run pgm=Network
neti=a.net
nodeo=a.xy, format=sdf ; in delimited format
endrun

Use the M atrix module to find the closest node:

run pgm=matrix
; treat the node xy file as a zonal data file with z,x,y
zdati=a.xy, z=#1, x=#2, y=#3

; define the intersection record

reci=reci.dat, xcoord=1-4, ycoord=5-9

; set the highest node number as maximum zones

zones=114

; start the RECI record loop, do for each record in the

; RECI file

; Initialize minimum distance and closest node values

min_dist=999999
closest=0

; loop through each node

jloop
if ((zi.1.x[j] <> 0) && (zi.1.y[j] <> 0))
; calculate the distance between the intersection
; location and node location
dist=sqrt((ri.xcoord-zi.1.x[j])*(ri.xcoord-zi.1.x[j]) + (ri.ycoord-zi.1.y[j])*
(ri.ycoord-zi.1.y[j]))

; save info if less than previous nodes

if (dist < min_dist)
 min_dist=dist
closest=j
endif
endif
endjloop

; if there is a close by node, write out a record with

; node number and name
if (closest > 0)
str1=substr(reci,11,30)
print file=node.dat,list=closest(5),' ',str1
endif
endrun

Finally, use Netwo rk to merge the street name info back into the network.
run pgm=network
neti=a.net
nodei[2]=node.dat, var=n, beg=1, len=5, var=name, beg=7, len=30, typ=a
neto=a2.net
endrun
Frequently Asked Questions > Matrix & Distribution > How can I convert a Voyager matrix to ASCII format without any zero-
value cells skipped in the output file?

How can I convert a Voyager matrix to ASCII format

without any zero-value cells skipped in the output file?
The M ATO FORMAT=TXT process is designed to minimize file size. Therefore, when
the module sees a string of zeros, instead of writing them all, it generates a new record
with the next non-zero cell as the first value. By doing this the file size is minimized
without losing any information of the matrix. However, this creates a problem when all
cells are wanted in the output file. The following two examples will convert a Voyager
matrix to ASCII format without any zero-value cells skipped.
Frequently Asked Questions > Matrix & Distribution > How can I convert a Voyager matrix to ASCII format without any zero-
value cells skipped in the output file? > Example 1

Example 1
; Will have to remove the first two columns to get a true
; matrix

run pgm=matrix
mati=input.mat ; a Voyager matrix with series of zeros
mato=mat.txt mo=1 dec=0 pattern=ij:v fields=4,4,6 maxfields=20
zones=20
mw[1]=mi.1.1
jloop
if (mw[1][j]=0) mw[1][j]=0.0001
endjloop
endrun
Frequently Asked Questions > Matrix & Distribution > How can I convert a Voyager matrix to ASCII format without any zero-
value cells skipped in the output file? > Example 2

Example 2
run pgm=matrix
mati=testmat
jloop
list='\\',mi.1.1[j](6),file=testfile
endjloop
list='\n',file=testfile
endrun
Frequently Asked Questions > Matrix & Distribution > How do I do non-50/50 balancing of PA matrices?

How do I do non-50/50 balancing of PA matrices?

Let's take a simple example:
MW[1] = (MI.1.1 + MI.1.1.T) * 0.5

We assume that there are 100 trips produced in zone 1 and attracted to zone 2; and
200 trips produced in zone 2 and attracted to zone 1. The above equation will end up
with 150 trips going from zone 1 to zone 2 : (100 + 200) * 0.5 = 150. The equation will
also yield the same result from zone 2 to zone 1: (200 + 100) * 0.5 = 150.
The above equation can also be expressed as:
MW[1] = (MI.1.1 * 0.5) + (MI.1.1.T * 0.5)

To do non-50/50 balancing, we can vary the two factors but keep the total to 1.0 (100%,
unless we also want to factor the total up or down). Changing the first factor to 0.9 and
the second factor to 0.1 will yield a 90/10 split with 90% going from the production end to
the attraction end:
MW[1] = (MI.1.1 * 0.9) + (MI.1.1.T * 0.1)

This resembles an AM Peak condition, with most people going from their home
(production zone) to their jobs (attraction zone).
Frequently Asked Questions > Matrix & Distribution > How do I split a zone into four sub-zones?

How do I split a zone into four sub-zones?

The following example illustrates how to generate a zonal equivalency file using M atrix,
which then renumbers zones according to that file. This example assumes that zone
743 is split into sub-zones 743, 946, 947, and 948 at 10%, 20%, 30%, and 40%,
respectively. All other zones stay the same.
; generate a zonal equivalency file "zone_eq.txt"
run pgm=matrix

zones=945
if (z<743)
list=z(5),z(5),file=zone_eq.txt
elseif (z=743)
list= ' 743 743 10 \n',
' 743 946 20 \n',
' 743 947 30 \n',
' 743 948 40',
file=zone_eq.txt
else
list=z(5),z(5),file=zone_eq.txt
endif
endrun

run pgm=matrix
mati=input.mat
mato=output.mat mo=1
mw[1]=mi.1.1
; renumber zones according to "zone_eq.txt"
renumber file=zone_eq.txt
endrun
Frequently Asked Questions > Matrix & Distribution > What do the statistics in a FREQUENCY report mean?

What do the statistics in a FREQUENCY report mean?

To tal Obs is the total number of occurences within the BASEM W work matrix for this trip
purpose (VALUEM W )
To tal Sum is the sum of the respective VALUEM W .
M eanis computed as sum(BASEM W *VALUEM W )/sum(VALUEM W ) for all i, j. In a trip-length
frequency, it is the average trip length.
@I=J is the sum of intrazonal cells of the VALUEM W .
Frequently Asked Questions > TrnBuild

TrnBuild
1. How does TrnBuild calculate fares?

2. How can I obtain farelink fares?

3. Why is the total number of trips reported by the TrnBuild module less than the input trip
matrix total?
Frequently Asked Questions > TrnBuild > How does TrnBuild calculate fares?

How does TrnBuild calculate fares?

TrnBuildcomputes fares by accumulating boarding fares and xfer fares into the
MODEFARE variable (see MW). If there are farelinks, the fares accumulated by
crossing the fare links in the path are added to MODEFARE. There is not a way to
separate the farelinks, the various mode fares, etc. It is a difficult process. Ideally, the
program should have the same tools for fare as it does for time, distance, etc. But, that
process is also questionable: If a path goes through modes 11-13-2-2-13-13-5-2-12,
what fares should be assessed for the path? It has used three mode-13 links and three
mode-2 links; what fare should be applied?
FARELINK values may be obtained separately; but not by mode. Please see the next
question: How can I obtain farelink fares?
Frequently Asked Questions > TrnBuild > How can I obtain farelink fares?

How can I obtain farelink fares?

The only way that farelink fares can be obtained is through MW[]=MODEFARE. This
command obtains the sum of MODEFARES + FARELINKS.
M W []=FARE(....) sums the values from FARE MODEFARE.
The program accumulates FARELINK values into modefare, along with the M ODEFARE
values. To get FARELINK values separately (but not by mode) you need to add / subtract
the fares fromM ODEFARE s from the M ODEFARE value:
MW[]=MODEFARE - FARE(0)
Frequently Asked Questions > TrnBuild > Why is the total number of trips reported by the TrnBuild module less than the
input trip matrix total?

Why is the total number of trips reported by the TrnBuild

module less than the input trip matrix total?
TrnBuildreports only the trips associated with zones where there is Transit access. If the
program determines that it doesn't need to read the trips for a zone, it doesn't bother
reading them, and then it can't report the values from those rows. Suppose that you wish
to assign only the trips from the downtown area (say zones 1-60). The program is not
going to spend the time to read the entire matrix since it doesn't have to. This speeds up
processing in large systems where only selected processing is being done.
Introduction

Cube Voyager Reference Guide

Introduction
This chapter introduces you to Cube Voyager. Topics include:
• Design concepts

• Program features

• Minimum system requirements

Getting Started

Cube Voyager Reference Guide

Getting Started
This chapter describes how to get started using Cube Voyager. Topics include:
• Installation

• Starting Cube Voyager

Cube Cluster

Cube Voyager Reference Guide

Cube Cluster
This chapter discusses Cube Cluster, an optional extension you can use with Cube
Voyager. Topics include:
• Using Cube Cluster

• Control statements

• Utilities
General Syntax

Cube Voyager Reference Guide

General Syntax
This chapter describes the general syntax found in Cube Voyager. Topics include:
• Introduction to Cube Voyager control statements

• Control statement syntax

• Standard control statements

• Voyager Return Codes

General Syntax : Standard control statements : LOOKUP : Example: Double value function — Using LOOKUP with DBF
data in a trip Distribution application
Pilot Program

Cube Voyager Reference Guide

Pilot Program
This chapter describes the Pilot program, the basic driver for Cube Voyager application
programs. Topics include:
• Using Pilot program

• Control statements

• Examples and FAQ

Frequently Asked Questions

Cube Voyager Reference Guide

Frequently Asked Questions

This chapter lists frequently asked questions for Cube Voyager. Most topics are
organized by Voyager program, and include:
• Pilot and general syntax

• Fratar

• Highway

• Generation

• Network

• Matrix & Distribution

• TrnBuild
Fratar

Cube Voyager Reference Guide

Fratar
This chapter discusses Fratar distribution, a process for modifying a matrix values.
Topics include:
• Using Fratar

• Control statements

• Examples and FAQ

Highway Program

Cube Voyager Reference Guide

Highway Program
This chapter discusses the Highway program. Topics include:
• Using the Highway program

• Phases

• Control statements

• Theory

• Examples and FAQ

The junction file is part of the Highway program. For information about the junction file,
see Chapter 7, “Intersection Modeling.”
Intersection Modeling

Cube Voyager Reference Guide

Intersection Modeling
This chapter discusses intersection modeling, part of the Cube Voyager Highway
program. Cube 6.4 version supports HCM 2010 methods for modeling of All-Way stop
controlled, Two-Way stop controlled and Roundabout intersections.
Topics include:
• Introduction to intersection modeling

• Control statements

• Common keywords

• Signal-controlled intersections

• Two-way stop-controlled intersections

• All-way-stop-controlled intersections

• Roundabouts

• Priority junctions
Highway Program : Phases
Highway Program : Control statements : FILEO
Highway Program : Control statements : FILEO : QUEUEDATA Example
Highway Program : Control statements : PARAMETERS : TRACESUMMARY Example
Highway Program : Control statements : PARAMETERS : TRACESUMMARY Example
Highway Program : Control statements : PATHLOAD
Highway Program : Control statements : PATHLOAD
Intersection Modeling : Introduction to intersection modeling : Methodology for U-Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for U-Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for U-Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for Free Right Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for Free Right Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for Free Right Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for Free Right Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for Free Right Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for Free Right Turns at Signalized Intersections
Intersection Modeling : Introduction to intersection modeling : Methodology for Free Right Turns at Signalized Intersections
Network Program

Cube Voyager Reference Guide

Network Program
This chapter discusses the Network program. Topics include:
• Introduction to the Network program

• Control statements

• Theory

• Examples and FAQ

Matrix Program

Cube Voyager Reference Guide

Matrix Program
This chapter describes the Matrix program. Topics include:
• Using the Matrix program

• Control statements

• Examples and FAQ

Distribution Program

Cube Voyager Reference Guide

Distribution Program
This chapter discusses the trip distribution process. Topics include:
• Introduction to the Distribution program

• Control statements

• Examples and FAQ

Matrix Program : Using the Matrix program : Working with logit choice models : Absolute logit model : Introduction
Matrix Program : Using the Matrix program : Working with logit choice models : Absolute logit model : Logit Choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Absolute logit model : Logit Choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Absolute logit model : Logit Choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Absolute logit model : Logit Choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Absolute logit model : Scale parameter (cost-
based models)
Matrix Program : Using the Matrix program : Working with logit choice models : Incremental logit model : Introduction
Matrix Program : Using the Matrix program : Working with logit choice models : Incremental logit model : Incremental logit
choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Incremental logit model : Incremental logit
choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Incremental logit model : Incremental logit
choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Incremental logit model : Incremental logit
choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Incremental logit model : Incremental logit
choice model
Matrix Program : Using the Matrix program : Working with logit choice models : Hierarchical logit model : Introduction
Matrix Program : Using the Matrix program : Working with logit choice models : Hierarchical logit model : Introduction
Matrix Program : Using the Matrix program : Working with logit choice models : Hierarchical logit model : Cost-based
examples of hierarchic logit models
Matrix Program : Using the Matrix program : Working with logit choice models : Destination choice : Introduction
Matrix Program : Using the Matrix program : Working with logit choice models : Mode and destination choice : Mode followed
by destination choice
Generation Program

Cube Voyager Reference Guide

Generation Program
This chapter discusses the Generation program. Topics include:
• Introduction to Generation program

• Control statements

• Examples and FAQ

Public Transport Program

Cube Voyager Reference Guide

Public Transport Program

This chapter describes the Public Transport program. Topics include:
• Overview

• Processes

• Phases

• Control statements

• Reports

• Theory

• Using the Public Transport program

• Examples

• Troubleshooting
Public Transport Program : Control statements : CROWDMODEL : Example 2
Public Transport Program : Theory : Network simplification : Line-line legs
Public Transport Program : Theory : Crowding : Crowding process
Public Transport Program : Theory : Crowding : Crowding process
Public Transport Program : Examples : Public transport crowding
TRNBUILD Program

Cube Voyager Reference Guide

TRNBUILD Program
This chapter discusses the TRNBUILD program. Imported from TP+, TRNBUILD is an
alternative to the Public Transport program for modeling public transit. Topics in this
chapter include:
• Using TRNBUILD in Cube Voyager

• Introduction to TRNBUILD

• Control statements

• Examples and FAQ

Cube Avenue

Cube Voyager Reference Guide

Cube Avenue
This chapter discusses Cube Avenue, an optional extension to Cube Voyager. Topics
include:
• Using Cube Avenue

• Control statements

• Theory

• Examples
Utilities

Cube Voyager Reference Guide

Utilities
This chapter describes the utility programs included with Cube Voyager. Topics include:
• Shortest Path

• Link Consolidation

• Build Network from Feature Class

• UB2TPP

• TPP2UB

• SYNCHIMP

• Saturn conversion