Cube Voyager Reference Guide Cube Voyager Reference Guide

Cube Voyager
Reference Guide
Version 5.1.1

Citilabs

Revision 50-007-0 February 19, 2010

Cube Voyager Reference Guide

Cube Voyager Reference Guide iii

Contents

Contents

About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Design concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Program features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Minimum system requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 2

Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 Starting Cube Voyager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Starting Cube Voyager from Cube Base . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Starting Cube Voyager from Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Starting Cube Voyager from the command prompt. . . . . . . . . . . . . . . . 17

Chapter 3

General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Introduction to Cube Voyager control statements . . . . . . . . . . . . . . . . . . . . . 23 Control statement syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Statement tokens (%...%) and (@...@) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

iv Cube Voyager Reference Guide

Contents

Null blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Control blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Control fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Subkeywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Keyword values and documentation descriptions . . . . . . . . . . . . . . . . . 31 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Variable naming convention (general syntax) . . . . . . . . . . . . . . . . . . . . . 43 Standard control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Control statement introduction (general syntax) . . . . . . . . . . . . . . . . . . 45 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 CONSOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 GLOBAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 LOG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 LOOKUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 4

Pilot Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Using Pilot program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Statement tokens (%...% and @...@) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 *command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 CLEARERROR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 COPY ... ENDCOPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 DOWNLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Cube Voyager Reference Guide v

Contents

LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 NEWPAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 ONRUNERRORGOTO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104 PROMPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 RUN ... ENDRUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 SENDMAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Pilot example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Pilot example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Pilot example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Chapter 5

Fratar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Using Fratar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Specifying target values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 Controlling target totals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 Convergence Iteration control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 Multiple purposes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 SETPA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Chapter 6

Highway Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Using the Highway program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Highway introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Highway program control statement overview . . . . . . . . . . . . . . . . . . . 138 Functions and built-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 Getting started with assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Path-based tolls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 SETUP phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 LINKREAD phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 ILOOP phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 ADJUST phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 CONVERGE phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

vi Cube Voyager Reference Guide

Contents

ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 FILET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 FILLMW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 LINKLOOP ... ENDLINKLOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 PATHLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 SETGROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 SPDCAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 TURNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 Process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257 User stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 Highway example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 Highway example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Highway example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Highway example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Highway example 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264 Highway example 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 Highway example 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 Highway example 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Chapter 7

Intersection Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Introduction to intersection modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 Why use intersection modeling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Cube Voyager Reference Guide vii

Contents

How the intersection models work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Limitations of intersection modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 Cube Voyager intersection modelling and other programs. . . . . . . . 274 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 JUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 UNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Common keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 APPROACH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 APPROACH1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 ESTIMATEDDELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 EXITONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 INITIALQUEUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 MINIMUMCAPACITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 MOVEMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 NODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 RANDOMNESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 Signal-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Overview of signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 Generic keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Geometric keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296 Geometric signals example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300 Saturation flow signals example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Two-way stop-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 All-way-stop-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313 Roundabouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Overview of roundabouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Empirical roundabouts: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 Empirical roundabouts: Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 Gap acceptance roundabouts: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . 327 Gap-acceptance roundabouts: Example. . . . . . . . . . . . . . . . . . . . . . . . . . 328 Priority junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 Overview of priority junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Geometric priority junctions: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 331 Geometric priority junctions: Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 Saturation-flow priority junctions: Keywords . . . . . . . . . . . . . . . . . . . . . 336

viii Cube Voyager Reference Guide

Contents

Saturation-flow priority junctions: Example . . . . . . . . . . . . . . . . . . . . . . 338

Chapter 8

Network Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Introduction to the Network program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 Built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350 COMPARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 CROSSTAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354 DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 MERGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 PLOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 PLOTTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391 SPDCAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Phase descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393 Variable referencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Output variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397 Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Listing links to the print file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Merging link records from multiple ASCII files . . . . . . . . . . . . . . . . . . . . 401 Dumping link and node records to DBF files excluding select fields . . 401 Building network from inline data records. . . . . . . . . . . . . . . . . . . . . . . . 402 Simple link plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 Complex plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

Cube Voyager Reference Guide ix

Contents

Chapter 9

Matrix Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406

Using the Matrix program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Introduction to the Matrix program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407 Control statement types in Matrix program . . . . . . . . . . . . . . . . . . . . . . 411 Working with intrazonal cells of a matrix . . . . . . . . . . . . . . . . . . . . . . . . . 412 Working with lists of zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 Working with RECI/RECO processing in v4.0 and beyond. . . . . . . . . . 417 Working with logit choice models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456 BSEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 CALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458 CHOICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461 XCHOICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 FILET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 FILLMW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 FREQUENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 RENUMBER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 WRITE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 Example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 Example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 Example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 Example 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

x Cube Voyager Reference Guide

Contents

Example 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Example 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

Chapter 10

Distribution Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562

Introduction to the Distribution program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563 Convergence: Iteration control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 Multiple purposes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 Referencing productions and attractions . . . . . . . . . . . . . . . . . . . . . . . . . 570 Travel function values: Friction factors . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 GRAVITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576 SETPA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Distribution example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Distribution example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Distribution example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 581

Chapter 11

Generation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

Introduction to Generation program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587 BALANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Generation example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 Generation example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596

Chapter 12

Public Transport Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 Summary of facts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601 Preparing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 Network development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609 Route enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611

Cube Voyager Reference Guide xi

Contents

Route evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 Skimming (level of service) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 614 Loading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 Select link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 Loading analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638 Crowd modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 NODEREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 DATAPREP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 MATI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 SELECTIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649 SKIMIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 MATO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 651 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 655 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660 CROWDCRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662 CROWDMODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 664 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 EARLYCRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665 FACTORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666 FARESYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 687 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708 GENERATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739 IF... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741 LATECRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 744 LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745 LINKLOOP ... ENDLINKLOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757 MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 758 NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 OPERATOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 PTRUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771

xii Cube Voyager Reference Guide

Contents

REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 REREPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774 VEHICLETYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780 WAITCRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786 Enumerated routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787 Evaluated routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788 Fare matrices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792 Transit line summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 Transit line loadings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794 Transfers between modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 795 Transfers between operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 796 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 Generalized cost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797 Modeling approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803 Network simplification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808 Route-enumeration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 820 Route-evaluation process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 826 SFM and SFCM examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836 Skimming process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839 Loading process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 842 Fares. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845 Crowding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857 Using the Public Transport program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 Estimating demand matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 Defining input and output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 Linking Highway and Public Transport models . . . . . . . . . . . . . . . . . . . 865 Coding network times/speeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 Generating nontransit access and egress legs . . . . . . . . . . . . . . . . . . . . 869 Considering nontransit-only routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876 Public transport network development . . . . . . . . . . . . . . . . . . . . . . . . . . 876 Public transport skimming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881 Public transport loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883 Public transport user classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884

Chapter 13

TRNBUILD Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890

Using TRNBUILD in Cube Voyager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 Introduction to TRNBUILD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902 COMBINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 903

Cube Voyager Reference Guide xiii

Contents

FACTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 905 FARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 907 FARELINKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 912 LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 917 LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 MATRICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 MULTIACCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 927 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928 PHASE1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 930 PNR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934 SEGLIMITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 SELECT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938 SUPPLINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940 SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941 TRIPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945 XFERGEN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 947 XY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 948 ZONEACCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 949 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 952 Converting from TRNPTH to TRNBUILD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 953

Chapter 14

Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 956
UB2TPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 957 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 958 TPP2UB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 959 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 960 SYNCHIMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 962 Saturn conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964 Running from program window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 964 Running from command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 965

xiv Cube Voyager Reference Guide

Contents

Chapter 15

Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 968

Using Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969 Cube Cluster introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 969 Cube Cluster control statement summary . . . . . . . . . . . . . . . . . . . . . . . . 974 Working with Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 974 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987 DISTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987 DISTRIBUTEMULTISTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987 ENDDISTRIBUTEMULTISTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988 WAIT4FILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 988 DISTRIBUTEINTRASTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 990 Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992 Cluster executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 992 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 994

Chapter 16

Cube Avenue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 998

Using Cube Avenue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999 Cube Avenue introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1001 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1008 DYNAMIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1008 DYNAMICLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1009 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1014 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1019 PATHLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1023 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1025 Cube Avenue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1025 Cube Avenue calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1027 Functions and built-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1030 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1033 Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1033 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1034 LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1035 Simplifying LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1036 Centroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1036 ILOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1037 ADJUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1038 Enhancing ADJUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1039 Packet logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1040 Tuning parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1041 Reducing segment and volume lists . . . . . . . . . . . . . . . . . . . . . . . . . . . .1042

Cube Voyager Reference Guide xv

Contents

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1046

xvi Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide xvii

About This Document

About This Document

Welcome to Cube Voyager! This document provides detailed information about the features and capabilities of Cube Voyager. This document contains the following chapters: Chapter 1, Introduction Chapter 2, Getting Started Chapter 3, General Syntax Chapter 4, Pilot Program Chapter 5, Fratar Chapter 6, Highway Program Chapter 8, Network Program

xviii Cube Voyager Reference Guide

About This Document

Chapter 9, Matrix Program Chapter 10, Distribution Program Chapter 11, Generation Program Chapter 12, Public Transport Program Chapter 13, TRNBUILD Program Chapter 14, Utilities Chapter 15, Cube Cluster Chapter 16, Cube Avenue

Cube Voyager Reference Guide xix

About This Document

xx Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 1

Introduction

Introduction

This chapter introduces you to Cube Voyager. Topics include: Design concepts Program features Minimum system requirements

2 Cube Voyager Reference Guide

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: Network, Matrix, Highway, and Public Transport. In addition, the system offers supplementary programs for common transportation planning tasks, such as the Generate program for trip generation and the Distribution 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

Cube Voyager Reference Guide 3

Introduction Design concepts

a very complicated set of instructions, or can be as simple as computing and/or printing a number from a file. It is the users 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.

4 Cube Voyager Reference Guide

Introduction Program features

Program features
Advanced features of the Cube Voyager software include: Integration with ESRIs ArcEngine 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 95/98/NT/2000/XP 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)

Cube Voyager Reference Guide 5

Introduction Program features

Capability to link with user-generated native code

6 Cube Voyager Reference Guide

Introduction Minimum system requirements

Minimum system requirements

Cube Voyager requires a Windows 95/98/NT/2000/XP 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 75 MB of disk space is required to install Cube Base and Cube Voyager. Additional disk space is required for the various files. 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.

Cube Voyager Reference Guide 7

Introduction Minimum system requirements

8 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 9

Getting Started

Getting Started

This chapter describes how to get started using Cube Voyager. Topics include: Installation Starting Cube Voyager

10 Cube Voyager Reference Guide

Getting Started Installation

Installation
To install Cube Voyager, follow the steps outlined below: Install the Citilabs license CD first Once the license files are installed, Cube Voyager should automatically be selected during the installation of Cube

Cube Voyager Reference Guide

11

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

Starting Cube Voyager from Cube Base

Cube Voyager should be started from Cube. After creating a new Cube Voyager application or opening an existing one, go to the Program menu, point to Passenger Forecasting, then VOYAGER to access Cube Voyager programs from the menus. See Chapter 14, Application Manager, in the Cube Base Reference Guide for general information on setting up an application in Application Manager. See Running application in Application Manager on page 655 of the Cube Base Reference Guide and Running a Cube Voyager, TP+, or TRIPS program on page 655 of the Cube Base Reference Guide for specific information on running a Cube Voyager application or program from Cube. When running a Cube Voyager 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 Monitor. See Chapter 16, Task Monitor, in the Cube Base Reference Guide for a detailed description of this program. Task Monitor sends the Cube Voyager

12 Cube Voyager Reference Guide

Getting Started Starting 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.

Starting Cube Voyager from Windows

If Cube Voyager has been properly installed, Cube Voyager can be started from: Start Menu, Run, then type or browse for VOYAGER.EXE (the default directory is C:\Program Files\Citilabs\CubeVoyager), then click enter The Cube Voyager run monitor window will open and prompt the user for the following data: The name of the script file that is to be run

Cube Voyager Reference Guide

13

Getting Started Starting Cube Voyager

The working directory where the basic application data is stored A system prefix (max of 4 characters) The desired height and width of a printed page A Run ID (character string) that will be printed at the top of every printed page

Users can use either the Browse or the Favorite 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 Edit Input 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 577 of the Cube Base Reference Guide.

14 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

The Work Directory is defaulted to the directory where the job script file resides when a new job script file is selected. When this data is completed and the Start button is pressed, Cube Voyager begins execution and the Start and the Cancel buttons become the Pause and the Abort 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 View Print File button can be pushed to view the resulting run print file. The Notify When Done check box can be used to bring the Cube Voyager window back on top when its 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.

Cube Voyager Reference Guide

15

Getting Started Starting Cube Voyager

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 Wait Start 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.

16 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

The About Voyager 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.

Starting Cube Voyager from the command prompt

You can run Cube Voyager completely from a command prompt (if this capability is available). 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:

Cube Voyager Reference Guide

17

Getting Started Starting Cube Voyager

scriptfile is the name of the file that contains the Cube Voyager

script control statements. The 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.
pageht is 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.
pagewdth is the maximum length a printed line can have. It

may not be less than 72, nor greater than 255. If it is not specified, and a width can not be found from the Cube Voyager

18 Cube Voyager Reference Guide

Getting Started Starting 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.
workdir is 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 can be 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 /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

Cube Voyager Reference Guide

19

Getting Started Starting Cube Voyager

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

20 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide

21

General Syntax

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

22 Cube Voyager Reference Guide

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.
Example
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: & doesnt fit here mfdus= 61-65

Cube Voyager Reference Guide

23

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)

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.

24 Cube Voyager Reference Guide

General Syntax Control statement syntax

Example
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

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.
Example
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 nonblank 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.

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

Cube Voyager Reference Guide

25

General Syntax Control statement syntax

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

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

26 Cube Voyager Reference Guide

General Syntax Control statement syntax

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.

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.

Cube Voyager Reference Guide

27

General Syntax Control statement syntax

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.
Examples of numbers specified as single or range values
Expression 1-5, 1- 5, 1 5 1 5 1 5, 1,5, 1 , 5 1,-5 1 , -5 135 -1-5 -1--5 -8--5 -8 - -5 Meaning three ways of specifying range: 1 through 5. value 1, and value -5. three ways of specifying: value 1 and value 5. error! value 1 and value -5 value 1 and range: 3 through 5. range: 1 through +5 range: -1 through -5; descending, and could be an error. range: -8 through -5, but doesnt look nice. 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 52.

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

28 Cube Voyager Reference Guide

General Syntax Control statement syntax

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 rows 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.
Examples
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]

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

Cube Voyager Reference Guide

29

General Syntax Control statement syntax

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:
Example
(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.

30 Cube Voyager Reference Guide

General Syntax Control statement syntax

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.
Letter C D F Description Character -- any valid text string, but only the first character is used. Double Double-precision real numbers. 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.) Integer -- numbers that are entered without decimal points. If a decimal point is entered, the value will be processed as the nearest integer. 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 doesnt 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.

Cube Voyager Reference Guide

31

General Syntax Control statement syntax

Letter N s

Description Numeric expression -- expressions that will result in a number. See Numeric expressions on page 33 for details of expressions. selection expression -- a special form for establishing complex selection criteria; usually IF statements. The expression must be enclosed within (...). See Selection expressions on page 40 for details of expressions. 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:
Character a K Description Ascending order Values must be listed in ascending order. 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. Pairs -- The values may be entered as single values or as pairs of numbers (two numbers separated by a dash.) 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. 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.

P V

[n]

32 Cube Voyager Reference Guide

General Syntax Control statement syntax

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

Numeric 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):
Operator Addition Subtraction Multiplication Division Modular Exponentiation Symbol + * / % ^ Level 1 (in strings, "+" is a concatenator) 1 2 2 2 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 format:

Cube Voyager Reference Guide

33

General Syntax Control statement syntax

[ddd] [.] [ddd] [fmt[sn]ddd], where: [ddd] [.] [fmt] optional digits (0-9) optional decimal point optional e or E

Character 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[] or MW[][]. 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 users 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. A general rule is that when a MW is on the left side of an expression (the result) the subscripts must be constants or variables, and when MW is within an expression, the subscripts may be expressions, constants, and/or variables.
Function MW[#] MW[#][n] MW[#][X] MW[W] MW[W][X] Description The Jth cell in work matrix #. The nth cell in work matrix #. The Xth cell in work matrix #. The Jth cell in work matrix W. The Xth cell in work matrix W.

# is a hard-coded constant. X and W may be dynamically computed (users responsibility). Most programs will detect an invalid index, and terminate with a fatal condition.

34 Cube Voyager Reference Guide

General Syntax Control statement syntax

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 Character functions Lookup functions

Numeric functions
Function ABS(x) CmpNumRetNum(V1,OP,V2,R1,R2) Description Absolute value 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. EXP(x) EXPDIST(x,m,t) Exponential e to the x (-103 < x < 88) Probability density (if t=0) or cumulative probability (if t>0) at x given an exponential distribution with mean m.

Cube Voyager Reference Guide

35

General Syntax Control statement syntax

Function EXPINV(p,m)

Description Inverse of exponential cumulative function at probabiliy p given an exponential distribution with mean m. (0 p 1). 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) 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) 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. Truncated integer value Natural logarithm (x > 0) Common logarithm (x > 0) Probability density (if t=0) or cumulative probability (if t>0) at x if x has a lognormal distributionthat is, if LOG(x) follows a normal distribution with mean m and standard deviation s. Inverse of lognormal cumulative function at probabiliy p given a lognormal distributionthat is, the logarithms of values follow a normal distribution with mean m and standard deviation s. (0 p 1) Maximum value from the list Minimum value from the list

GAMMADIST(x,a,b,t)

GAMMAINV(p,a,b)

INLIST(n,str)

INT(x) LN(x) LOG(x) LOGNORMDIST(x,m,s,t)

LOGNORMINV(p,m,s)

MAX(x,y,...) MIN(x,y,...)

36 Cube Voyager Reference Guide

General Syntax Control statement syntax

Function NORMDIST(x,m,s,t)

Description Probability density (if t=0) or cumulative probability (if t>0) at x given a normal distribution with mean m and standard deviation s. Inverse of normal cumulative function at probabity p given a normal distribution with mean m and standard deviation s. (0 p 1) Probability density (if t=0) or cumulative probability (if t>0) of x occurrences given a Poisson distribution with mean and variance v. Inverse of Poisson cumulative function at probability p given a Poisson distribution with mean and variance v. (0 p 1) Power (x=base, y=exponent) Return a random floating point number between 0 and < 1 Return a random integer between 0 and n-1, n is an integer between 1 and 2147483647 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 Rounded integer value Square root (x > 0)

NORMINV(p,m,s)

POISSONDIST(x,v,t)

POISSONINV(x,v)

POW(x,y) RAND() RANDOM(n)

RANDSEED(n)

ROUND(x) SQRT(x)

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

convert radians to degrees:

Cube Voyager Reference Guide

37

General Syntax Control statement syntax

Degrees=Radians*180/
Function ARCCOS(x) ARCSIN(x) Description Returns the ARCCOS of x. Returns the ARCSIN (inverse SIN) of x. Example VAR2=ARCSIN(0.5) would return a value of 30. ARCSIN(SIN(x))=x Returns the ARCTAN of x. Returns the COS of x. Returns the SIN of x where x is in degrees. Example VAR1=SIN(30) would return a value of 0.5. Returns the TAN of x.

ARCTAN(X) COS(x) SIN(x) TAN(x)

Character functions
Function1 DELETESTR(s1,n1,n2) DUPSTR(str,n) FORMAT(x,w,d,str) Description Deletes n2 characters in s1 starting at n1 (1 is the first character); if n1 or n2 is < 1, then return s1. Duplicates str n times; result must be less than 100 chars. Formats number (x) with width=w, decimals=d, format=str. The str pattern can contain any characters, but any single, or string of, m, d, or y in the pattern will cause x (first argument) to be treated as a date in the format of yyyymmdd, and its corresponding element formatted in place of the m, d, or y string. For example: yy/mm/dd will result in 07/02/13 if n=20070213. "abc m:d:y" would result in "abc 2/3/2007". If m or d is a single character, the rightmost digit is used, any other string of m or d will cause a two-digit result. If y is 2, the year is formatted in two digits; any other string of y will cause a four-digit result. If multiple occurrences of any of the y, m, or d occur, the result will contain multiple values. "dd/mm/yy abcm" will result in "07/02/13 abc2." INSERTSTR(s1,s2,n) Inserts s1 into s2 at n; if n < 2, return s1+s2; if n > length of s2, return s2+s1.

38 Cube Voyager Reference Guide

General Syntax Control statement syntax

Function1 LEFTSTR(s1,n) LTRIM(str) REPLACESTR(s1,s2,s3,n)

Description Returns n characters from the left side of s1; if the length of s1 is less than n, or n is < 0, returns s1. Deletes leading spaces from str. 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. Same as REPLACESTR but ignores case when searching for s2 within s1. Reverses s1. Returns n characters from the right side of s1; if the length of s1 is less than n, or n is < 0, return s1. 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. Returns the length of str. Sets str to lowercase for immediate use; str is not permanently changed. Returns the position in str2 where str begins. If str does not exist in str2, returns 0. Both strings are case sensitive. 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. Sets str to uppercase for immediate use; str is not permanently changed. 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.

REPLACESTRIC(s1,s2,s3,n) REVERSESTR(s1) RIGHTSTR(s1,n) STR(v,w,d)

STRLEN(str) STRLOWER(str) STRPOS(str,str2)

STRPOSEX(s1,s2,n1)

STRUPPER(str) SUBSTR(str,b,n)

TRIM(str) VAL(str)

Deletes trailing spaces from str. Returns the numeric value contained in str.

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

Cube Voyager Reference Guide

39

General Syntax Control statement syntax

Lookup functions

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 55 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.
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)

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):.
Expression A=B A == B A != B Description A equals B. A equals B. A is not equal to B.

40 Cube Voyager Reference Guide

General Syntax Control statement syntax

Expression A >= B A <= B A>B A<B A <> B

Description A is greater than, or equal to, B. A is less than, or equal to, B. A is greater than B. A is less than 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)

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

Cube Voyager Reference Guide

41

General Syntax Control statement syntax

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.
Example of complex selection
( (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)) ) ))

Examples of keyword 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

Examples of expressions
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.

42 Cube Voyager Reference Guide

General Syntax Control statement 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.
Rule Length: Description 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 ). A-Z, a-z, 0-9, _$#@ Insensitive. Any of the valid characters, except 0-9. Convention is to use underscore _ as the first character.

Valid Characters: Case: First Character: Temporary variables:

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:
Prefix T I # Description File type (L=Link, N=Node, M=Matrix, Z=ZonalData). Indicates Input Index (explicit or implied) number of the file type named on a FILEI control statement.

Cube Voyager Reference Guide

43

General Syntax Control statement syntax

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

Filename format MI.3.varname Description 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 refers to the variable named varname found in the node portion of the network file designated by NETI[3]= on the FILEI control statement. refers to the variable named varname found in the link portion of the network file designated by NETI[2]= on the FILEI control statement. 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].

NI.3.varname

LI.2.varname

ZI.5.varname

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

44 Cube Voyager Reference Guide

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

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.

Cube Voyager Reference Guide

45

General Syntax Standard control statements

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 |...|.
Key Key1 Key2 Key3 Description A keyword that must be followed by an equals sign and appropriate value(s). 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). 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

46 Cube Voyager Reference Guide

General Syntax Standard control statements

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.
Keyword values AAA=3 BBB=5 DDD=2 EEE=25,FFF=Y AAA=3 DDD=2 BBB=5 KKK=27 FFF=Y HHH=5 BBB=5 CCC=6 DDD=7 CCC=8 BBB=9 Description Valid. Invalid: DDD must follow BBB or CCC Invalid: KKK must follow JJJ. Invalid: HHH must follow GGG Valid.

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

Cube Voyager Reference Guide

47

General Syntax Standard control statements

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.

CONSOLE
A CONSOLE statement is used to set certain switches relative to dynamic display of messages in the message area of the window.
Statement CONSOLE ONLINE=Y CONSOLE ONLINE=N CONSOLE MESSAGE=text Description Causes all subsequent text written to the standard print media to also be written to the console. Turns off the ONLINE=Y switch Causes text to be written to the console.

FILEI
FILEI tells 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,

48 Cube Voyager Reference Guide

General Syntax Standard control statements

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]= MATI[2]= MATI[5]=, Abc=def ; ; ; ; this is single FILEI statement this is a single FILEI statement this is a FILEI statement with continuation 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 applications .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.)

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

Cube Voyager Reference Guide

49

General Syntax Standard control statements

Manager opens when you double-click an output file box. (See Chapter 14, Application Manager, in the Cube Base Reference Guide.)

GLOBAL
Alters the size of a page on the standard print media. The keywords are trigger keywords; you need not specify GLOBAL.
GLOBAL keywords
Keyword PAGEHEIGHT |KI| Description 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 1032767. 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. 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.

PAGEWIDTH

|KI|

If these parameters are specified, they remain in effect through subsequent programs until revised.
Example
PAGEHEIGHT=32767 ; preclude insertion of page headers

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)

50 Cube Voyager Reference Guide

General Syntax Standard control statements

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.
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:
Example of Computing the ID
LOOP PASS=1,5 COMP ID=This is Pass+str(PASS,2,0) RUN PGM= ENDRUN ENDLOOP

Example
ID=This is the new Page Header

Cube Voyager Reference Guide

51

General Syntax Standard control statements

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.
Example
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:

Value of I -1 3 9 >9 Statements executed S1 S2 S3 S4

52 Cube Voyager Reference Guide

General Syntax Standard control statements

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

LOG
Writes values to the log file PREFIX 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

Cube Voyager Reference Guide

53

General Syntax Standard control statements

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

54 Cube Voyager Reference Guide

General Syntax Standard control statements

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 keywords
Keyword PREFIX |S| Description 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. Indicates which variables will have their values written to the .VAR file.

VAR

|S|

Example
RUN PGM=MATRIX . LOG PREFIX=MATRIX1, VAR=TOTMW1, AVEMW LOG VAR=GRANDTOTAL ; will be written as MATRIX1.GRANDTOTAL=#####

LOOKUP
NAME (LOOKUP (RESULT)) LOOKUPI FILE FAIL SIZE INTERPOLATE LIST R SETUPPER NEAREST TOLERANCE

A LOOKUP statement is used to define a lookup function and to enter data for the function. 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

Cube Voyager Reference Guide

55

General Syntax Standard control statements

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.
LOOKUP keywords
Keyword FAIL Subkeyword Type |RV3| Description 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. 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. Indicates if the program is to format and list the lookup table.

INTERPOLATE

|?|

LIST

|?|

56 Cube Voyager Reference Guide

General Syntax Standard control statements

LOOKUP keywords (continued)

Keyword LOOKUPI Subkeyword Type |I| Description 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 of the lookup function that the statement defines. 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. Field number or name of the field from the data record that contains the result to be returned when the function is called. 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.

NAME NAME LOOKUP

|S| |S|

NAME

RESULT

|S|

NEAREST

|?|

Cube Voyager Reference Guide

57

General Syntax Standard control statements

LOOKUP keywords (continued)

Keyword R Subkeyword Type |SV| Description 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 62 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. 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. 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. 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.

SETUPPER

|?|

SIZE

|I|

TOLERANCE

|R|

58 Cube Voyager Reference Guide

General Syntax Standard control statements

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

Cube Voyager Reference Guide

59

General Syntax Standard control statements

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, 1, 2, 3, 4, 5, v1, v2, v3 101, 201, 301 102, 202, 302 103, , 303 104, 204 , , 305

60 Cube Voyager Reference Guide

General Syntax Standard control statements

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 dont 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.
Example: Single value function
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:

Lower Limit 1 2 3 4 9 23 50 Upper Limit 1 2 3 8 10 23 50 Result Value 2 1 1 1 3 1 15

DISTRICTS(6) results in the value 1. DISTRICTS(9) results in 3. DISTRICTS(50) results in 15.

Cube Voyager Reference Guide

61

General Syntax Standard control statements

Example: Single value function using LOOKUPI

FILEI LOOKUP[1]=C:\LOOK1.DAT LOOKUP NAME=DISTRICTS, LOOKUPI=1 LIST=Y

Example: Double value function Typical friction factor 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, LOOKUP[1]=1, RESULT=2, LOOKUP[2]=1, RESULT=3, ; ; ; ; ; typical Friction Factor Curve 1 lookup value is Result (FF) for curve 1 Curve 2 lookup value is Result (FF) for curve 2 table in field 1 is in field 2 in field 1 is in field 3

62 Cube Voyager Reference Guide

General Syntax Standard control statements

LOOKUP[3]=1, RESULT=4, FAIL=2000,1,0,

INTERPOLATE=Y, 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 */

; ; ; ; ;

Curve 3 lookup value is in field 1 Result (FF) for curve 3 is in field 4 return 2000 if any lookup < 0.01 return 1 if any lookup > 120 interpolate to obtain values

The lookup table will be represented as:

Curve # 1 1 1 1 1 1 2 2 2 2 2 3 3 3 3 Lower Limit 0.01 1 3 4 5 120 0.01 1 3 4 120 0.01 1 4 120 Upper Limit 0.01 1 3 4 5 120 0.01 1 3 4 120 0.01 1 4 120 Result Value 1200 1200 300 100 50 50 1000 1000 500 100 100 800 800 100 100

Cube Voyager Reference Guide

63

General Syntax Standard control statements

Example: Double value function 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

Example: Double value function Using LOOKUP to get constants and populate 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

64 Cube Voyager Reference Guide

General Syntax Standard control statements

*/

Example: Double value function Using LOOKUP with DBF data in a trip Distribution application
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:

Cube Voyager Reference Guide

65

General Syntax Standard control statements

PRINT
Formats data items and writes them as 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.
CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT)

PRINT keywords
Keyword CFORM Subkeyword |S| Description 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 71. 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: FILE |F| T Print in CSV format, with commas between each LIST item F Do not print in CSV format

Default value is 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 endof-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.

66 Cube Voyager Reference Guide

General Syntax Standard control statements

PRINT keywords (continued)

Keyword FILE Subkeyword APPEND |?| Description 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 PRINT |?| Optional. Flag indicating whether to write record to standard printed output in addition to specified file. Possible values: FILE REWIND |?| 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. 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 70. Default value is 10.2.

Cube Voyager Reference Guide

67

General Syntax Standard control statements

PRINT keywords (continued)

Keyword LIST Subkeyword |KS| Description 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 70 and Defining a character print format on page 71. 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. NOTE: Because special characters are 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".

68 Cube Voyager Reference Guide

General Syntax Standard control statements

PRINT keywords (continued)

Keyword LIST (continued) Subkeyword Description 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. |I| PRINT |?| Optional. Index number of the FILEO PRINTO file where the program writes this output. Optional. Flag that indicates whether to write record to standard printed output in addition to specified PRINTO file. Possible values: PRINTO REWIND |?| T Write the record to the standard printed output in addition to the specified file F Only write the record to the specified file

PRINTO PRINTO

Default value is F. 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.

Examples

Report a mixture of numeric and character variables.

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

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

Cube Voyager Reference Guide

69

General Syntax Standard control statements

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

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

70 Cube Voyager Reference Guide

General Syntax Standard control statements

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

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

Cube Voyager Reference Guide

71

General Syntax Standard control statements

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.

72 Cube Voyager Reference Guide

General Syntax Standard control statements

PRINTROW
Formats and prints all cells or selected cells of a matrix row to the main print file. 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.
PRINTROW keywords
Keyword BASE1 |?| Description 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 70. 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 66.

Cube Voyager Reference Guide

73

General Syntax Standard control statements

PRINTROW keywords (continued)

Keyword J |IP| Description 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 MAXPERLINE to some integral of 10.
Example
PRINTROW mw=1-2,8 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10

74 Cube Voyager Reference Guide

General Syntax Standard control statements

READ
Switches reading of control statements to a different file. The format is:
READ FILE=filename, oldstring=newstring, oldstring=newstring, ....

READ keywords
Keyword FILE Description 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. Character string that will replace oldstring in the records in FILE that contain oldstring. Newstring is case sensitive; it will be replaced directly. 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.

newstring

oldstring

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.
Example
READ FILE=BUSLINES, MODE=5 = MODE=3

Cube Voyager Reference Guide

75

General Syntax Standard control statements

SORT
Sorts an array, or series of arrays. The format is:
SORT ARRAY=name, name, NUMRECS=x

SORT keywords
Keyword ARRAY |S| Description 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.

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

76 Cube Voyager Reference Guide

General Syntax Standard control statements

Example 2 (Matrix, Fratar, Distribution, Generation)

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

Example 3 (Network)
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

Cube Voyager Reference Guide

77

General Syntax Standard control statements

78 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide

79

Pilot Program

Pilot Program

This chapter describes the Pilot program, the basic driver for Cube Voyager application programs. Topics include: Using Pilot program Control statements Examples

80 Cube Voyager Reference Guide

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 @...@)

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

Cube Voyager Reference Guide

81

Pilot Program Using Pilot program

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.

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

82 Cube Voyager Reference Guide

Pilot Program Using Pilot program

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

Flow control statements Help to determine which statement is to be performed next. Typical flow control statements are:

GOTO :LABEL ONRUNERRORGOTO CLEARERROR LOOP BREAK CONTINUE ENDLOOP IF ELSEIF ELSE ENDIF EXIT

Cube Voyager Reference Guide

83

Pilot Program Using Pilot program

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=

System statements Program initiates an operating-system

command. A system statement is 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.
Example
*COPY *.DAT d:

84 Cube Voyager Reference Guide

Pilot Program Using Pilot program

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.

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

Cube Voyager Reference Guide

85

Pilot Program Using Pilot program

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

86 Cube Voyager Reference Guide

Pilot Program Control statements

Control statements
This section describes the control statements available in the Cube Voyager Pilot program.
Control statement *command BREAK CLEARERROR COMP CONTINUE COPY ... ENDCOPY DOWNLOAD EXIT FILEI FILEO GOTO IF ... ELSEIF ... ELSE ... ENDIF LOOP ... ENDLOOP NEWPAGE ONRUNERRORGOTO PARAMETERS PRINT PROMPT REPORT RUN ... ENDRUN SENDMAIL Description Perform an OS system command with OS window minimized Break out of current loop Clear a run error to allow continued processing Compute variables Continue to end of loop Copy records to a file Download specified file(s) from a URL Exit current phase Specify input file with existing variable values Specify output file PRINTO[#]=fname Jump to a specific control statement Standard IF block Setup a user loop Control new-page processing Jump to a specified :label when an error condition is encountered Specify basic parameter values Print variable values Pause execution and wait for user input Turn reports on/off Runs a specified program Send mail with attachments based on conditions of the run

Cube Voyager Reference Guide

87

Pilot Program Control statements

*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 users 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.
Example
*DEL ABCD*.TMP *IF EXIST OLD.NET DEL OLD.NET

Or:
**DEL ABCD*.TMP **IF EXIST OLD.NET DEL OLD.NET

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.

88 Cube Voyager Reference Guide

Pilot Program Control statements

Example
LOOP i=1,3 IF (condition) statements ELSE BREAK ; get out of loop ENDIF ENDLOOP

CLEARERROR
CODE RESUME 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 users responsibility to set those values with the keywords.
CLEARERROR keywords
Keyword CODE RESUME |I| |?| Description Internal error code is reset to this value. Can be a value of 0,1. 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.

Example
ONRUNERRORGOTO = 'MYERROR' :STEP1 RUN PGM=MATRIX ENDRUN ;At this point control will transfer to :MYERROR :STEP2 RUN PGM=. ENDRUN

Cube Voyager Reference Guide

89

Pilot Program Control statements

:STEP3 RUN PGM= ENDRUN :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 RESUME=T ; At this point, control will return to :Step2

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

Var is 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.

90 Cube Voyager Reference Guide

Pilot Program 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.
Lambda is a special case variable, and Lambda must also be a

variable within the expression. 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: Set a min and max Lambda (0 and 1.0) Divide the difference between min and max into equal intervals. Solve for all the interval points between min and max. 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. Reset the min and max Lambdas to the interval points that contain 0. If the interval size is not within the accepted tolerance, repeat steps 2-5. 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.

Cube Voyager Reference Guide

91

Pilot Program Control statements

The statement need not have COMP, it may begin directly with var=.
Example
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)

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.
Example
LOOP i=1,3 IF (condition) statements ELSE CONTINUE ; jump to ENDLOOP ENDIF ENDLOOP

COPY ... ENDCOPY

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

92 Cube Voyager Reference Guide

Pilot Program Control statements

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.
COPY and ENDCOPY keyword
Keyword Description |F| Name of the file onto which the records are to be copied. Must be an acceptable name for the operating system.

FILE=filename

Example
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) ...

DOWNLOAD
URL FILEO CLEARFILEO

Cube Voyager Reference Guide

93

Pilot Program Control statements

Downloads a file from the internet from the specified URL.

DOWNLOAD keywords
Keyword CLEARFILEO |?| Description <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).

EXIT
Terminates the program.
Example
IF (expression) EXIT

FILEI
NOTE: See FILEI on page 48 for general information about FILEI

and for important limitations when using Application Manager. 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.

94 Cube Voyager Reference Guide

Pilot Program Control statements

VARI=filename
FILEI keywords
Keyword LOOKUPI |FKV999| Description 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. 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.
Example
VARI=XXXX.VAR

FILEO
Specifies an output file for the PRINT PRINTO capability when printing from Pilot. PRINTO[#]=filename
FILEO keyword
Keyword PRINTO |KF| Description Specifies the name of the file where the output from the PRINT statement is to be directed

Cube Voyager Reference Guide

95

Pilot Program Control statements

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

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 (:).
Example 1
GOTO hwybuild GOTO :hwybuild

96 Cube Voyager Reference Guide

Pilot Program Control statements

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

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

Example
; Single IF examples:

Cube Voyager Reference Guide

97

Pilot Program Control statements

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

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.

98 Cube Voyager Reference Guide

Pilot Program Control statements

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.
Example 1

Executes the code within the LOOP block 10 times.

LOOP iter=1,10 . . ENDLOOP

Example 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

Cube Voyager Reference Guide

99

Pilot Program Control statements

NEWPAGE
beforepgm afterpgm beforesys aftersys Controls the printed output when the program invokes an external process. 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.
NEWPAGE keywords
Keyword afterpgm aftersys beforepgm beforesys |?| |?| |?| |?| Description Starts a new page after a PGM returns. Starts a new page after a system command. Sets the line counter so that the invoked PGM will start on a new page. Starts a new page before performing the system command.

Example:
NEWPAGE beforepgm=y afterpgm=n beforesys=y aftersys=y

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

100 Cube Voyager Reference Guide

Pilot Program Control statements

statement is executed, the program sets a return code that indicates what type of message the program returned on closing. The codes returned are:
Code 0 = No messages 1 = Warning messages 2 = Fatal messages 3 = Program aborted Description The job ran to completion successfully. The job ran to completion but generated one or more warning messages. The job failed to run to completion and generated on or more fatal error messages. The job was aborted by user conditions with the 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 96 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 111 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.

Cube Voyager Reference Guide 101

Pilot Program Control statements

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 89).
Example 1
RUN PGM=MATRIX ENDRUN

At this point the job will terminate because there was an error in the Matrix program (no operations).
Example 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

Example 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

102 Cube Voyager Reference Guide

Pilot Program Control statements

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

Example 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

PARAMETERS
Specifies basic parameter values for the Pilot run. MAXSTRING

Cube Voyager Reference Guide 103

Pilot Program Control statements

<> is the program default value.

PARAMETERS keyword
Keyword MAXSTRING |KI| Description 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. 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.

PRINT
Formats and prints a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) The standard Cube Voyager PRINT statement can be used (see PRINT on page 66).
Example 1
LIST= ITER(6) TIMEPERIOD(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001 PRINT FORM=6.0CDLR LIST= ITER, TIMEPERIOD,TOTAL1,TOTAL2 FILE=PRINTFIL.002

Example 2
PRINT PRINTO=1 FORM=6.0CDLR LIST=ITER, TIMEPERIOD, TOTAL1, TOTAL2

104 Cube Voyager Reference Guide

Pilot Program Control statements

PROMPT
QUESTION= ANSWER= WAIT= 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.
PROMPT keywords
Keyword ANSWER |S5| Description Possible answers. The same rules about quotes in QUESTION also apply here. There may be up to 5 ANSWERs. Question to prompt the user with. Enclose with quotes or ""; if it contains any delimiters, it must be within quotes.

QUESTION

|KS|

Cube Voyager Reference Guide 105

Pilot Program Control statements

PROMPT keywords (continued)

Keyword WAIT |R| Description 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.
Example
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 PROMPT

106 Cube Voyager Reference Guide

Pilot Program Control statements

REPORT
VARS STACK TRACE
REPORT keywords
Keyword STACK |?| Description 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. 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. When set to true, the program lists the current variables and their values from the VARS array.

TRACE

|K?|

VARS

|?|

Example
REPORT Vars=y REPORT Trace=y ; turn stack tracing on REPORT Trace=n ; turn stack tracing off

RUN ... ENDRUN

Loads and executes a program. PGM=name CTLFILE=name PRNFILE=name REDIRECTIN REDIRECTOUT PARAMETERS

Cube Voyager Reference Guide 107

Pilot Program Control statements

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 nonCube 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 clientdeveloped program to run in accordance with Citilabs specifications, or a standard OS executable RUN file.
RUN keywords
Keyword CTLFILE |F| Description Optional. File be used as the programs 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. 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.

PARAMETERS

|SV|

108 Cube Voyager Reference Guide

Pilot Program Control statements

RUN keywords (continued)

Keyword PGM |S| Description 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. Optional. Switch to indicate that CTLFILE is to be directed into the program. Optional. Switch to indicate that the program is to direct its output to PRNFILE, if PRNFILE is also specified.

REDIRECTIN REDIRECTOUT

|?| |?|

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

Cube Voyager Reference Guide 109

Pilot Program Control statements

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 F F F F T T T T RDO F F T T F F T T prnfile T F T F T F T F Generated command
pgm ctlfile prnfile parameters pgm ctlfile parameters pgm ctlfile parameters >prnfile pgm ctlfile parameters >tprn pgm prnfile parameters <ctlfile pgm parameters <ctlfile pgm parameters <ctlfile >prnfile 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 Examples
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"

110 Cube Voyager Reference Guide

Pilot Program Control statements

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

SENDMAIL
SMTPSERVER FROM TO CC SUBJECT MESSAGE ATTACHMENTS USERNAME PASSWORD PORT

Cube Voyager Reference Guide 111

Pilot Program Control statements

Immediately sends an e-mail. Use 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.
SENDMAIL keywords
Keyword ATTACHMENTS CC FROM MESSAGE |S| |S| |S| |S| Description List of file names sent as attachments. There is a maximum of 1000 attachments. E-mail address(es) for copied recipient(s). E-mail address to be sent as the return 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 for the account specified in USERNAME, if the SMTP server requires secure logon. If coding your script in Cube, you can insert the password value with the Insert menu command then selecting Password for email. Cube opens a Password Entry dialog box, which t allows you to mask the password for security.

PASSWORD

|S|

PORT SMTPSERVER

|I| |S|

<25> is the TCP PORT number. The typical SMTP server uses PORT number 25. Name of the send-mail server. An example might be: smtp.sbcglobal.yahoo.com

112 Cube Voyager Reference Guide

Pilot Program Control statements

SENDMAIL keywords (continued)

Keyword SUBJECT TO |S| |S| Description Subject of e-mail. 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.

Example

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='[email protected]',

Cube Voyager Reference Guide 113

Pilot Program Control statements

TO='[email protected],[email protected]', CC='The Boss<[email protected]>', 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='[email protected]', TO='[email protected]', 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='[email protected]', TO='[email protected]', 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

114 Cube Voyager Reference Guide

Pilot Program Examples

Examples
This section contains examples using the Pilot program: Pilot example 1 Pilot example 2 Pilot example 3

Pilot example 1
/* 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 example 2
/* Example 2: 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

Cube Voyager Reference Guide 115

Pilot Program Examples

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 example 3
/* Example 3: more capabilities. */ 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

116 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 117

Fratar

Fratar

This chapter discusses Fratar distribution, a process for modifying a matrix values. Topics include: Using Fratar Control statements Examples

118 Cube Voyager Reference Guide

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

Cube Voyager Reference Guide 119

Fratar Using Fratar

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

120 Cube Voyager Reference Guide

Fratar Using Fratar

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.
Example 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.
Example 3
SETPA MW[1]=... INCLUDE=1-500 ; will compute only the I=1-500 to J=1-500 portion of the matrix.

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

Cube Voyager Reference Guide 121

Fratar Using Fratar

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:
Value P A PA Description The P totals control; all values in the A array will be factored so that the A totals will match the P totals. The A totals control; all values in the P array will be factored so that the P totals will match the A totals. 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.
Value PL AL PAL Description 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. 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. 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, 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

122 Cube Voyager Reference Guide

Fratar Using Fratar

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

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:
After Iteration 1: RMSE = 22.87
Zone 1 2 3 Total Target 1 57 64 102 223 240 2 24 106 61 191 200 3 19 30 137 186 160 Total 100 200 300 600 600

Cube Voyager Reference Guide 123

Fratar Using Fratar

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:
After Iteration 2: RMSE = 7.94
Zone 1 2 3 Total 1 61 69 110 240 2 25 111 64 200 3 16 26 118 160 Total 102 206 292 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).
After Iteration 5: RMSE = 0
Zone 1 2 3 Total 1 60 70 113 240 2 25 190 64 200 3 16 26 118 160 Total 102 206 292 600

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

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

124 Cube Voyager Reference Guide

Fratar Using Fratar

are initialized with the final matrices from the Fratar distribution. After the factoring process is complete, a standard Matrix program I-loop is performed.

Cube Voyager Reference Guide 125

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

PARAMETERS
Sets general parameters. MATOEVERY MAXITERS MAXPURPS MAXRMSE ZONES

126 Cube Voyager Reference Guide

Fratar Control statements

In addition to the standard Matrix parameters (see PARAMETERS on page 539), you may specify the parameters described here.
PARAMETERS keywords
Parameter MATOEVERY |K?| Description 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.

Cube Voyager Reference Guide 127

Fratar Control statements

PARAMETERS keywords (continued)

Parameter MAXPURPS |KI| Description Number of purposes to process in this application. The keyword 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. 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.

MAXRMSE

|KR|

REPORT
PCOMP ACOMP In addition to the REPORT keywords available for Matrix, the following are also available for Fratar:
REPORT keywords
Keyword ACOMP |KIP| Description 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. Same as ACOMP, but refers to productions, and refers to only even iterations.

PCOMP

|KIP|

128 Cube Voyager Reference Guide

Fratar Control statements

Example
ACOMP=1-3,5 ;request reports for the specified purposes

SETPA
Establishes base productions and attractions. P A PGF AGF MW CONTROL INCLUDE EXCLUDE 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. 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

Cube Voyager Reference Guide 129

Fratar Control statements

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).
SETPA keywords
Keyword A AGF |NV| |NV| Description Expression solved to set the target attraction totals for the indexed purpose. 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. String indicating how to adjust final target totals to enable convergence. The possible values are: P A PA PL Production totals control; As will be adjusted Attraction totals control; Ps will be adjusted Both Ps and As will be adjusted to the average of the P and A totals. Same as P, but only As in adjustable zones will be adjusted

CONTROL

|SV*|

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 47). If it is used, the loop will not be processed for any zones in the list. EXCLUDE filtering follows any INCLUDE filtering. Processed the same as INCLUDE on COMP statements (see COMP on page 47). If it is used, the loop will not be processed for any zones not in the list. INCLUDE filtering precedes any EXCLUDE zones.

INCLUDE

|IP|

130 Cube Voyager Reference Guide

Fratar Control statements

SETPA keywords (continued)

Keyword MW |NV| Description 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. Expression solved to set the target production totals for the indexed purpose. Expression solved to set the target production growth factors for the indexed purpose.

P PGF

|NV| |NV|

Example

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) A1=(ZI.1.A1) MW1=1 CONTROL[1]=A SETPA P[2]=(ZI.1.P1) A2=(ZI.1.A1) MW2=1 CONTROL[2]=P SETPA P[3]=(ZI.1.P1) A3=(ZI.1.A1) MW3=1 CONTROL[3]=PA

Cube Voyager Reference Guide 131

Fratar Examples

Examples
/* The following two steps (MATRIX and FRATAR) setup and run the small example used in the Introduction 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

132 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 133

Highway Program

Highway Program

This chapter discusses the Highway program. Topics include: Using the Highway program Phases Control statements Theory Examples

The junction file is part of the Highway program. For information about the junction file, see Chapter 7, Intersection Modeling.

134 Cube Voyager Reference Guide

Highway Program Using the Highway program

Using the Highway program

This section provides helpful information about using Cube Voyagers Highway program. Topics include: Highway introduction Highway program control statement overview Functions and built-ins Getting started with assignment Path-based tolls

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 201 and PATHLOAD on page 230; also refer to Highway path display on page 297 of the Cube Base Reference Guide for information about path-based analysis in Cube. The Highway programs 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

Cube Voyager Reference Guide 135

Highway Program Using the Highway program

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

136 Cube Voyager Reference Guide

Highway Program Using the Highway program

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: SETUP Optionally, initialize basic user arrays and processes LINKREAD 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

Cube Voyager Reference Guide 137

Highway Program Using the Highway program

CONVERGE Optional phase where user can specify their own convergence rules and 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 155.

Highway program control statement overview

There are several types of control statements in the Highway program:
Definition statements Define static processes. Examples

include: FILEI and FILEO which define the input and output data FUNCTION LOOKUP PARAMETERS
Computational statements Update variable values. Examples

include: COMP PATHLOAD SET

Reporting statements Accumulate or dynamically display

values. Examples include:

138 Cube Voyager Reference Guide

Highway Program Using the Highway program

PRINT PRINTROW REPORT

Flow control statements Set statement order. Examples

include: GOTO :label LOOP BREAK CONTINUE ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For details about control statements, see Control statements on page 179.

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: The names 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 211.

Cube Voyager Reference Guide 139

Highway Program Using the Highway program

Built-in variables
Only the variables with a * may be stored into by the user; the others are reserved.
Variable _SKIPTOI Description 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 146. Capacity used in congestion expressions; Link distance expressed in miles or kilometers. Current rows zone (ILOOP). Current iteration number. Column index, usually 1, and varies (1-Zones) for MW[] and JLOOPs. Lambda value computed for this iteration; do not be reset. Last iteration indicator, usually set to the MAXITERS parameter Class of the current link; you can modify in LINKREAD. Link number (available during any implied link loops) Result of LOWEST(). Number of nodes. Number of links. Zero value means do not include in equilibrium; you can modify in LINKREAD. Link speed. Link free flow time. Initial iteration time. Total link volume used in ADJUST phase; by default, it is the sum of all VOL[] sets. Number of zones.

C* DISTANCE*

I
ITERATION

J
LAMBDA LASTITERATION LINKCLASS* LINKNO LOWCNT NODES NUMLINKS PROJECTLINK

SPEED*
T0* T1* V* ZONES

140 Cube Voyager Reference Guide

Highway Program Using the Highway program

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.
Array A B COST DIST* LI.name LW.name* MW[]* TIME* VOL[]* Description A-nodes for each link. B-nodes for each link. Link cost values. Link distances. Link values from the network. User generated values for links (currently accepts numeric values only). A work matrix; see COMP on page 182 for more details. Link times. Link volumes.

Built-in functions
These built-in functions are described in COMP on page 182.
Function ROWSUM(mw) ROWCNT(mw) ROWMIN(mw) ROWMAX(mw) ROWAVE(mw) ROWFIX(mw) ROWFAC(mw,fac) ROWADD(d,s1,,sn) ROWMPY(d,s) Description Row total. Number of cells whose values != 0. Minimum value in the row. Maximum value in the row. Average cell value where value!=0. Convert mw to integer values (start at column intrazonal + 1). Factors the row by fac. Add matrixes mw[1] + + mw[sn] into mw[d]. Multiply mw[d] by mw[s].

Cube Voyager Reference Guide 141

Highway Program Using the Highway program

Function ROWDIV(d,s) LOWEST(mw,#) LOWCNT SPEEDFOR(lanes,class) CAPACITYFOR(lanes,class) PATHTRACE(value) LINKNUM(a,b)

Description Divide mw[d] by mw[s]. Sum of lowest valued cells in a matrix row. Actual number of cells found by LOWEST function. Speed from spdtab. Capacity from captab. Sum of link values (Time, Cost, LI. or LW.) on path for I to J. Link number for link a-b.

Built-in variables available in the CONVERGE phase

There are various variables available for testing in the CONVERGE phase. See CONVERGE phase on page 171 for examples of usage.
Converge phase variables
Variable GAP RGAP AAD RAAD PDIFF RMSE BALANCE GAPCUTOFF* RGAPCUTOFF* AADCUTOFF* Description The GAP for the current iteration. Must be indexed GAP[] for previous iterations. The RELATIVEGAP for the current iteration. Must be indexed for previous iterations. The AAD for the current iteration. Must be indexed for previous iterations. The RAAD for the current iteration. Must be indexed for previous iterations. The PDIFF for the current iteration. Must be indexed for previous iterations. The RMSE for the current iteration. Must be indexed for previous iterations. Initialized to 0 and set to 1 when convergence criteria have been met. Initialized to the value PARAMETERS GAP; may be reset anytime. Initialized to the value PARAMETERS RELATIVEGAP; may be reset anytime. Initialized to the value PARAMETERS AAD; may be reset anytime

142 Cube Voyager Reference Guide

Highway Program Using the Highway program

Converge phase variables (continued)

Variable RAADCUTOFF* PDIFFCUTOFF* RMSECUTOFF* Description Initialized to the value PARAMETERS RAAD; may be reset anytime Initialized to the value PARAMETERS PDIFF; may be reset anytime Initialized to the value PARAMETERS RMSE; may be reset anytime.

Built-in functions available in the CONVERGE phase

There are various functions available that return a value for testing in the CONVERGE Phase. See CONVERGE phase on page 171 for examples of usage.
Converge phase functions
Function GAPCHANGE RGAPCHANGE AADCHANGE RAADCHANGE PDIFFCHANGE RMSECHANGE GAPMIN GAPMAX GAPAVE Description Change in GAP between the specified iteration (the required argument) and the previous iteration. Change in RELATIVEGAP between the specified iteration (the required argument) and the previous iteration. Change in AAD between the specified iteration (the required argument) and the previous iteration. Change in RAAD between the specified iteration (the required argument) and the previous iteration. Change in PDIFF between the specified iteration (the required argument) and the previous iteration. Change in RMSE between the specified iteration (the required argument) and the previous iteration. Minimum GAP between the last n iterations, where n = the number of iterations to process. Maximum GAP between the last n iterations, where n = the number of iterations to process. Function that results in the average GAP between the last n iterations, where n = the number of iterations to process. Minimum change in GAP between the last n iterations, where n = the number of iterations to process.

GAPCHANGEMIN

Cube Voyager Reference Guide 143

Highway Program Using the Highway program

Converge phase functions (continued)

Function GAPCHANGEMAX GAPCHANGEAVE RGAPMIN RGAPMAX RGAPAVE RGAPCHANGEMIN RGAPCHANGEMAX RGAPCHANGEAVE AADMIN AADMAX AADAVE AADCHANGEMIN AADCHANGEMAX AADCHANGEAVE RAADMIN RAADMAX RAADAVE RAADCHANGEMIN Description Maximum change in GAP between the last n iterations, where n = the number of iterations to process. Average change in GAP between the last n iterations, where n = the number of iterations to process. Minimum RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Maximum RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Average RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Minimum change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Maximum change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Average change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Minimum AAD between the last n iterations, where n = the number of iterations to process. Maximum AAD between the last n iterations, where n = the number of iterations to process. Average AAD between the last n iterations, where n = the number of iterations to process. Minimum change in AAD between the last n iterations, where n = the number of iterations to process. Maximum change in AAD between the last n iterations, where n = the number of iterations to process. Average change in AAD between the last n iterations, where n = the number of iterations to process. Minimum RAAD between the last n iterations, where n = the number of iterations to process. Maximum RAAD between the last n iterations, where n = the number of iterations to process. Average RAAD between the last n iterations, where n = the number of iterations to process. Minimum change in RAAD between the last n iterations, where n = the number of iterations to process.

144 Cube Voyager Reference Guide

Highway Program Using the Highway program

Converge phase functions (continued)

Function RAADCHANGEMAX RAADCHANGEAVE PDIFFMIN PDIFFMAX PDIFFAVE PDIFFCHANGEMIN PDIFFCHANGEMAX PDIFFCHANGEAVE RMSEMIN RMSEMAX RMSEAVE RMSECHANGEMIN RMSECHANGEMAX RMSECHANGEAVE Description Maximum change in RAAD between the last n iterations, where n = the number of iterations to process. Average change in RAAD between the last n iterations, where n = the number of iterations to process. Minimum PDIFF between the last n iterations, where n = the number of iterations to process. Maximum PDIFF between the last n iterations, where n = the number of iterations to process. Average PDIFF between the last n iterations, where n = the number of iterations to process. Minimum change in PDIFF between the last n iterations, where n = the number of iterations to process. Maximum change in PDIFF between the last n iterations, where n = the number of iterations to process. Average change in PDIFF between the last n iterations, where n = the number of iterations to process. Minimum RMSE between the last n iterations, where n = the number of iterations to process. Maximum RMSE between the last n iterations, where n = the number of iterations to process. Average RMSE between the last n iterations, where n = the number of iterations to process. Minimum change in RMSE between the last n iterations, where n = the number of iterations to process. Maximum change in RMSE between the last n iterations, where n = the number of iterations to process. 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:

Cube Voyager Reference Guide 145

Highway Program Using the Highway program

Example of most simple assignment

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

Example of _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

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 assumes that cost is equal to time, unless the user specifies otherwise. In our examples

146 Cube Voyager Reference Guide

Highway Program Using the Highway program

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.
Variable T0 DISTANCE C Description Link free flow time Optional, but useful for certain statistics 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

Cube Voyager Reference Guide 147

Highway Program Using the Highway program

Separate trips on separate paths Assignment of trips to HOV facilities

Daily assignment
Now lets 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 (well assume that daily capacity is 10 times the hourly capacity). We can do this in one of several ways, but lets 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

Add select link loading

Back to base case, but 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 links 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. So, we merely 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].

148 Cube Voyager Reference Guide

Highway Program Using the Highway program

Add truck assignment on same paths

Base case plus assigning the trucks from the second matrix on MATI. 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

Add truck assignment on separate paths

Base case plus assign the trucks from the second matrix on MATI. 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

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

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

Cube Voyager Reference Guide 149

Highway Program Using the Highway program

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

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

150 Cube Voyager Reference Guide

Highway Program Using the Highway program

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

Network 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. Every on-gate must have a unique number (1-999). Every off-gate must have a unique number (1-999). 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 links 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: On-gate number Off-gate number 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: Toll on-ramps:

Cube Voyager Reference Guide 151

Highway Program Using the Highway program

Inbound link must be a non-toll-road link or a toll offlink. Outbound link must be a toll-road link or a toll off-link. 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 onlink. 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.
Inbound link must be Non-toll-road off-ramp Toll-road onramp Toll-road onramp Outbound link must be Toll-road offramp Non-toll-road on-ramp Toll-road offramp Inbound link may not be Toll-road onramp Non-toll road Non-toll-road off-ramp Outbound link may not be Non-toll-road on-ramp Toll-road offramp Non-toll-road on-ramp

Toll off-ramps:

Toll-road links:

Toll type On-ramp Off-ramp Toll road

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

152 Cube Voyager Reference Guide

Highway Program Using the Highway program

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 a record 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 onoff 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

Cube Voyager Reference Guide 153

Highway Program Using the Highway program

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 Highway example 8 on page 268.

154 Cube Voyager Reference Guide

Highway Program Phases

Phases
You code Highway-program control statements within different phases. The Highway program processes the phases in a specific order.
ITERATION = 0 For ITERATION = 1 to LASTITERATION LINKREAD phase ILOOP phase

SETUP phase

CONVERGE phase optional

LINKREAD phase Implicit (combine volumes)

ADJUST phase

This section provides more details about the different phases in the Highway program: SETUP phase LINKREAD phase ILOOP phase ADJUST phase CONVERGE phase

SETUP phase
After reading all control statements, the Highway program processes the SETUP phases control statementsthat is, its stack. The SETUP phase can only contain COMP and SET statements. The

Cube Voyager Reference Guide 155

Highway Program Phases

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.

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 141). 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. PRINT statements to list information about individual links.

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

156 Cube Voyager Reference Guide

Highway Program Phases

NOTE: The program processes the entire LINKREAD stack for each

link whenever reading a network links 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 links TIME, COST, and DIST values. There are several methods for setting these variables (see Setting TIME, COST, and DIST values on page 158).
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 230 for more details.) For example, you might build lowoccupancy 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 GROUPcoded links. See SETGROUP on page 253 for details.

Cube Voyager Reference Guide 157

Highway Program Phases

Setting TIME, 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): If set by LINKREAD stack, use that value. Else if there is a LI.DISTANCE, set DISTANCE = LI.DISTANCE. Else set DISTANCE = 0. If DISTANCE < 0, set DISTANCE = 0. LINKCLASS (essential for selecting appropriate Functions): If set by LINKREAD stack, use that value. Else if there is a LI.LINKCLASS, set LINKCLASS = LI.LINKCLASS. Else set LINKCLASS = 1. If LINKCLASS < 1, set LINKCLASS = 1. SPEED (possibly used to compute T0): If set by LINKREAD stack, use that value. Else if there is a LI.SPEED, set SPEED = LI.SPEED. 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). Else set SPEED = 0. C (capacity, used later in restraining process in the ADJUST phase): If set by LINKREAD stack, use that value. Else if there is a LI.CAPACITY, set C = LI.CAPACITY* CAPFAC. Else If there are valid LI.LANES and LI.CAPCLASS values (1-9 and 1-99), set C = CAPACITYFOR(LI.LANES,LI.CAPCLASS) * CAPFAC. Else set C = 0.

158 Cube Voyager Reference Guide

Highway Program Phases

If C < 0, set C = 0.
NOTE: The program treats a link capacity of 0 (zero) as

infinite capacity. T0 (free flow time): If set by LINKREAD stack, use that value. Else if there is a LI.T0, set T0=LI.T0. Else if there is a LI.TIME, set T0 = LI.TIME. Else if there is a LI.TIME1, set T0 = LI.TIME1. Else if SPEED > 0, set T0 = DISTANCE*60/SPEED. If T0 < 0, set T0 = 0. T1 (initial iteration time): If set by LINKREAD stack, use that value. Else set T1 = T0. TIME (a link-work variable, without the required LW. prefix, of T1 values): 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): 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): 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

Cube Voyager Reference Guide 159

Highway Program Phases

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.

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]). 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

Volume sets
A volume set is an array that accumulates assignments for each link. There may be up to twenty volume sets. Though the highest set number is 20, 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

160 Cube Voyager Reference Guide

Highway Program Phases

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.
Example 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.
Example 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.)
Example 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.

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.

Cube Voyager Reference Guide 161

Highway Program Phases

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.

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 MW[] 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 links volume set.
Example (simple code 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.
Example (most efficient)
IF (I=...) PATH=..., VOL[1]=MI.1.1, INCLUDEJ=...

Example (using SELECTLINK)

PATH=..., MW[1]=MI.1.ODTRIPS, SelectLink=(a=... && b=...), SelectLink=(a=... && b=...), VOL[1]=MI.1.1,

162 Cube Voyager Reference Guide

Highway Program Phases

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 VOL[] statement. Use IF statements to find the desired I, and use INCLUDEJ and EXCLUDEJ keywords to select the desired J values. Use SELECTLINK, specifying A=range of desired I values and B=range of desired J values.

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 SUBAREANETI Define the region. FILEO SUBAREAMATO Define where to save the selected trips. PATHLOAD SUBAREAMAT 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 paths J in the subarea matrix. This process can extract several types of records:
Potential extracted records
Record type X-X X-I I-X I-I Description Path begins and ends outside subarea, crossing the cordon line exactly two times. Path begins outside the subarea and ends inside the subarea. Path begins inside the subarea and end outside the subarea. Path begins and ends inside the subarea.

Cube Voyager Reference Guide 163

Highway Program Phases

When a path enters the subarea by crossing a cordon link, the Anode 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.
Example (subarea trip extraction)
PATHLOAD PATH=TIME, SUBAREAMAT[1]=MI.1.1, SUBAREAMAT[2]=1

ADJUST phase
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 links 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

164 Cube Voyager Reference Guide

Highway Program Phases

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 Functions and built-ins on page 139 for a description of the builtin functions, variables. and arrays the program uses.) 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. 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. 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 COMBINE to specify the method used: Equilibrium (the default)

Cube Voyager Reference Guide 165

Highway Program Phases

Average Weighted average Iterative Summation (often referred to as incremental)

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 iterations volume in the volume combining process, a factor (generally referred to as Lambda) is estimated for the iteration. Lambda is a factor between 0 and 1. 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 COMBINE LAMBDASEARCH = AREA/EQUATION. Note that both processes estimate Lambda so the results might be

166 Cube Voyager Reference Guide

Highway Program Phases

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 Vk-1) * T0(1 + TCCOEFF * ((Vk-1 + * (VOLk - Vk-1))/C) ^ TCEXP) where:
VOLk Vk-1 T0 = the summation over the links in the input network = the AON volume assigned in iteration k to COSTk-1 paths based on Vk-1 = the equilibrium weighted volume from the prior iteration = the free flow time

TCCOEFF = value of the TC functions coefficient term defined on the PARAMETERS statement C TCEXP = the link capacity = 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 new PARAMETERS TCCOEFF and TCEXP and requests the EQUATION search process then the program uses the following expression to solve for Lambda: Y() = (VOLk Vk-1) * TC(V,TCCOEFF,TCEXP)

Cube Voyager Reference Guide 167

Highway Program Phases

Where TC(V,TCCOEFF,TCEXP) is the TC functions evaluated for link volumes V, and the appropriate values of TCCOEFF and TCEXP, where V= Vk-1 + * (VOLk - Vk-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: Vk = * VOLk + (1- )*Vk-1. There are several iteration volume combination processes available; the PARAMETERS COMBINE= specifies the one to use. EQUI is the default. The available processes are:
Process EQUI AVE WTD ITE SUM Description Equilibrium assignment. Iteration volumes are factored by the equilibrium weights computed for each iteration. Average assignment simply keeps a running average of the volumes on each link. Weighted Average assignment is the same as Average, but the user can specify a specific weight for each iteration. Iterative assignment keeps only last iteration volumes are output; prior iteration volumes are not considered. 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.

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.

168 Cube Voyager Reference Guide

Highway Program Phases

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:
Keywords GAPk Description 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 RAAD Pdiff RMSE MAXITERS Average absolute volume difference: based upon successive iterations Relative AAD: DiffV/V Percent of links whose change in V between iterations is less than a set value. Root mean squared error of the differences in V between iterations. 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): Obtain link values (as in LINKREAD and LINKREAD stack, except TIME is not altered). If Iteration > 1, obtain prior combined iteration volumes (CVOL is prior V). Apply the appropriate TC and Cost Functions (based on LinkClass) to compute revised Time and Cost.

Cube Voyager Reference Guide 169

Highway Program Phases

If this is an Equilibrium pass, compute link contribution (Y) to Lambda estimations. Else if Iteration > 1, combine V with prior combined Vs Process LinkAdjust stack (if present), and recompute Cost. End Major Link Loop. Determine if this is to be the last iteration: 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 RGAP AAD RAAD PDIFF RMSE < MinGap < MinRGAP < MinAAD < MinRAAD > MaxPdiff < 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:

170 Cube Voyager Reference Guide

Highway Program Phases

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.

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.

Cube Voyager Reference Guide 171

Highway Program Phases

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 RAAD Pdiff RMSE

Average absolute volume difference: based upon successive iterations Relative AAD: DiffVE/VE Percent of links whose change in VE between iterations is less than a set value. 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.

172 Cube Voyager Reference Guide

Highway Program Phases

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.
Variables available for BALANCE
Variable GAP RGAP AAD RAAD PDIFF RMSE Description The GAP for the current iteration, Must be indexed GAP[] for previous iterations The RELATIVEGAP for the current iteration, Must be indexed for previous iterations The AAD for the current iteration, Must be indexed for previous iterations The RAAD for the current iteration, Must be indexed for previous iterations The PDIFF for the current iteration, Must be indexed for previous iterations The RMSE for the current iteration, Must be indexed for previous iterations A variable initialized to the value Parameters GAP, may be reset anytime A variable initialized to the value Parameters RELATIVEGAP, may be reset anytime A variable initialized to the value Parameters AAD, may be reset anytime A variable initialized to the value Parameters RAAD, may be reset anytime A variable initialized to the value Parameters PDIFF, may be reset anytime A variable initialized to the value Parameters RMSE, may be reset anytime

GAPCUTOFF RGAPCUTOFF AADCUTOFF RAADCUTOFF PDIFFCUTOFF RMSECUTOFF

Cube Voyager Reference Guide 173

Highway Program Phases

Functions available for BALANCE

Function GAPCHANGE Description Function that results in change in GAP between the specified iteration (the required argument) and the previous iteration. Function that results in change in RELATIVEGAP between the specified iteration (the required argument) and the previous iteration. Function that results in change in AAD between the specified iteration (the required argument) and the previous iteration. Function that results in change in RAAD between the specified iteration (the required argument) and the previous iteration. Function that results in change in PDIFF between the specified iteration (the required argument) and the previous iteration. Function that results in change in RMSE between the specified iteration (the required argument) and the previous iteration. Function that results in the minimum GAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum GAP between the last n iterations, where n = the number of iterations to process. Function that results in the average GAP between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in GAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in GAP between the last n iterations, where n = the number of iterations to process. Function that results in the average change in GAP between the last n iterations, where n = the number of iterations to process.

RGAPCHANGE

AADCHANGE

RAADCHANGE

PDIFFCHANGE

RMSECHANGE

GAPMIN

GAPMAX

GAPAVE

GAPCHANGEMIN

GAPCHANGEMAX

GAPCHANGEAVE

174 Cube Voyager Reference Guide

Highway Program Phases

Functions available for BALANCE (continued)

Function RGAPMIN Description Function that results in the minimum RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the average RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the average change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the minimum AAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum AAD between the last n iterations, where n = the number of iterations to process. Function that results in the average AAD between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in AAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in AAD between the last n iterations, where n = the number of iterations to process. Function that results in the average change in AAD between the last n iterations, where n = the number of iterations to process.

RGAPMAX

RGAPAVE

RGAPCHANGEMIN

RGAPCHANGEMAX

RGAPCHANGEAVE

AADMIN

AADMAX

AADAVE

AADCHANGEMIN

AADCHANGEMAX

AADCHANGEAVE

Cube Voyager Reference Guide 175

Highway Program Phases

Functions available for BALANCE (continued)

Function RAADMIN Description Function that results in the minimum RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the average RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the average change in RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the minimum PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the maximum PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the average PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the average change in PDIFF between the last n iterations, where n = the number of iterations to process.

RAADMAX

RAADAVE

RAADCHANGEMIN

RAADCHANGEMAX

RAADCHANGEAVE

PDIFFMIN

PDIFFMAX

PDIFFAVE

PDIFFCHANGEMIN

PDIFFCHANGEMAX

PDIFFCHANGEAVE

176 Cube Voyager Reference Guide

Highway Program Phases

Functions available for BALANCE (continued)

Function RMSEMIN Description Function that results in the minimum RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the maximum RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the average RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the average change in RMSE between the last n iterations, where n = the number of iterations to process.

RMSEMAX

RMSEAVE

RMSECHANGEMIN

RMSECHANGEMAX

RMSECHANGEAVE

Example
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

Example
; 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 &

Cube Voyager Reference Guide 177

Highway Program Phases

RAAD<RAADCUTOFF & RMSE<RMSECUTOFF & PDIFF<PDIFFCUTOFF) BALANCE = 1 ENDIF ENDPHASE

178 Cube Voyager Reference Guide

Highway Program Control statements

Control statements
The following control statements are available in the Highway program.
Control statement ABORT ARRAY BREAK COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FUNCTION GOTO IF ... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LINKLOOP ... ENDLINKLOOP LOOKUP LOOP ... ENDLOOP PARAMETERS PATHLOAD PRINT PRINTROW PROCESS ... ENDPROCESS REPORT SET SETGROUP Description Quit current program Set user arrays Break out of current process Compute variables from expressions Go to end of current loop Terminate current phase Input files Output files Set path for temporary files Fill work matrices Define Volume, TimeAdjustment, and Cost functions Jump immediately to :label statement Define IF ENDIF block Define a loop for destination zones (J) Control a link loop for processing link records in the ILOOP phase Define lookup tables (see Chapter 3, General Syntax) Define a user controlled loop Set static parameters Build path, load path, compute selected link matrices Print variable values Print a row of a matrix Set process (phase) blocks Set standard reports Set multiple variables/arrays to same value Set link group codes

Cube Voyager Reference Guide 179

Highway Program Control statements

Control statement SORT SPDCAP TURNS

Description Sort user arrays Set Speed and Capacity table values Designate intersections where turn volumes are to be accumulated

ABORT
Aborts the entire run. MSG 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.
ABORT keyword
Keyword Description |S| Optional message that can be printed when the program terminates.

MSG Example

IF (MW[1][I] != 0) ABORT ;Intrazonal present in MW[1]

ARRAY
Declares user single dimension arrays. 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 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

180 Cube Voyager Reference Guide

Highway Program Control statements

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.
ARRAY keyword
Keyword Description |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).

VAR

Example
ARRAY sum_toll=20 sum_toll[NI.CLASS] = sum_toll[NI.CLASS] + VOLTOT ARRAY VMT=LINKS

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.
Example
LOOP L1=1,3 IF (condition) statements ELSE BREAK ENDIF

; jump to IF statement

Cube Voyager Reference Guide 181

Highway Program Control statements

ENDLOOP IF (condition) BREAK ; no more processing for this origin zone

COMP
Computes a variable, matrix, or matrix element from an expression.
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 keywords
Keyword MW Subkeyword |KN| Description Value for a working matrix. You can specify this keyword in two formats: MW[n] Defines the value for row n of a working matrix. Matrices can contain up to MAXMW rows, 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 loops current J. MW[n][c] Defines the value for column c in row n. The second index, c, must be between one and Zones. The program solves the expression one time only, with J being the loops J if within a JLOOP, or 1, if not.

182 Cube Voyager Reference Guide

Highway Program Control statements

COMP keywords (continued)

Keyword Subkeyword EXCLUDE |IP| Description 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. INCLUDE |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.

Cube Voyager Reference Guide 183

Highway Program Control statements

COMP keywords (continued)

Keyword VAR Subkeyword |KN| Description 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 -- dont mix jkl = 1 jkl = xyz xyz = 'xyz' ; jkl is declared numeric ; invalid: xyz is declared a string (later) ; 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.
Special matrix variables MW[] MI.n.name MI.n.matnum

184 Cube Voyager Reference Guide

Highway Program Control statements

The expression is a standard Cube Voyager numeric expression, but there are some special variables that may be used within it:
Matrix variables
Variable MW[Rexpression] Description 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. 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.name

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

ZI.n.name

Special matrix functions

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(#).

Cube Voyager Reference Guide 185

Highway Program Control statements

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.
Matrix functions
Function LOWCNT Description 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). Sum of lowest n cells. Sum of lowest n cells, including only cells with values greater than or equal to lo, and less than or equal to hi. 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.

LOWEST(mw,n) LOWEST(mw,n,lo,hi) LOWEST(mw,n,lo,hi,z,z,... )

186 Cube Voyager Reference Guide

Highway Program Control statements

Matrix functions (continued)

Function ROWADD(d,s1...sn) Description Add matrix mw[1] + mw[sn] into mw[d] Same as:
MW[d] = MW[s1] + MW[s2] + MW[sn]

ROWAVE(mw) ROWAVE(mw,lo,hi) ROWCNT(mw) ROWCNT(mw,lo,hi) ROWDIV(d,s)

Average cell value, including only cells with values not equal to 0. Average cell value, but include only cells with values greater than or equal to lo, and less than or equal to hi. Number of cells with values not equal to 0 Number of cells with values greater than or equal to lo, and less than or equal to hi; can include 0. 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) ROWFIX(mw) ROWFIX(mw,n) ROWFIX(mw,n,rnd)

Factors the row by fac. Same as MW[mw] = MW[mw] * fac Convert mw to integer values (start at column intrazonal + 1, with rounding factor = 0). Convert mw to integer values (start at column n, with rounding factor = 0). Convert mw to integer values (start at column n, using specified rounding factor).

Cube Voyager Reference Guide 187

Highway Program Control statements

Matrix functions (continued)

Function Description 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) ROWMIN(mw) ROWMPY(d,s) Maximum value in the row. Minimum value in the row. Multiply MW[d] by MW[s] Same as:
MW[d] = MW[d] * MW[s]

ROWSUM(mw) ROWSUM(mw,lo,hi)

Row total. Row total, but include only cells with values greater than or equal to lo, and less than or equal to hi.

Example 1
MW[mw][I] = LOWEST(mw,4,0.01,5,I)/max(1,LOWCNT)/2

Example 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

188 Cube Voyager Reference Guide

Highway Program Control statements

; 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

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

EXIT
Terminates stack processing. When the program encounters an EXIT statement, the program goes to the end of I-loop processing.
Example
IF (expression) EXIT

FILEI
NOTE: See FILEI on page 48 for general information about FILEI

and for important limitations when using Application Manager.

Cube Voyager Reference Guide 189

Highway Program Control statements

Input data files MATI NETI SUBAREANETI TURNPENI (MISSINGLINK LIST) ZDATI (Z SELECT NAME (DEFAULT) AVE AVEX0 CNT FIRST LAST MAX MIN SUM) JUNCTIONI (PERIOD N SET) LOOKUPI TOLLMATI (ENTRYGATE EXITGATE TOLLS NETIENTRY NETIEXIT NETITOLLROAD TOLLFACTOR TOLLROUND) 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.

190 Cube Voyager Reference Guide

Highway Program Control statements

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 (users choice, it doesnt 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 -------11 23 15 1 12 13 15 58 36 set # -----1 3 8 turnpen ---------1 2 FUNC1(500)

(Prohibitor) (Constant) (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 users responsibility to make sure that the penalty values are in the proper scale and units as the paths to which they are being applied.

Cube Voyager Reference Guide 191

Highway Program Control statements

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.

192 Cube Voyager Reference Guide

Highway Program Control statements

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

Cube Voyager Reference Guide 193

Highway Program Control statements

be applied with higher or lower priority (that is, set number) than the calculated delays.
FILEI keywords
Keyword JUNCTIONI Subkeyword |KF| Description 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. Specifies the nodes where intersection modeling is to be invoked. A junction model 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. Duration of the model period in minutes. The input demand matrix should be in units of vehicles (or PCU) per model period. Specifies which turn penalty set will contain the delays calculated by the junction models 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 NETI |KFV20| |KF| Specifies the input matrix files. The files must be Cube Voyager, TP+, MINUTP, or Tranplan binary matrices. 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 file. If specifying a Cube geodatabase network stored in an MDB file, 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.

JUNCTIONI

|IP|

JUNCTIONI

PERIOD

|R|

JUNCTIONI LOOKUPI

SET

|I| |FKV999|

194 Cube Voyager Reference Guide

Highway Program Control statements

FILEI keywords (continued)

Keyword SUBAREANETI Subkeyword |KF| Description 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 160 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 151. 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.

Cube Voyager Reference Guide 195

Highway Program Control statements

FILEI keywords (continued)

Keyword TOLLMATI Subkeyword EXITGATE |S| Description 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. 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. 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. 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. 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

NETIENTRY

|S|

TOLLMATI

NETIEXIT

|S|

TOLLMATI

NETITOLLROAD

|S|

TOLLMATI

TOLLFACTOR

|R10|

196 Cube Voyager Reference Guide

Highway Program Control statements

FILEI keywords (continued)

Keyword TOLLMATI Subkeyword TOLLROUND |R| Description 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). 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. Specifies the input file that contains the turn penalty functions and movement records. Switch to designate if the penalty values are to be listed to the print file. 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

TOLLMATI

TOLLS

|S10|

TURNPENI TURNPENI TURNPENI LIST MISSINGLINK

|KF| |?| |I|

Cube Voyager Reference Guide 197

Highway Program Control statements

FILEI keywords (continued)

Keyword ZDATI Subkeyword |KFV10| Description 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 ZDATI AVE1 AVEX01 |SV| |SV| Average of all records. Average of all records, where the value from the file records is not 0.

198 Cube Voyager Reference Guide

Highway Program Control statements

FILEI keywords (continued)

Keyword ZDATI ZDATI Subkeyword CNT1 DEFAULT |SV| |R| Description Count of the records that contain the variable. 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. Directly from the record from the FILEI with the lowest index[]. Directly from the record from the FILEI with the highest index []. Maximum value of all the records. Minimum value from all the records. 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 doesnt 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 ZDATI ZDATI ZDATI ZDATI

FIRST1 LAST1 MAX1 MIN1 NAME

|SV| |SV| |SV| |SV| |S|

Cube Voyager Reference Guide 199

Highway Program Control statements

FILEI keywords (continued)

Keyword ZDATI Subkeyword SELECT |S3| Description 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. Sum of all the records. 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).

ZDATI ZDATI

SUM1 Z

|SV| |S|

1. Indicates a process to use in obtaining the value for the variables that are listed following the keyword. 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.

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.
Example
NETI=network.net ; TPP binary network file MATI=test11.dat, test12.dat ; MINUTP binary matrix files

200 Cube Voyager Reference Guide

Highway Program Control statements

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

FILEO
Specifies files that the Highway program outputs. ESTMDATO NAME ESTMICPO (CONFVAR COUNTVAR DEFAULTCONF SCREENLINE VAR) JUNCTIONO MATO (FORMAT MO NAME DEC COMBINE) NETO (INCLUDE EXCLUDE APPEND DEC) PATHO (COSTDEC ITERS) PRINTO (APPEND) SUBAREAMATO (FORMAT DEC NAME) TURNPENO TURNVOLO (FORMAT (DELIMITER) DEC INCLUDE0 VARS NAMES) 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

Cube Voyager Reference Guide 201

Highway Program Control statements

(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 (twoway) 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. 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.
FILEO keywords
Keyword ESTMDATO ESTMDATO NAME Subkeyword |F| |SV| Description Specifies the file name for the output screenline data file (*.DAT) that is required by Cube Analyst. 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. Specifies the file name for the output intercept file (*.ICP) that is required by Cube Analyst. Specifies the link array that contains the count confidence values. The value may be an lw.array or li.array. 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 specify VAR.

ESTMICPO ESTMICPO ESTMICPO CONFVAR COUNTVAR

|F| |S20| |S20|

202 Cube Voyager Reference Guide

Highway Program Control statements

FILEO keywords (continued)

Keyword ESTMICPO ESTMICPO Subkeyword DEFAULTCON F SCREENLINE |I| |S20| Description Default confidence value applied if CONFVAR is not set or contains an illegal value (<=0). Valid range is 1 to 10,000. 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. 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 MATO MATO COMBINE |F| |FV20| |?| Specifies the file name where the results of junction modeling may be stored for display. Specifies the filename for the MATO specified. Specifies that ALL the matrices on this file are to be combined in a manner consistent with the method of volume combination as specified with PARAMETERS_COMBINE. The most common application would be with selected link matrices.

ESTMICPO

VAR

|S20|

Cube Voyager Reference Guide 203

Highway Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword DEC |SV*| Description Specifies the format for the MOs. There is a separate DEC for each MO. The value can be a number (0-9) or the character D or S. A number value indicates the output matrix cells are to be integerized with that many decimal places preserved. The letter D indicates that the cells are to be stored in double precision floating point format, while S indicates single precision floating point. 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. 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. 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.

MATO

FORMAT

|S|

MATO

NAME

|SV|

204 Cube Voyager Reference Guide

Highway Program Control statements

FILEO keywords (continued)

Keyword NETO Subkeyword |F| Description 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 by designating the file name followed by a backslash and the Cube geodatabase network name. 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. Specifies the number of decimal places to written to the NETO Volume fields. Values in the range 1-5 are valid. 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. 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. Specifies the name of a file upon which paths from a PATHLOAD statement are to be written. 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.

NETO

APPEND

|I|

NETO NETO

DEC EXCLUDE

|I| |S20|

NETO

INCLUDE

|S20|

PATHO PATHO COSTDEC

|F10| |I|

Cube Voyager Reference Guide 205

Highway Program Control statements

FILEO keywords (continued)

Keyword PATHO Subkeyword ITERS |I| Description Indicates which iterations to write the PATHO file. Possible values are: PRINTO |KF| 0 All iterations 1 First iteration only 2 Last iteration only 3 First and last iteration only

Default is 0. Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=# See APPEND under PRINT on page 66. 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. 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 doubleprecision 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. 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. Specifies the individual names for the SUBAREAMATO matrices. This keyword is ignored if the format is not TPP.

PRINTO SUBAREAMATO

APPEND

|?| |KF|

SUBAREAMATO

DEC

|SV20|

SUBAREAMATO

FORMAT

|C|

SUBAREAMATO

NAME

|SV20|

206 Cube Voyager Reference Guide

Highway Program Control statements

FILEO keywords (continued)

Keyword TURNPENO Subkeyword |F| Description 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 2635 2635 2635 2635 2621 2621 2621 2621 2621 2773 2606 2615 2615 2773 1 1 1 2 1 0.08 ;junct 0.15 ;junct 0.15 ;junct -1.00 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 210. Specifies the number of decimal places to preserve when the file is either DBF of TXT. 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 TURNVOLO

DEC DELIMITER

|I| |c|

Cube Voyager Reference Guide 207

Highway Program Control statements

FILEO keywords (continued)

Keyword TURNVOLO Subkeyword FORMAT |S| Description 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: 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: 2: 1 always on for T0 1 if T[1] in the data records, 0 if not in data record 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 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-201st T (T1) 21-282nd 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.

208 Cube Voyager Reference Guide

Highway Program Control statements

FILEO keywords (continued)

Keyword TURNVOLO Subkeyword FORMAT (continued) Description TXT ASCII format either in fixed format or delimited. There is no header for this file; the structure of each record is: 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. 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. 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 T2Tn, 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.

TURNVOLO

NAMES

|S25|

TURNVOLO

VARS

|S25|

PATHLOAD must have the keyword ESTMO=T specified in order for

the trips assigned from that statement to be included in the matrix estimation. There may be more than one PATHLOAD statement with ESTMO=T on it. It does not make sense to have ESTMO=T on a

Cube Voyager Reference Guide 209

Highway Program Control statements

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

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

Example
/* 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

FILET
Specifies where the Highway program writes various temporary files.

210 Cube Voyager Reference Guide

Highway Program Control statements

PATH
FILET keyword
Keyword Description |S| Specifies the path to the disk area where any temporary files are to be written.

PATH

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.

Example
PATH=' ' PATH=..\ PATH=c:\ ; use current directory ; up a directory ; root of c:

FILLMW
Fills work matrices. See FILLMW on page 531 for a complete description.

FUNCTION
Defines special functions. V TC COST 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

Cube Voyager Reference Guide 211

Highway Program Control statements

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.
FUNCTION keywords
Keyword COST |NV999| Description 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. 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.

TC

|NV999|

212 Cube Voyager Reference Guide

Highway Program Control statements

FUNCTION keywords (continued)

Keyword V |N| Description 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.

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

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. Example
GOTO buildhwy GOTO :buildhwy

Cube Voyager Reference Guide 213

Highway Program Control statements

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

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

Example
IF (LI.DIST< 20) LIST=a,b,LI.dist; single IF with process

214 Cube Voyager Reference Guide

Highway Program Control statements

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

JLOOP ... ENDJLOOP

Controls a loop through the columns of a matrix row. 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. JLOOP keywords
Keyword J |I| Description 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 loops 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 loops control variable, J. Valid values range from 1 to the networks maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1. Jinc defines the increment for the loops 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. 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.

Cube Voyager Reference Guide 215

Highway Program Control statements

JLOOP keywords (continued)

Keyword EXCLUDE |I| Description 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.

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: If J is specified, establish values for Jend and Jinc, else set J=1, Jend=Zones, Jinc=1. If (J < 1 or J > Zones or Jend <1 or Jend > Zones), terminate fatally. If (statement contains INCLUDE keyword and J is not listed among INCLUDE keyword values) go to ENDJLOOP. If (statement contains EXCLUDE keyword and J is among listed EXCLUDE keyword values) go to ENDJLOOP. Process statements within JLOOP. At ENDJLOOP: Add Jinc to J. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. 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

216 Cube Voyager Reference Guide

Highway Program Control statements

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. Example
;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

LINKLOOP ... ENDLINKLOOP

Controls a link loop for processing link records in the ILOOP phase. You can nest LINKLOOP blocks, but you cannot overlap them with IF blocks. 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.
Example
; double LW.VAR for even number zones

Cube Voyager Reference Guide 217

Highway Program Control statements

IF (I%2==0) LINKLOOP LW.VAR=LW.VAR*2 ; no [LINKNO] subscript needed ENDLINKLOOP ENDIF

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 LOOPENDLOOP 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: Initialize Lvar to Lbeg. Drop through to next statement.

218 Cube Voyager Reference Guide

Highway Program Control statements

At ENDLOOP: If Lend not specified, jump to next statement. Compute Lend. If Linc not specified, set Linc to 1 or 1(if Lbeg and Lend are constants, and Lbeg > Lend), otherwise compute Linc. Add Linc to Lvar. Compare Lvar to Lend. If (Linc > 0 and Lvar > Lend) jump to statement after
ENDLOOP

If (Linc > 0 and Lvar <= Lend) jump to statement after LOOP If (Linc < 0 and Lvar < Lend) jump to statement after
ENDLOOP

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).
Example
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

Cube Voyager Reference Guide 219

Highway Program Control statements

PARAMETERS
Sets general parameters. AAD CAPFAC COMBINE (WEIGHTS FRACTIONS LAMBDASEARCH) CONSOLIDATE EQUITURNCOSTFAC GAP MATOADJUST MAXITERS MAXMW MAXSTRING MODELPERIOD PDIFF PDIFFVALUE RAAD RELATIVEGAP RMSE TCCOEFF TCEXP TURNCOSTFAC TURNGAPWT ZONEMSG ZONES
PARAMETERS keywords
Keyword AAD1 Subkeyword |KR| Description Specifies the cutoff point based upon the average absolute difference in volumes between two iterations. Default value is 0.5.

220 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword CAPFAC Subkeyword |KR| Description 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 156 for details on how Cube Voyager obtains capacity from input network.) Default value is 1.

Cube Voyager Reference Guide 221

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword COMBINE Subkeyword |KS| Description Specifies the method to combine the results of iteration volumes. Default value is EQUI. Possible values include: 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 * Lambda + CVOL * (1-Lambda) This method is an implementation of the Frank-Wolfe algorithm ("An algorithm for quadratic programming", Naval Research Logistics Quarterly, 3 (1956), pp. 95-110). With this method, there are several options that can be specified by the subkeyword LAMBDASEARCH (seeLAMBDASEARCH on page 225). 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.

222 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword COMBINE (continued) Subkeyword Description New in 5.1 is support for additional assignment algorithms for COMBINE=EQUI mode. To access these, include the ENHANCE keyword immediately after the COMBINE=EQUI statement. The values for this keyword are: 0 Normal Frank-Wolfe algorithm (default) 1 Conjugate Frank-Wolfe algorithm 2 Bi-conjugate Frank-Wolfe algorithm AVE WTD Average all the iteration loadings. Weighted average. MAXITERS will be set according to the number of weights specified in WEIGHTS. This is similar to AVE, but the required weights are used to favor specific iterations. Only the last iteration volumes are used for output to NETO. 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.

ITER SUM

Cube Voyager Reference Guide 223

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword COMBINE (continued) Subkeyword Description

Stochastic Assignment
PROBIT BURRELL New in 5.1 is built-in support for stochastic assignment algorithms. The parameter keywords to implement a stochastic assignment are: COMBINE=t, STOCHASTICSEED=n, LINKRANDSERIES=s The associated PATHLOAD statement stochastic assignment support keywords are: PATHLOAD PATH=x, SPREADPERC=n, SPREADPERCVAR=var, SPREADMAX=n

Path-based Assignment
PATH New in 5.1 is support for path based assignment 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 VARIABLEDEMAD and ALLJ can be included immediately 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 if VARIABLEDEMAND=T. If AllJ is true, all destinations (J) are processed even if the demand is zero. 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.

224 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword Subkeyword LINKRANDSERIES |?| Description Switch to decide whether the random number generator will bind to the network or not. Only valid for COMBINE=BURRELL or PROBIT. 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. 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. Estimates lambda by solving an expression based on the TC functions.

FRACTIONS

|RV*|

COMBINE

LAMBDASEARCH

|S|

EQUATION

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 164. COMBINE WEIGHTS |RV*| Specifies the weights to be used when COMBINE is set to WTD. The number of weights sets the value for MAXITERS. 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.

CONSOLIDATE

|I|

Cube Voyager Reference Guide 225

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword EQUITURNCOSTFAC Subkeyword |KR| Description 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. GAP1 |KR| Specifies the cutoff point based upon the relative difference in system cost (volume * cost) between two iterations. Default value is 0.005. Specifies how often MATO matrices are combined during assignment. Enter number of iterations to combine at once, using the same factors used to combine volumes. Default value is 5 (the matrices are combined every five iterations). 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. If disk space is scarce or you are not concerned about run times, Citilabs recommends setting this value to 1 (matrices will be combined after each iteration). Otherwise, Citilabs recommends using the default value. MAXITERS1 |KI| Specifies maximum number of assignment iterations to be performed. Default value is 20 if COMBINE=EQUI otherwise the default value is 1. 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. 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.

MATOADJUST

|KI|

MAXMW

|KI|

MAXSTRING

|KI|

226 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword MODELPERIOD Subkeyword |KR| Description Duration of the model period in minutes. The input demand matrix should be in units of vehicles (or PCU) per model period. This value is only used if junctions are being modelled, or in an AVENUE run. If no value is specified, a default of sixty minutes (one hour) will be used. 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. Specifies the value to be used with PDIFF. Default value is 0.0. Specifies the cutoff point based upon the relative average absolute difference in volumes between two iterations. Default value is 0.005. Specifies an alternative GAP measure as the cutoff point. Default value is 0.005. Specifies the cutoff point based upon the root mean squared error of the differences in volumes between two iterations. Default value is 0.1.

PDIFF1

|KR|

PDIFFVALUE1 RAAD1

|KR| |KR|

RELATIVEGAP1 RMSE1

|KR| |KR|

Cube Voyager Reference Guide 227

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword TCCOEFF Subkeyword |RV*| Description Represents the coefficient term in a LINKCLASSspecific 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.

228 Cube Voyager Reference Guide

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword TCEXP Subkeyword |RV*| Description Represents the exponential term in a LINKCLASSspecific 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. 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. 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). 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.

TURNCOSTFAC

|KR|

TURNGAPWT

|R|

Cube Voyager Reference Guide 229

Highway Program Control statements

PARAMETERS keywords (continued)

Keyword ZONES Subkeyword |KI| Description 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. 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.

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

PATHLOAD
Builds a path, generates related matrices, and loads path links. CONSOLIDATE ESTMO (ALLJ) EXCLUDEGROUP

230 Cube Voyager Reference Guide

Highway Program Control statements

EXCLUDEJ INCLUDEJ LINKIDARRAY (LINKIDCNTMW LINKIDMW LINKIDLASTUSE LINKID#MW) MW (NOACCESS SELECTLINK SELECTGROUP SELECTLINKGROUP) PATH (DEC) PATHO (ALLJ INCLUDECOST NAME PATHOGROUP (FULLPATH)) PENI PENIFACTOR SPREADPERC SPREADPERCVAR SPREADMAX SUBAREAMAT (MAXMSG) TOLLFACTOR TOLLMATI THRUNODE TRACE (PRINTO (REWIND PRINT) CSV CFORM FORM LIST) VOL (VALUENAME) 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

Cube Voyager Reference Guide 231

Highway Program Control statements

2. TRACE 3. LINKIDARRAY 4. MW Processed in the input order 5. VOL Loaded in input order PATHLOAD keywords
Keyword CONSOLIDATE Subkeyword |?| Description 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 225 for information on controlling the effective level of consolidation. ESTMO |?| Flag that specifies whether the assigned volumes on screenline links are to be trapped and output to the ICP file specified by FILEO ESTMICPO. Default value is F. 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 INCLUDEJ |IVP| |IVP| Specifies that the processes for the named keywords will exclude the specified destination zones. Specifies that the process for the named keywords will include only the specified destination zones

ESTMO

ALLJ

|?|

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.

232 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword LINKIDARRAY LINKIDARRAY LINKIDARRAY LINKIDARRAY LINKIDCNTMW LINKIDLASTUSE LINKIDMW Subkeyword |S| |I| |I| |IP| Description Specifies an array of link attributes; it must be either an LI.array or an LW.array. Specifies the MW[] in which to store the number of links in the list. Specifies the MW[] in which to store the information for the last link in the list. 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 links information will be stored in MW[10]; the second links information will be stored in MW[11]; the fifth links 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]].

Cube Voyager Reference Guide 233

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword MW[] Subkeyword |N| Description 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-tozone 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.

234 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword MW[] (continued) Subkeyword Description In some cases, a big number is 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. 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.

Cube Voyager Reference Guide 235

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword MW[] (continued) Subkeyword Description 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=20002001), 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. 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[]

SELECTGROUP

|s|

236 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword MW[] Subkeyword SELECTLINK |s| Description 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 B N L The A-node of a link; only useful to select links with a path begins at A. The B-node of a link; only useful to select links with a path ends at B. A node that must be used in the path. 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. 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.

Cube Voyager Reference Guide 237

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword MW[] Subkeyword SELECTLINK (continued) Description Sample path: 1-101-102-103-104-105-2 (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: false (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 102101: true (L=101-102* && L=104-105*) The path contains link (101102 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. 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)

238 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword PATH PATH DEC Subkeyword |KS| |S| Description Specifies the link value on which the paths are to be built. Valid values are: Cost, Time, Dist, LI.name, or LW.name. 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. 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). T/F flag used with PATHOGROUP to keep partial or full paths for the specified GROUP(s). 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

ALLJ

|?|

PATHO PATHO

FULLPATH INCLUDECOST

|?| |?|

Cube Voyager Reference Guide 239

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword PATHO Subkeyword NAME |S| Description 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. 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.

PATHO

PATHOGROUP

|IP|

240 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword PENIFACTOR Subkeyword |N| Description 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=). 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 path cost value (for PATH=x) will be selected from the +/- spread range value from the original path cost value (C) as follows:
Min(SPREADPERC/100 * sqrt(C), C, SPREADMAX)

SPREADPERC

|R|

SPREADPERCVAR

|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. Specifies the maximum spread value allowed for stochastic assignment (COMBINE=PROBIT|BURRELL). Default is unlimited. 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 160.

SPREADMAX

|R|

SUBAREAMAT

|N|

Cube Voyager Reference Guide 241

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword SUBAREAMAT Subkeyword MAXMSG |I2| Description 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 151. 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.

242 Cube Voyager Reference Guide

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword TRACE Subkeyword |S| Description Specifies if any paths from I 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, and Iteration, but any valid variable can be used. The TRACE expression is evaluated for J=1,Zones. Example:
PATHLOAD PATH=TIME TRACE=(I=1-10 & J=100150)

The selected path traces will be listed in the run print file. The TRACE keyword can now 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 247 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 245.

Cube Voyager Reference Guide 243

Highway Program Control statements

PATHLOAD keywords (continued)

Keyword VOL[] Subkeyword |N| Description 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-20; there may be up to 20 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. 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 links 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.

VOL[]

Valuename

|S|

244 Cube Voyager Reference Guide

Highway Program Control statements

TRACE example
RUN PGM=HIGHWAY FILEO PRINTO[1] = PATH.CSV FILEO PRINTO[2] = PATH_TRACE_RPT.DAT FILEI NETI = TEST.NET PHASE = LINKREAD FromNode=1500 ToNode=1875 lw.fac_dist=10*li.DISTANCE lw.flag1=1 ENDPHASE PROCESS PHASE=ILOOP if (I < FromNode) _skiptoI=FromNode ; speeds up process IF (I=FromNode) ; build paths for select I PATHLOAD PATH=li.TIME mw[1]=PATHTRACE(li.TIME), mw[2]=PATHTRACE(li.DISTANCE), TRACE=(I=FromNode & J=ToNode) PRINTO=2 PRINT=T F=6.0, LIST=I,J,A,B,li.TIME(8.3),_pathcost(8.3), li.DISTANCE(8.4),lw.flag1(3.0), lw.fac_dist(10.2) ;Print results to formatted file to check against TRACE JLOOP IF (J=ToNode) ; FROM, TO, TIME, DISTANCE PRINT CSV=T, PRINTO=1, LIST='FromNode','ToNode','TIME','DISTANCE' PRINT CSV=T, PRINTO=1, LIST=FromNode(5.0),ToNode(5.0),mw[1](10.2),mw[2](10.2) ENDIF ENDJLOOP EXIT ENDIF ENDPROCESS 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 Highway example 7 on page 267 for an example of using the LINKIDARRAY keyword and its subkeywords in a script.

Cube Voyager Reference Guide 245

Highway Program Control statements

PATHLOAD example
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).
Example
/* 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

246 Cube Voyager Reference Guide

Highway Program Control statements

; 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])

PRINT
Formats and prints a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT)

Cube Voyager Reference Guide 247

Highway Program Control statements

See PRINT on page 66 for details.

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

PRINTROW
Formats and prints row(s) of matrices. MW J TITLE FORM MAXPERLINE BASE1 See PRINTROW on page 73 for details.
Example
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

PROCESS ... ENDPROCESS

Establishes phase blocks. 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

248 Cube Voyager Reference Guide

Highway Program Control statements

PROCESS statement acts as the ENDPROCESS statement. If ENDPROCESS is used, it may be coded as either ENDPROCESS or ENDPHASE. PROCESS keywords
Keyword PHASE |KS| Description 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: ENDPHASE |K| SETUP LINKREAD ILOOP ADJUST

Defines the end of the user control statements for a stack.

Example
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

REPORT
Requests reports and establishes tracing. CAPACITY PENI

Cube Voyager Reference Guide 249

Highway Program Control statements

SPEED TRACE VDTSPD (VOL I J RANGE FILE) ZDAT (DEC)

REPORT keywords
Keyword CAPACITY PENI Subkeyword |?| |?| Description Switch that indicates if the capacity portion on the SPDCAP tables is to be reported. 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. Switch that indicates if the speed portion on the SPDCAP tables is to be reported. 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. 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. Specifies which origin zones are to be included in this report. If this keyword is not specified, all origin zones will be included. Specifies which destination zones are to be included in this report. If this keyword is not specified, all destination zones will be included.

SPEED TRACE

|?| |K?|

VDTSPD

|?|

VDTSPD

|IV|

VDTSPD

|IV|

250 Cube Voyager Reference Guide

Highway Program Control statements

REPORT keywords (continued)

Keyword VDTSPD Subkeyword FILE |F| Description 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. 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

VDTSPD

RANGE

|IP|

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

Cube Voyager Reference Guide 251

Highway Program Control statements

REPORT keywords (continued)

Keyword VDTSPD Subkeyword VOL |IP| Description Specifies which volume sets are to be included in this report. If this keyword is not specified, the program will report all volume sets. Switch that indicates if all the internal arrays obtained from FILEI ZDATI files are to be reported. Sets the maximum number of decimal places to be printed for any variable. This one value applies to all variables on all ZDATI statements.

ZDAT ZDAT DEC

|?| |I|

Example
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

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.
SET keywords
Keyword VAL |R| Description 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. 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.

VARS

|S|

252 Cube Voyager Reference Guide

Highway Program Control statements

Example
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

SETGROUP
Sets group codes for a link. ADDTOGROUP REMOVEFROMGROUP 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 users responsibility. Group codes can be quite helpful in project analysis or for determining specific interchange to interchange movements.
SETGROUP keywords
Keyword ADDTOGROUP |KIP| Description Specifies that the current link is to be assigned the codes that are in the value list. Specifies that the current link is to have the designated values removed from its codes. This keyword normally should not be used.

REMOVEFROMGROUP

|KIP|

Example
PHASE=LINKREAD IF (LI.SPDCLASS==1-3,6,9,55) ADDTOGROUP=1

Cube Voyager Reference Guide 253

Highway Program Control statements

SORT
Sorts user-defined arrays. ARRAY NUMRECS See SORT on page 76 for details.

SPDCAP
Revises speed and capacity tables. CAPACITY LANES 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.
SPDCAP keywords
Keyword CAPACITY |RV*99| Description 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 09999, inclusive. The capacity array is initialized to 20 times the index number, for all lane stratification (CAPACITY[1]=20, CAPACITY[2]=40...). 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 to be applied to the link. All values must be 03276.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.

LANES

|IV|

SPEED

|RV*99|

254 Cube Voyager Reference Guide

Highway Program Control statements

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.
Example
;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.

TURNS
Requests turning movement volumes. NT 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. 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. 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.

Cube Voyager Reference Guide 255

Highway Program Control statements

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.
TURNS keywords
Keyword N T |IP| |N| Description List of nodes at which turning volumes are to be accumulated. Expression used to compute the total volume at each of the nodes.

Example
FILEO TURNVOLO=myfile.trn, FORMAT=BIN TURNS N=1000-2000,3000,5000-6000,19000-32000, T=TURN[1] + TURN[3]

256 Cube Voyager Reference Guide

Highway Program Theory

Theory
This section discusses the theory used in the Highway program. Topics include: Process overview User stacks

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.
Example of suggested basic application template
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

Cube Voyager Reference Guide 257

Highway Program Theory

The internal logic of the program is as follows: PHASE = SETUP 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. ENDPHASE PHASE = LINKREAD 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

EndLoop ENDPHASE LOOP ITERATION=1,MAXITERS PHASE = ILOOP Loop I=1,ZONES Read required MATIs. Process the ILOOP stack. Write requested MATOs.

EndLoop ENDPHASE PHASE = ADJUST 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.

258 Cube Voyager Reference Guide

Highway Program Theory

Process the users ADJUST stack to either list the results of the assignment, or to revise LW.values, or Time for the next iteration. Apply Function Cost.

EndLoop. Depending upon the values for COMBINE and ITERATION: Combine link volumes. Combine MATO matrices.

Process the CONVERGE stack (user or default) If Convergence met, exit ITERATION Loop. ENDPHASE ENDLOOP ; Iteration loop

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

Cube Voyager Reference Guide 259

Highway Program Theory

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.
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.
ILOOP stack

This stack is the entire ILOOP phase, and is described previously. It MUST be present.
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.
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.

260 Cube Voyager Reference Guide

Highway Program Examples

Examples
This section contains examples for using the Highway program: Highway example 1 Highway example 2 Highway example 3 Highway example 4 Highway example 5 Highway example 6 Highway example 7 Highway example 8

Highway example 1
/* EXAMPLE 1 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

Cube Voyager Reference Guide 261

Highway Program Examples

Highway example 2
/* EXAMPLE 2 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 example 3
/* EXAMPLE 3 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 */ RUN PGM=HIGHWAY FILEI NETI = NETWORK.NET FILEI MATI[1] = TRIPS.MAT FILEI TURNPENI = TURNPEN.PEN FILEO NETO = LOADED.NET

262 Cube Voyager Reference Guide

Highway Program Examples

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 example 4
/* EXAMPLE 4 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

Cube Voyager Reference Guide 263

Highway Program Examples

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 example 5
/* EXAMPLE 5 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

264 Cube Voyager Reference Guide

Highway Program Examples

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 example 6
/* EXAMPLE 6 This script has two steps. In step 1 several examples of select link assignment are shown. In step two 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.0 5,0.05 ; Equilibrium assignment could be performed specifying COMBINE=EQUI ; or volume averaging by specifying COMBINE=AVE if desired PHASE=LINKREAD

Cube Voyager Reference Guide 265

Highway Program Examples

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

266 Cube Voyager Reference Guide

Highway Program Examples

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 example 7
/* EXAMPLE 7 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 8 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

Cube Voyager Reference Guide 267

Highway Program Examples

Highway example 8
/* Example 8 Example of using TOLLMATI 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],

268 Cube Voyager Reference Guide

Highway Program Examples

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

Cube Voyager Reference Guide 269

Highway Program Examples

270 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 271

Intersection Modeling

Intersection Modeling

This chapter discusses intersection modeling, part of the Cube Voyager Highway program. 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

272 Cube Voyager Reference Guide

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

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

Cube Voyager Reference Guide 273

Intersection Modeling Introduction to intersection modeling

measures (for example, changing the form of control at key intersections) it must be possible to represent the proposals in the model.

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

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

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

274 Cube Voyager Reference Guide

Intersection Modeling Introduction to intersection modeling

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.

Cube Voyager Reference Guide 275

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

JUNCTION
Each JUNCTION statement 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.
JUNCTION statement keyword overview
Priority Saturation v v Roundabout Gap acceptance v v Roundabout Empirical v v v v v v v v v v v Signals Geometric v v v v v v v Signals Saturation v v v v v

Keyword ACTUALGREEN APPROACH APPROACH1 APPROACHWIDTH AVERAGELANEWIDTH BUSBLOCKAGE CANSHARELEFT CANSHARERIGHT |R| |KIV10 | |KI| |R| |R| |RV2*| |?| |?|

Allway Stop

Priority Geometric

Twoway Stop

276 Cube Voyager Reference Guide

Intersection Modeling Control statements

JUNCTION statement keyword overview (continued)

Priority Saturation Roundabout Gap acceptance Roundabout Empirical v v v Signals Geometric Signals Saturation

Keyword CAPACITYINTERCEPT CAPACITYSLOPE CENTRALBUSINESSDISTRICT CENTRALRESERVATIONWIDTH CRITICALGAP CYCLETIME ENTRYANGLE ENTRYRADIUS ENTRYWIDTH ESTIMATEDDELAY EXCLUSIVELANES EXITONLY FLARELENGTH FOLLOWUPTIME FOURLANEMAJOR FREEFLOWCAP GRADE INITIALQUEUE INSCRIBEDDIAMETER LANEADJUST |R| |R| |K?|

Allway Stop

Priority Geometric

Twoway Stop

|KR|

|R| |KR| |R| |R| |R| |R| |I| |?| |R| |R| |K?| |R| |R| |R| |R| |K?| v v v x v x v v v v v v v

v v v v v v v v v v v v v v v x v x v v v x v v v x v v v v v v v v v v

Cube Voyager Reference Guide 277

Intersection Modeling Control statements

JUNCTION statement keyword overview (continued)

Priority Saturation Roundabout Gap acceptance Roundabout Empirical Signals Geometric Signals Saturation

Keyword MAJORROADWIDTH MINIMUMCAPACITY MOVEMENT NODE NUMBEROFLANES PARKINGMANEUVERS PHASE PHASES RANDOMNESS SATFLOWPERLANE SINGLELANE STORAGESPACE TURNCHANNELIZED TYPE VISIBILITY WIDTH |KR| |R| |S| |KI| |I| |RV2*| |KI| |I| |R| |R| |?| |KR| |?| |KS| |R| |R|

Allway Stop

Priority Geometric v

Twoway Stop

v v v v

v v v

v v v

v v v

v v v

v v v

v v v

v v v

v v v v v v v minor only v v v v v v v v v v minor only v v v v v v v v v v v v v

See the individual topics for descriptions of each keyword.

UNITS
Defines units of measurement for junction geometry. UNITS LENGTH

278 Cube Voyager Reference Guide

Intersection Modeling Control statements

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.
Example
UNITS LENGTH=FEET UNITS LENGTH=METERS

Cube Voyager Reference Guide 279

Intersection Modeling Common keywords

Common keywords
This section describes common keywords, applicable to multiple intersection types: APPROACH APPROACH1 ENABLE ESTIMATEDDELAY EXITONLY INITIALQUEUE MINIMUMCAPACITY MOVEMENT NODE RANDOMNESS TYPE

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

280 Cube Voyager Reference Guide

Intersection Modeling Common keywords

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.

Cube Voyager Reference Guide 281

Intersection Modeling Common keywords

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:
LeftDrive = n First Approach Second Approach Third Approach Through Right Right Left Left Through LeftDrive = y Through Left Left Right Right Through

At other modeled intersections, the choice of APPROACH1 is arbitrary with no modeling consequences.

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

282 Cube Voyager Reference Guide

Intersection Modeling Common keywords

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.

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 approachs ESTIMATEDDELAY value is analogous to a links initial travel time. On the assignments 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.

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.

Cube Voyager Reference Guide 283

Intersection Modeling Common keywords

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

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 queues discharge rate is not a constant; the discharge rate depends on the junctions 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.

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.

284 Cube Voyager Reference Guide

Intersection Modeling Common keywords

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.

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,

Cube Voyager Reference Guide 285

Intersection Modeling Common keywords

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.

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.

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

286 Cube Voyager Reference Guide

Intersection Modeling Common keywords

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.

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:

Cube Voyager Reference Guide 287

Intersection Modeling Common keywords

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 exception to the above rule is signals when there are several layers of choice of modeling methodology. When observed baseyear 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 Catlings delay formulation at an HCM signals.

288 Cube Voyager Reference Guide

Intersection Modeling Common keywords

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 yieldcontrolled intersection in the U.S. (where stop-controlled intersections are the norm).

Cube Voyager Reference Guide 289

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

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., 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. The detailed model also imposes more constraints on the allowed signal phasing than the saturation flow only model.

290 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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.

Generic keywords
This section describes generic keywords used for signals: CANSHARELEFT CANSHARERIGHT CYCLETIME EXCLUSIVELANES LANEADJUST PHASE and ACTUALGREEN PHASES SATFLOWPERLANE SINGLELANE

CANSHARELEFT
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

Cube Voyager Reference Guide 291

Intersection Modeling Signal-controlled intersections

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 movements left and the movement to this movements left must have CANSHARERIGHT = T coded. If SINGLELANE = T then CANSHARELEFT should not be coded.

CANSHARERIGHT
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 movements right, and the movement to this movements right must have CANSHARELEFT = T coded. If SINGLELANE = T then CANSHARERIGHT should not be coded.

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

292 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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.

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

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

PHASE and ACTUALGREEN

These keywords occur in pairs; every occurrence of the integervalued 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).

Cube Voyager Reference Guide 293

Intersection Modeling Signal-controlled intersections

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

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.

SATFLOWPERLANE
NOTE: Keywords are case insensitive. Capitalizing as SatFlowPerLane might improve readability.

294 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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.

SINGLELANE
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:
Junction type Signal-controlled intersection All-way stop-controlled intersection Two-way stop-controlled intersection Geometric Data Saturation Flows Use SINGLELANE may be coded SINGLELANE may be coded SINGLELANE may not be coded; code NUMBEROFLANES = 1 SINGLELANE may be coded for minor road Use FOURLANEMAJOR to describe major road Geometric Data SINGLELANE may be coded for minor arms Major road width in meters, not lanes SINGLELANE may be coded SINGLELANE may not be coded SINGLELANE may not be coded

Priority intersection (two-way yieldcontrolled intersection)

Saturation Flows Roundabout Empirical Gap Acceptance

Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES, CANSHARERIGHT, or CANSHARELEFT on that approach.

Cube Voyager Reference Guide 295

Intersection Modeling Signal-controlled intersections

At two-way stop-controlled intersections and priority junctions, a minor arm that does not have SINGLELANE = Y explicitly coded, has two lanes.

Geometric keywords
This section describes geometric keywords: AVERAGELANEWIDTH CONFLICTINGBIKE BUSBLOCKAGE CENTRALBUSINESSDISTRICT DELAYEQUATION EXITLANES GRADE PARKINGMANEUVERS PEDESTRIANFLOW PEDESTRIANPHASE PHASES UNITEXTENSION

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

296 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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

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

Cube Voyager Reference Guide 297

Intersection Modeling Signal-controlled intersections

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.

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

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

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

298 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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

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

PEDESTRIANFLOW
The number of pedestrians crossing the approach per hour. Note that this is a two-way flow.

PEDESTRIANPHASE
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

Cube Voyager Reference Guide 299

Intersection Modeling Signal-controlled intersections

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.

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.

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

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,

300 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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,

Cube Voyager Reference Guide 301

Intersection Modeling Signal-controlled intersections

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

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,

302 Cube Voyager Reference Guide

Intersection Modeling Signal-controlled intersections

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,

Cube Voyager Reference Guide 303

Intersection Modeling Signal-controlled intersections

ExclusiveLanes = 1, Phases = 23

304 Cube Voyager Reference Guide

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

Overview
This control is an unsignalized intersection between a major road and a minor road. The minor road approach (at a T), or approaches (at a crossroads) have stop signs. Traffic on the minor road must stop, before entering the intersection, even if there is no major road traffic visible. There is a hierarchy of flows, illustrated below, in which lower rank flows must give way to all higher rank streams.

Cube Voyager Reference Guide 305

Intersection Modeling Two-way stop-controlled 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.

Keywords
This section describes the keywords for two-way stop-controlled intersections: CRITICALGAP FLARESTORAGE FOLLOWUPTIME FOURLANEMAJOR FREEFLOWCAP GRADE PEDESTRIANFLOW PEDESTRIANSPEED SINGLELANE STORAGESPACE TURNCHANNELIZED

306 Cube Voyager Reference Guide

Intersection Modeling Two-way stop-controlled intersections

CRITICALGAP
NOTE: Keywords are case insensitive. Capitalizing as CriticalGap

might improve readability. The critical gap, in seconds, is one of the parameters of any gapacceptance 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:
Base critical gap (seconds)
Vehicle Movement Left turn from major Right turn from minor Through traffic on minor Left turn from minor Two-Lane Major Street 4.1 6.2 6.5 7.1 Four-Lane Major Street 4.1 6.9 6.5 7.5

Normally this value is allowed to default; only code when there are observations indicating site-specific driver behavior at the intersection

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

FOLLOWUPTIME
NOTE: Keywords are case insensitive. Capitalizing as FollowUpTime might improve readability.

Cube Voyager Reference Guide 307

Intersection Modeling Two-way stop-controlled intersections

The follow-up time, in seconds, is one of the parameters of any gapacceptance 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:
Vehicle Movement Left turn from major Right turn from minor Through traffic on minor Left turn from minor Base Follow-Up Time (seconds) 2.2 3.3 4.0 3.5

Normally this value is allowed to default; only code when there are observations indicating site-specific driver behavior at the intersection

FOURLANEMAJOR
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).

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

308 Cube Voyager Reference Guide

Intersection Modeling Two-way stop-controlled intersections

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.

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

PEDESTRIANFLOW
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 Chapter 18 of HCM 2000, especially to Equation 18-18 and the surrounding text.

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

SINGLELANE
NOTE: Keywords are case insensitive. Capitalizing as SingleLane

might improve readability.

Cube Voyager Reference Guide 309

Intersection Modeling Two-way stop-controlled intersections

The logical-valued keyword is used to indicate that an approach consists of a single lane. It is applicable to many junction types:
Junction type Signals All-way stop-controlled intersection Two-way stop-controlled intersection Geometric Data Saturation Flows Use SINGLELANE may be coded SINGLELANE may be coded SINGLELANE may not be coded; code NUMBEROFLANES = 1 SINGLELANE may be coded for minor road Use FOURLANEMAJOR to describe major road Geometric Data SINGLELANE may be coded for minor arms Major road width in meters, not lanes SINGLELANE may be coded SINGLELANE may not be coded SINGLELANE may not be coded

Priority intersection (two-way yield-controlled intersection)

Saturation Flows Roundabout Empirical Gap Acceptance

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.

STORAGESPACE
NOTE: Keywords are case insensitive. Capitalizing as StorageSpace

might improve readability.

310 Cube Voyager Reference Guide

Intersection Modeling Two-way stop-controlled intersections

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

TURNCHANNELIZED
NOTE: Keywords are case insensitive. Capitalizing as TurnChannelized might improve readability.

Cube Voyager Reference Guide 311

Intersection Modeling Two-way stop-controlled intersections

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.

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,

312 Cube Voyager Reference Guide

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 Voyager offers a capacity model of all-way-stop-controlled intersections which has been calibrated against traffic conditions in the US. The models only variable is the number of lanes for each arm. The capacities reported by models of undersaturated all-way-stopcontrolled intersections can appear very large. However, the model is very nonlinear and, as the flows are increased, the capacities will decrease.
All-way-stop-controlled intersection keyword
Keyword NUMBEROFLANES |I| Description Number of lanes at an approach to an all-waystop-controlled intersection. Valid values are 1, 2, or 3.

NOTE: Keywords are case insensitive. Capitalizing as NumberOfLanes might improve readability. Example

The following example describes an all-way-stop-controlled intersection between a one-lane road and a two-lane road.
Junction Node Approach = 6 Approach = 7 Approach = 8 Approach = 5 = 9 Type = AllWayStop Approach1 = 8, NumberOfLanes = 1, NumberOfLanes = 2, NumberOfLanes = 1, NumberOfLanes = 2

Cube Voyager Reference Guide 313

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

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

314 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

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. Empirical model Each entry is characterized by a capacity slope and a capacity intercept. 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

Cube Voyager Reference Guide 315

Intersection Modeling Roundabouts

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.

Empirical roundabouts: Keywords

This section describes keywords to model empirical roundabouts: APPROACHWIDTH CAPACITYINTERCEPT CAPACITYSLOPE CROSSING2ENTRY CROSSING2EXIT CROSSINGLENGTH ENTRYANGLE ENTRYRADIUS ENTRYWIDTH FLARELENGTH INSCRIBEDDIAMETER

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

316 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

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.

CAPACITYINTERCEPT
NOTE: Keywords are case insensitive. Capitalizing as CapacityIntercept might improve readability.

Cube Voyager Reference Guide 317

Intersection Modeling Roundabouts

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.

CAPACITYSLOPE
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

318 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

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.

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

Cube Voyager Reference Guide 319

Intersection Modeling Roundabouts

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

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

ENTRYANGLE
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.
Case 1: A roundabout with straight weaving sections

Let A be the point where the entry line meets the inside edge of the lane

320 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

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

Case 2: A roundabout with long curved weaving sections

The construction for case 2 is nearly identical to that for case 1. However, the line AD is replaced by a curve AD which is always parallel to the weaving section.
Case 3: A roundabout with short weaving sections

EF and BC are constructed as in case 1

Cube Voyager Reference Guide 321

Intersection Modeling Roundabouts

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

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

322 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

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

Cube Voyager Reference Guide 323

Intersection Modeling Roundabouts

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

324 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

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.

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

Empirical roundabouts: Example

The following example uses geometrical data to calculate slopes and intercepts:
Junction,

Cube Voyager Reference Guide 325

Intersection Modeling Roundabouts

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,

326 Cube Voyager Reference Guide

Intersection Modeling Roundabouts

Gap acceptance roundabouts: Keywords

This section describes the keywords to model gap-acceptance roundabouts: CRITICALGAP FOLLOWUPTIME

CRITICALGAP
Keywords are case-insensitive but the recommended capitalization CriticalGap may improve readability. The critical gap, in seconds, is one of the parameters of any gapacceptance 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 singlelane roundabout entry in the US, the critical gap should be in the range 4.1 to 4.6 seconds.

FOLLOWUPTIME
NOTE: Keywords are case insensitive. Capitalizing as FollowUpTime might improve readability.

The follow-up time, in seconds, is one of the parameters of any gapacceptance 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 singlelane roundabout entry in the America, the follow-up time should be in the range 2.6 to 3.1 seconds.

Cube Voyager Reference Guide 327

Intersection Modeling Roundabouts

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

328 Cube Voyager Reference Guide

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

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 twoway 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. 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).

Cube Voyager Reference Guide 329

Intersection Modeling Priority junctions

Keywords
This section describes keywords for priority junctions: GEOMETRIC SINGLELANE

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

SINGLELANE
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:
Junction type Signals All-way stop-controlled intersection Two-way stop-controlled intersection Priority intersection (two-way yield-controlled intersection) Roundabout Geometric Data Geometric Data Saturation Flows Use SINGLELANE may be coded SINGLELANE may be coded SINGLELANE may not be coded; code NUMBEROFLANES = 1 SINGLELANE may be coded for minor road Use FOURLANEMAJOR to describe major road SINGLELANE may be coded

Saturation Flows Empirical Gap Acceptance

SINGLELANE may be coded SINGLELANE may not be coded SINGLELANE may not be coded

330 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

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.

Geometric priority junctions: Keywords

This section describes the keywords for geometric priority junctions: CENTRALRESERVATIONWIDTH CROSSING2ENTRY CROSSING2EXIT CROSSINGLENGTH FREEFLOWCAP MAJORROADWIDTH VISIBILITY WIDTH

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

Cube Voyager Reference Guide 331

Intersection Modeling Priority junctions

In the diagram below, the CENTRALRESERVATIONWIDTH is given by (W5 + W6).

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

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

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

FREEFLOWCAP
NOTE: Keywords are case insensitive. Capitalizing as FreeFlowCap might improve readability.

332 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

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.

MAJORROADWIDTH
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).

Cube Voyager Reference Guide 333

Intersection Modeling Priority junctions

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

334 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

WIDTH
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 roads 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 lanes average width during the final 25 meters of the approach before the give-way line.

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,

Cube Voyager Reference Guide 335

Intersection Modeling Priority junctions

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

Saturation-flow priority junctions: Keywords

This section describes the keywords for saturation-flow priority junctions: CANSHARELEFT CANSHARERIGHT EXCLUSIVELANES SATFLOWPERLANE

CANSHARELEFT
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

336 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

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 movements left and the movement to this movements left must have CANSHARERIGHT = T coded. If SINGLELANE = T then CANSHARELEFT should not be coded.

CANSHARERIGHT
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 movements right, and the movement to this movements right must have CANSHARELEFT = T coded. If SINGLELANE = T then CANSHARERIGHT should not be coded.

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

Cube Voyager Reference Guide 337

Intersection Modeling Priority junctions

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

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,

338 Cube Voyager Reference Guide

Intersection Modeling Priority junctions

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

Cube Voyager Reference Guide 339

Intersection Modeling Priority junctions

340 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 341

Network Program

Network Program

This chapter discusses the Network program. Topics include: Introduction to the Network program Control statements Theory Examples

342 Cube Voyager Reference Guide

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 COMBINE subkeyword with the LINKI and NODEI keywords under the FILEI statement to specify how to combine values of fields with redundant data records. 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

Cube Voyager Reference Guide 343

Network Program Introduction to the Network program

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 FORMAT subkeywords under NETO keyword for the FILEO statement on page 367 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

344 Cube Voyager Reference Guide

Network Program Introduction to the Network program

Built-in variables
Variable A B GEOMETRYSOURCE Description Node number of a links A node Node number of a links B node Defines the input file index number that controls the source of the geometry to be applied to the output NETO 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, or combinations of link and node files in ASCII, DBF, or MDB formats. When specifying an output network to a Cube geodatabase network, GEOMETRYSOURCE specifies which # from the FILEI LINKI[#]= 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 fields 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]). N X Y _COMPARE _ZONES Node number of the node X-coordinate value of a node Y-coordinate value of a node Stores a return code value resulting from the COMPARE statement Holds the number of zones read from the input network as set by the ZONES parameter

Cube Voyager Reference Guide 345

Network Program Introduction to the Network program

Built-in functions
Function SPEEDFOR(lanes,spdclass) CAPACITYFOR(lanes,capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass. Returns the capacity times the lanes for the designated number of lanes and capclass.

346 Cube Voyager Reference Guide

Network Program Control statements

Control statements
This section describes the control words available in the Network program.
Control word ABORT ARRAY BREAK COMP COMPARE CONTINUE CROSSTAB DELETE EXIT FILEI FILEO IF ... ELSEIF ... ELSE ... ENDIF LOOKUP LOOP ... ENDLOOP MERGE PARAMETERS PLOT PLOTTER PRINT PROCESS ... ENDPROCESS REPORT SORT SPDCAP Description Abort current program and Cube Voyager Declare user arrays Break out of stack processing for current data record Compute variables from expressions Compare network records Continue at end of loop statement Tabulate / cross tabulate variable values Delete this record Terminate current phase Input files Output files Define IF ENDIF block Define lookup tables (see Chapter 3, General Syntax) Define user controlled loop Set record and variable merging specifications Set static parameters Draw and post values on links and nodes Set plotter driver specifications Print variable values Set process (phase) blocks Select standard reports Sort user arrays Set / revise network speed and capacity table values

Cube Voyager Reference Guide 347

Network Program Control statements

ABORT
Aborts the Network program and Cube Voyager. MSG 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.
ABORT keyword
Keyword MSG |S| Description Optional message to be printed along with the ABORT message.

Example
IF (a > 1000) ABORT MSG='Must be the wrong Network'

ARRAY
Declares user single dimension arrays. 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

348 Cube Voyager Reference Guide

Network Program Control statements

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.
ARRAY variable
Variable VAR |I| Description VAR is the 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, 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.

Example
ARRAY abc=100, xyz=100 ARRAY AN=LINKS, BN=LINKS, VMT=LINKS ; NETI must be a binary network

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

Cube Voyager Reference Guide 349

Network Program Control statements

Example 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

COMP
Computes a value for a variable.
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 variables 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,

350 Cube Voyager Reference Guide

Network Program Control statements

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:
Function SPEEDFOR(lanes,spdclass) CAPACITYFOR(lanes,capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass. Returns the capacity times the lanes for the 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.
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)

COMPARE
Compares network records. RECORD (LIST TITLE)

Cube Voyager Reference Guide 351

Network Program Control statements

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:
Value of _COMPARE n 0 -1 -2 Meaning n attributes are different between two records. No differences between two records. Record not in file one. Record not in file two.

There may be multiple COMPARE statements in a single application.

COMPARE keywords
Keyword RECORD |IP| Description 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. 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. TITLE |S| Optional title to print with the summary report. It is suggested that the value be embedded within quotes.

LIST

|I|

352 Cube Voyager Reference Guide

Network Program Control statements

Example 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 ------Variable Cnt Cnt Min Max Ave -------- --- --------A 321 ----B 321 ----LANES -- 321 1 1 -1 DISTANCE -- 321 1 1 -1 SPDCLASS -- 321 2 2 -2 CAPCLASS -- 321 1.23 1.23 -1.23 NAME -- 321 ------- 1 > 2 ---Cnt Min Max Ave --- --- --- --7 -- -- -7 -- -- --- -- -- --- -- -- --- -- -- --- -- -- --- -- -- --

Ave -----1 -1 -2 -1.23 --

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

Cube Voyager Reference Guide 353

Network Program Control statements

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

CROSSTAB
Cross tabulates variables. VAR (FORM) ROW (RANGE) COL (RANGE) COMP (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 tables 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

354 Cube Voyager Reference Guide

Network Program Control statements

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.
CROSSTAB keywords
Keyword COL COL RANGE Subkeyword |S| |RV50| Description Name of the variable that will be used for the column definition of the report. 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). 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. 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 Name of the variable that will be used for the row definition of the report.

COMP

|NV|

COMP

FORM

|S|

ROW

|S|

Cube Voyager Reference Guide 355

Network Program Control statements

CROSSTAB keywords (continued)

Keyword ROW Subkeyword RANGE |RV50| Description 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. 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. 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.

VAR

|SV10|

VAR

FORM

|S|

Range classification strategy

The ROW RANGE and COL RANGE values are stored as singleprecision 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

356 Cube Voyager Reference Guide

Network Program Control statements

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.
RANGE 1-10 1-10-1 1-10-1 1-10-1.0 1-10-0.5 1-3-0.5 1-3-0.3 1-3-0.3 1-3-0.3 Internal Range 1-10 1-10-1 1-10-1 10-100-10 10-100-5 10-30-5 10-30-3 10-30-3 10-30-3 Integer Value 0.99 1.50 1.45 1.45 1.45 3.00 1.29 3.01 3.001 Value 1 2 1 15 15 30 13 30 30 Index -2 1 1 2 5 2 7 7

Cube Voyager Reference Guide 357

Network Program Control statements

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.
Example
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, 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

CrossTab

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.
Example
If (a=2150-2199 || b=2150-2199) DELETE ;remove all links connected to nodes 2150-2199

EXIT
Exits current phase. Use EXIT to exit the current phase. The remaining input records to the phase will not be read.
Example
IF (a > 1000) EXIT; no reason to process beyond this link.

358 Cube Voyager Reference Guide

Network Program Control statements

FILEI
NOTE: See FILEI on page 48 for general information about FILEI

and for important limitations when using Application Manager. Inputs data files. LINKI (EXCLUDE VAR (BEG LEN TYP MIN MAX) RENAME START STOP SELECT REV TRIPSXY DETAILS COMBINE (FIRST LAST AVE SUM MAX MIN CNT AVEX0)) NODEI (EXCLUDE VAR (BEG LEN TYP MIN MAX) RENAME START STOP SELECT COMBINE (FIRST LAST AVE SUM MAX MIN CNT AVEX0)) LOOKUPI The FILEI statement specifies the input files that contain the network data. You may designate up to ten NODEI and ten LINKI files in a FILEI statement. 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 networks 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

Cube Voyager Reference Guide 359

Network Program Control statements

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 recordspossible 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.
FILEI keywords
Keyword LINKI Subkeyword |KFV10| Description Name of a file that contains link-based records. 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.

360 Cube Voyager Reference Guide

Network Program Control statements

FILEI keywords (continued)

Keyword LINKI Subkeyword COMBINE |?| Description 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. 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. Use to rename a variable from the input file. The format is
RENAME=oldname-newname; both names must be specified.

LINKI

EXCLUDE

|SV|

LINKI

RENAME

|SP|

Names can be swapped on one statement; to swap names for V1 and V2: RENAME=V1-temp1,V2-V1,temp1-V2

Cube Voyager Reference Guide 361

Network Program Control statements

FILEI keywords (continued)

Keyword LINKI Subkeyword REV [I| Description 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 BA, 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. 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. 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. Name of a file that contains TRIPS X-Y data. This keyword is only required for TRIPS networks.

LINKI

START

[s]

LINKI

STOP

[s]

LINKI

TRIPSXY

[F]

362 Cube Voyager Reference Guide

Network Program Control statements

FILEI keywords (continued)

Keyword LINKI Subkeyword VAR |SV| Description 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. Designates the length of the field that begins at position BEG. 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). 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.

LEN |I| TYP |S|

MIN |R|

Cube Voyager Reference Guide 363

Network Program Control statements

FILEI keywords (continued)

Keyword LINKI Subkeyword VAR (continued) Description VAR may also be specified with 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 610). 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. NODEI |KFV10| Name of a file or an MDB and element that contains node-based records. See LINKI on page 360 for comments regarding file detection. NODEI uses the same keywords as LINKI except REV and TRIPSXY.

Example

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

364 Cube Voyager Reference Guide

Network Program Control statements

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

FILEO
Generates output filesa network file, link file, and node file. LINKO (FORM FORMAT DELIMITER INCLUDE EXCLUDE VARFORM) NETO (FORMAT (TRIPSXY) EXCLUDE INCLUDE LEFTDRIVE) NODEO (FORMAT DELIMITER INCLUDE EXCLUDE FORM VARFORM) PRINTO (APPEND)
FILEO keywords
Keyword LINKO Subkeyword |KF| Description 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 may be an MDB/element name. 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. Similar to EXCLUDE under NETO. 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 70 and Defining a character print format on page 71. Optional format codes are usually not appropriate for use on this statement.

LINKO LINKO

EXCLUDE FORM

|SV| |S|

Cube Voyager Reference Guide 365

Network Program Control statements

FILEO keywords (continued)

Keyword LINKO Subkeyword FORMAT |S| Description 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 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. LINKO INCLUDE |SV| Similar to 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. 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 variables 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.

LINKO

VARFORM

|SV|

366 Cube Voyager Reference Guide

Network Program Control statements

FILEO keywords (continued)

Keyword NETO Subkeyword EXCLUDE |S| Description 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. 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 345). 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. Do not use with EXCLUDE subkeyword.

NETO

FORMAT

|S|

Cube Voyager Reference Guide 367

Network Program Control statements

FILEO keywords (continued)

Keyword NETO Subkeyword LEFTDRIVE |?| Description 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: NODEO |KF| 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

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.

PRINTO PRINTO APPEND

|KF| |?|

Name of the file where the program directs output from a PRINT statement using PRINT PRINTO=#. See APPEND under PRINT on page 66.

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.

368 Cube Voyager Reference Guide

Network Program Control statements

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

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 52 for more details.
Example
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

LOOP ... ENDLOOP

Controls a general variable loop.
LOOP LVAR=Lbeg,Lend,Linc ; ... ENDLOOP

where:

Cube Voyager Reference Guide 369

Network Program Control statements

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 LOOPENDLOOP 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: Initialize LVAR to Lbeg. Compute the value for Lend. Compute the value for Linc (default to 1 if missing). Proceed to next statement. At ENDLOOP: If Lend not specified, jump to next statement.

370 Cube Voyager Reference Guide

Network Program Control statements

Add Linc to LVAR. Compare LVAR to Lend. 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.
Example
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

MERGE
Specifies record and variable merging. RECORD AVE AVEX0 CNT FIRST LAST MAX MIN SUM

Cube Voyager Reference Guide 371

Network Program Control statements

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.
MERGE keyword selecting records
Keyword RECORD |?| Description 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.
MERGE keywords technique
Keyword AVE AVEX0 CNT |SV| |SV| |SV| Description Average of all records. Average of all records, where the value from the file records is not 0. Count of the records that contain the variable.

372 Cube Voyager Reference Guide

Network Program Control statements

MERGE keywords technique

Keyword FIRST LAST MAX MIN SUM |SV| |SV| |SV| |SV| |SV| Description Directly from the record from the FILEI with the lowest index[]. Directly from the record from the FILEI with the highest index []. Maximum value of all the records. Minimum value from all the records. Sum of all the records.

Example
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 1 1 2 2 3 3 3 101 105 101 102 101 102 104 B DISTANCE SPDCLASS CAPCLASS 11 12 -----11 12 -----LANES 1 3 --2 2 3 COUNT --1000 1000 ----

102 10.1 106 12.5 102 -103 -102 11.5 103 12.6 105 1.0

Cube Voyager Reference Guide 373

Network Program Control statements

Order as seen in LINKMERGE, after being processed in the INPUT phase.

LINKI[] A 1 2 3 2 3 3 2 B DISTANCE SPDCLASS CAPCLASS LANES 11 -----12 11 -----12 1 -2 -2 3 3 COUNT -1000 -2000 ----

101 102 10.1 101 102 -101 103 11.5 102 103 -102 103 12.6 104 105 1.0 105 106 12.5

MERGE RECORD=FALSE ; Resulting file:

A 101 105 B 102 106 DISTANCE 10.1 12.5 SPDCLASS 11 12 CAPCLASS 11 12 LANES 1 3 COUNT 1000 0

MERGE RECORD=TRUE FIRST=COUNT, AVEX0=DISTANCE ; Resulting file:

A 101 102 104 105 B 102 103 105 106 DISTANCE 10.8 12.6 1.0 12.5 SPDCLASS 11 0 0 12 CAPCLASS 11 0 0 12 LANES 1 2 3 3 COUNT 1000 2000 0 0

PARAMETERS
Specifies basic parameter values.

374 Cube Voyager Reference Guide

Network Program Control statements

LEFTDRIVE LIST_ERRS MAX_IP_ERRS NODES REPL_DUP ZONES

PARAMETERS keywords
Keyword LEFTDRIVE |?| Description Used to force a LeftDrive switch into the NETO. By default, this value is not set. See FILEO NETO LEFTDRIVE in FILEO on page 365 for more details. Specifies how many records with data errors will be listed before turning off the error listing. Default value is 20. 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.

LIST_ERRS

|KI|

MAX_IP_ERRS

|KI|

Cube Voyager Reference Guide 375

Network Program Control statements

PARAMETERS keywords (continued)

Keyword NODES |KI| Description 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 must be a greater than 0 and less than 999,999. 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. 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.

REPL_DUP

|K?|

All the values on this statement are trigger keys; the PARAMETERS control word need not be specified. Each keyword could begin a new statement.

376 Cube Voyager Reference Guide

Network Program Control statements

Example
PARAMETERS repl_dup=n MAX_IP_ERRS=10 nodes=35000 zones=2203

PLOT
Selects links/nodes for plotting. DRAWA DRAWLINK LINKPOST NODEPOST
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.

Cube Voyager Reference Guide 377

Network Program Control statements

A PLOT statement may be specified on a short IF statement, but it must begin with one of the keywords.
PLOT keywords
Keyword DRAWA |S4| Description Specifies the characteristics for drawing a symbol for the A-node of the link. Possible values are: DRAWLINK |KS4| Color A value as described in PLOTTER on page 378. Size Size of the symbol. Symbol Centered on the node, can be Circle, Rectangle, or Triangle. Fill

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. Specifies the color that this link is to be posted with. Specifies the color and size of the variables that are to be posted for this Anode. (See NODEPOSTVARS under PLOTTER on page 378 for information about which variables are to be posted.)

LINKPOST NODEPOST

|S| |S2|

Example

See Examples on page 401.

PLOTTER
Specifies plotting parameters BANDWIDTH (FILL TAPER) DEVICE FILE FOOTER (ALIGN FONT) HEADER (ALIGN FONT) LINKOFFSET LEGEND (FONT LINE (SYMBOL)) MAPSCALE MAPWINDOW MARGINS PLATESIZE POSTLINKVAR (FONT POST) POSTNODEVAR (FONT)

378 Cube Voyager Reference Guide

Network Program Control statements

The PLOTTER statement specifies the configuration for plotting link and/or node information. See Plotting on page 398 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.
PLOTTER keywords
Keyword BANDWIDTH Subkeyword |S| Description 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. 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. 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. 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

BANDWIDTH

FILL

|S|

BANDWIDTH

TAPER

|I|

DEVICE

|S|

Cube Voyager Reference Guide 379

Network Program Control statements

PLOTTER keywords (continued)

Keyword FILE Subkeyword |F| Description 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. 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 [date] [idate] [time] [times] [window] [scale] FOOTER ALIGN Replacement MM/DD/YY MMM DD YYYY HH.MM HH.MM.SS X=xxxxx-xxxxx Y=yyyyy-yyyyy Scale=xxxxx

FOOTER

|S16|

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

FOOTER

FONT

380 Cube Voyager Reference Guide

Network Program Control statements

PLOTTER keywords (continued)

Keyword HEADER Subkeyword |S16| Description 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. 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. 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. 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

HEADER

ALIGN

|S|

HEADER

FONT

|S4|

LEGEND

|S|

NOTE: The four positions can also be designated as TL, TR, BL, and BR, or 1, 2, 3, and 4. See Examples on page 401. 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.

Cube Voyager Reference Guide 381

Network Program Control statements

PLOTTER keywords (continued)

Keyword LEGEND Subkeyword FONT |S9| Description Specifies the font characteristics for the text in this legend. See HEADER FONT on page 381 for details. Text to be printed at the specified line of the legend. 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 377 for valid symbol names. If a sample line style is to be drawn, see DRAWLINK under PLOT on page 377 for valid names. The size of the symbol, or the length of the line. Standard color designation. Standard color designation if the symbol is to be filled with a color.

LEGEND LEGEND

LINE SYMBOL

|S16| |S4|

Size Color Fill 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-tohigh link. 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.

MAPSCALE

|R|

382 Cube Voyager Reference Guide

Network Program Control statements

PLOTTER keywords (continued)

Keyword MAPWINDOW Subkeyword |R4| Description 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. 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.

MARGINS

|R4|

Cube Voyager Reference Guide 383

Network Program Control statements

PLOTTER keywords (continued)

Keyword PLATESIZE Subkeyword |R2| Description 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. 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. 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

|S4|

POSTLINKVAR

FONT

|S4|

384 Cube Voyager Reference Guide

Network Program Control statements

PLOTTER keywords (continued)

Keyword POSTLINKVAR Subkeyword POST |S| Description Specifies how link post text is to be printed when it is too long for the link. The possible selections are: Fit All AutoSize AutoSize(ss) Omit the text; it doesnt fit. Print it, regardless if it overruns the link. Decrease the font size until it fits, or is too small. 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. 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.

POSTNODEVAR

FONT

|S4|

Font specifications

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

Cube Voyager Reference Guide 385

Network Program Control statements

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.
Color black red green blue yellow purple aqua gray silver lime white none Decimal 0 255 49152 16711680 65535 8388736 16776960 8421504 12632256 65280 16777215 -1 HexValue 0x000000 0x0000ff 0x008000 0xff0000 0x00ffff 0x800080 0xffff00 0x808080 0xc0c0c0 0x00ff00 0xffffff -R#G#B# -r255 g128 b255 r255g255 r128b128 g255b255 r128g128b128 r192g192b192 g255 r255g255b255 --

386 Cube Voyager Reference Guide

Network Program Control statements

Example

See Examples on page 401.

PRINT
Formats and prints a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See PRINT on page 66 for more details.
Example
PRINT LIST=A(4),B(5),DISTANCE(6.2) ABCDE(6.3), FORM=LRCD, LIST=SPEED, TIME1 ;Note: this line is a continuation

Cube Voyager Reference Guide 387

Network Program Control statements

LIST= N(5), X, Y PRINT FORM=6.0CDLR LIST=A,B,DISTANCE, T0, SPDCLASS FILE=PRINTFIL.002

PROCESS ... ENDPROCESS

Specifies a PROCESS and ENDPROCESS block. PHASE (FILEI (comp))
PROCESS keywords
Keyword PHASE Subkeyword |KS| Description 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. 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.

PHASE

FILEI

|F|

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.

388 Cube Voyager Reference Guide

Network Program Control statements

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.

Example 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

Example 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

Cube Voyager Reference Guide 389

Network Program Control statements

REPORT
Defines report specifications. ALL CAPACITY DEADLINKS DUPLICATES FILEI FILEO INPUT MERGE SPEED UNCONNECTED
REP

REPORT keywords
Keyword ALL CAPACITY DEADLINKS |?| |?| |?| Description Set all the following reports to this value (not usually recommended). Default value is F. Capacity tables. Default value is F. 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. Duplicate links that are detected during PHASE=INPUT. Default value is F. Internal specifications for the input files (use for debugging only). Default value is F. Internal specifications for the allocation of output variables use for debugging only). Default value is F. Summary statistics following input phases. Default value is F. Summary statistics following every phase. Default value is T. Speed tables. Default value is F. List of zones that do not have links into and out of them. Default value is T.

DUPLICATES FILEI FILEO INPUT MERGE SPEED UNCONNECTED

|?| |?| |?| |?| |?| |?| |?|

All reports must be specified with a logical value of true or false. The default value is true.
Example
REPORT FILEI=Y, FILEO=Y; normally not specified. REPORT SPEED=Y, UNCONNECTED=N REPORT ALL=true, fileo=false, filei=false

390 Cube Voyager Reference Guide

Network Program Control statements

SORT
Sorts user-defined arrays. ARRAY NUMRECS See SORT on page 76 for more information about this standard Cube Voyager statement.
Example
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

Cube Voyager Reference Guide 391

Network Program Control statements

SPDCAP
Revises speed and capacity tables. CAPACITY LANES SPEED
SPDCAP keywords
Keyword CAPACITY |RV*99| Description 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...). 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 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.

LANES

|IV|

SPEED

|RV*99|

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.
Example
;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.

392 Cube Voyager Reference Guide

Network Program Theory

Theory
This section describes the theory used by the Network program. Topics include: Phase descriptions Variable referencing Output variables Plotting

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

Cube Voyager Reference Guide 393

Network Program Theory

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.

INPUT phase
All ASCII 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.

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

394 Cube Voyager Reference Guide

Network Program Theory

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

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

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

Cube Voyager Reference Guide 395

Network Program Theory

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 node records: NI.#.name* NI#.name N.#.name N#.name For link records: LI.#.name* LI#.name L.#.name L#.name

*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

396 Cube Voyager Reference Guide

Network Program Theory

variables allow the user to accumulate statistics during link processing, and to then compute and print summaries at the end of processing.
NOTE: In some 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 on page 401 for an illustration.)
Example
_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

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.

Cube Voyager Reference Guide 397

Network Program Theory

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

398 Cube Voyager Reference Guide

Network Program Theory

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.

Cube Voyager Reference Guide 399

Network Program Theory

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:
Process DrawLink LinkPost DrawA NodePost Description Draw the link as specified. Post variables for the link. Draw a specified symbol for the Anode of the link 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.

400 Cube Voyager Reference Guide

Network Program Examples

Examples
This section contains examples of the Network program: Listing links to the print file Merging link records from multiple ASCII files Dumping link and node records to DBF files excluding select fields Building network from inline data records Simple link plot Complex plot

Listing links to the print file

run pgm=NETWORK ; List the links in a network neti=demo20.net list=a,b endrun

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

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

Cube Voyager Reference Guide 401

Network Program Examples

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

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') ,

402 Cube Voyager Reference Guide

Network Program Examples

stop=(substr(record,1,2)=='XY') list=a,b,dist endrun

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

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,

Cube Voyager Reference Guide 403

Network Program Examples

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

404 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 405

Matrix Program

Matrix Program

This chapter describes the Matrix program. Topics include: Using the Matrix program Control statements Examples

406 Cube Voyager Reference Guide

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 RECI/RECO processing in v4.0 and beyond Working with logit choice models

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: Selected rows Marginal summaries (trip ends, etc.) Frequency distributions User formatted files

Cube Voyager Reference Guide 407

Matrix Program Using the Matrix program

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 Iloop, 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.

408 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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

Built-in variables
Matrix program built-in variables
Variable FIRSTZONE Description 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. The current row zone. The iteration number; usually 1. A column index, usually 1, and varies (1-Zones) for MW[] and LOOPs. 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. Result of LOWEST(); A work matrix; see COMP on page 477 for more details. Holds the number of fields on the input record file. Holds the number of records in the input record file. Holds the record number of the current record being processed from the input record file.

I ITERATION J LASTZONE

LOWCNT MW[] RECI.NUMFIELD RECI.NUMRECORDS RECI.RECERR RECI.RECNO

Cube Voyager Reference Guide 409

Matrix Program Using the Matrix program

Matrix program built-in variables (continued)

Variable THISPROCESS Description Contains the process number of the current process when using intrastep distributed processing under Cube Cluster. A copy of I. Number of zones.

Z ZONES

Built-in functions
Described in more detail in COMP on page 477.
Matrix program built-in functions
Function ARRAYSUM() LOWEST() MATVAL() ROWADD() ROWAVE() ROWCNT() ROWDIV() ROWFAC() ROWFIX() ROWMAX() ROWMIN() ROWMPY() ROWSUM() Description Returns the value of the sum of an arrays values. Sum lowest valued cells in a row. Allow random access to values from MATIs Add matrices. Average cell value where value!=0 Number of cells whose values != 0 Divide one matrix by another. Factors the row by fac. Integerize mw (start at column intrazonal + 1) Maximum value in the row. Minimum value in the row. Multiply one matrix by another. Row total

Transposed matrices
A copy of a transposed input is obtained by referencing a variable with a name of MI.n.nameT. In Matrix program terminology, a transposed matrix is one that has had its rows and columns switched. See COMP on page 477 for details.

410 Cube Voyager Reference Guide

Matrix Program Using the 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.

ARRAY FILEI and FILEO (which define the input and output data.) LOOKUP PARAMETERS RENUMBER
Computational statements Cause variable values to be

updated. BSEARCH CALL CHOICE COMP FREQUENCY SET XCHOICE

Reporting statements Cause values to be accumulated

and/or displayed dynamically. FREQUENCY PRINT PRINTROW REPORT

Flow control statements Set which statement is to be

performed next. GOTO :label

Cube Voyager Reference Guide 411

Matrix Program Using the Matrix program

BREAK CONTINUE LOOP ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For more details about control statements, see Control statements on page 451.

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)

412 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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.

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.

Cube Voyager Reference Guide 413

Matrix Program Using the Matrix program

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.

Working with lists of zones using the INLIST 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

414 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Working with 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 lists 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:
...

Cube Voyager Reference Guide 415

Matrix Program Using the Matrix program

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

416 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Working with RECI/RECO processing in v4.0 and beyond

Substantial changes have been made in dealing with RECI text (non-DBF) files in versions later than 3.2.x. There were several reasons for these changes: Earlier versions had used the keyword FLD to define data fields. This was inconsistent with most other text file processing where FIELDS was used; so FLD has been decommissioned and replaced with FIELDS. For backward compatibility, script references to RI.FLD[] will act the same and be treated as if RECI.NFIELD[] were coded. New scripts developed after version 3.2.x should reference RECI.NFIELD[]. The earlier versions could deal with only numeric data fields; v4.0 can and later versions can deal with both numeric and character data fields. To incorporate these changes, the entire structure of RECI for text processing had to be completely rewritten. This has rendered older setups unusable, a practice that we generally do not like to condone, but necessary in this situation. We have attempted to minimize these impacts by making program changes such that the only possible change to user script files can be made with simple global search and replace commands in a text editor. There are two forms of text records that have to be dealt with: fixed format and delimited. These forms can not be intermixed in the same record processing step of the Matrix program. The way that the program distinguishes between the two is by the way the data fields are defined in the script. 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. All data fields can optionally be defined as character mode (C) or numeric mode (N), with N being the default mode. If the data field is being defined via the name= format, the mode can be appended to the name: ORGZONE(N)= STREET(C)=. If the data fields are being

Cube Voyager Reference Guide 417

Matrix Program Using the Matrix program

defined via the FIELDS= format, the mode can be appended to the end of the field definition: FIELDS=1-3(C) for fixed format, or FIELDS=1(N). For every FIELD, there will be two values: a numeric value and a character value. They are referenced as RECI.NFIELD[x] and RECI.CFIELD[x]. If the field is defined as numeric, its parallel character RECI.CFIELD[] value will be blank. Conversely, for all character variables, the parallel RECI.NFIELD[] value will be zero. To define a number of data fields when the user does not wish to have uniquely specified names for all fields, the FIELDS= format is used. FIELDS=6,9,13 will define variables RI.FIELD1, RI.FIELD2, RI.FIELD3 coming from data fields number 6, 9, 13 respectively. These variables can also be referenced as: RECI.NFIELD[3] RECI.NFIELD[2] RECI.NFIELD[3]. Optionally, FIELDS can specify multiple successive fields with a single specification (providing all are the same mode). FIELDS=6(7) specifies that RI.FIELD1RI.FIELD7 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. For fixed format, FIELDS=1-5(10), would define variables 10 variables: RI.FIELD1RI.FIELD10, and RECI.NFIELD[1-10]. FIELDS=15(C10) would establish the RI.FIELDs as character, and would cause population of RECI.CFIELD[1-10]. RI.FIELD2 would be obtained from columns 6-10, RI.FIELD3 would be from 11-15, etc. FIELDS=21-22(7) would generate RI.FIELD1-7 with the values coming from columns 21-22, 23-24,25-26 If FIELDS= and name= are intermixed, the monotonic index for FIELDS continues with the next FIELDS value. FIELDS=1,2,3, Var4=4, var5=5, Var6(C)=10, FIELDS=11(5) will generate RI.FIELD1 through RI.FIELD8 (and RECI.xFIELD[1-8]). FIELDS= may be specified multiple times, with, or without multiple definitions. FIELDS=1,2,3,6(3), FIELDS=22(C3) will cause RI.FIELD1 RI.FIELD9 to be obtained from data fields 1,2,3,6,7,8,22,23,24. In addition, RECI.NFIELD[1-9] and RECI.CFIELD[1-9] will be defined. However, RECI.NFIELD[7-9] will all be zero, and RECI.CFIELD[1-6] will be blank.

418 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Application script running under earlier versions that did not have this capability will have to be revised. The basic revisions required are: If FLD= specification (which indicated fixed format records) was used, several revisions are required. If the old script had FLD[3]=3, FLD[10]=10, RI.FLD[3] was obtained from column 3 of the data record and RI.FLD[10] was obtained from column 10. This will have to be revised to FIELDS=0-0,0-0,3-3,0-0,0-0,0-0,0-0,0-0,10-10. Any references to RI.FLD[x] should be revised to RECI.NFIELD[x], or to RI.FIELDx. In addition, if name= was specified, and the definition was a single field (not lo-hi), the definition will have to be changed to lo-lo; for example: INCOME=3 will have to become INCOME=3-3 If FLD= was not specified (free format) and no name= was specified, the program estimated the number of variables (n) on the record and generated variables RI.FLD[1]RI.FLD[n]. This can not be duplicated in this version; the user must specify the maximum number of variables to be obtained from any data record (judicious over estimation should not cause any problems). If the highest field to be referenced is 15, then FIELDS=1(15) should be specified. Any references to RI.FLD[x] must be revised to RECI.NFIELD[x], or to RI.FIELDx. In general, all references to RI.FLD should be changed to RECI.NFIELD. This can usually be done quite easily with any editor with search and replace capabilities.

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

Cube Voyager Reference Guide 419

Matrix Program Using the Matrix program

Mode and destination choice General notes

Introduction to choice modeling

Beginning with version 4.1 of Cube Voyager, the XCHOICE control statement replaces the CHOICE control statement for implementing logit choice models. XCHOICE implements the same logit model structures as the original CHOICE statement but improves choicemodel run times. A choice model implemented with XCHOICE should run significantly faster than the same model implemented with CHOICE. The CHOICE command statement continues to function as in prior versions. 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. Use the XCHOICE command statement whenever developing new choice models in the Matrix program. 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 detailed changes please refer to XCHOICE on page 468. The XCHOICE (CHOICE prior to v4.1) command in Cube Voyager scripting provides powerful extensions to the core language designed to allow complex logit choice models to be specified easily. 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.

420 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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

Cube Voyager Reference Guide 421

Matrix Program Using the Matrix program

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

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

Introduction

This section introduces a straightforward example of an aggregate demand model. Suppose that in a transport system there are just two discrete competing modescar and public transport (PT)

422 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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

Structure of absolute logit model

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.
Logit Choice model

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

Cube Voyager Reference Guide 423

Matrix Program Using the Matrix program

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:

424 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

the composite utility (or logsum) is:

and the equations for demand by alternative (Dcar, etc.) are as given above.
Scale parameter (cost-based models)

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

Cube Voyager Reference Guide 425

Matrix Program Using the Matrix program

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.

Logit model 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 script for cost-based model

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

426 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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.

Cube Voyager Reference Guide 427

Matrix Program Using the Matrix program

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 models 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 script for utility-based model

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

428 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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

Cube Voyager Reference Guide 429

Matrix Program Using the Matrix program

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.

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

430 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Introduction

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.

Structure of incremental logit model

This model is developed, both using costs and utilities below.

Incremental logit choice model

The model inputs are base demand by mode (Dcar, Dpt), base costs by mode (Ccar, Cpt) and forecast costs by mode (Ccar, Cpt). The change in cost is denoted by DCcar and DCpt where:

Base probabilities are denoted by Pcar and Ppt where:

Cube Voyager Reference Guide 431

Matrix Program Using the Matrix program

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 (Dcar, Dpt) 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:

432 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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 script for cost-based model

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

Cube Voyager Reference Guide 433

Matrix Program Using the Matrix program

STARTMW = 40

Alternative script using cost 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 script for utility-based models

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

434 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input base demand by BASEDEMANDMW = 10, 11, ; Input base costs by BASEUTILSMW = 20, 21, ; Input forecast costs UTILITIESMW = 30, 31, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL car pt, ; Forecast incremental SPLITCOMP = 7, ; Working matrices STARTMW = 50

mode mode by mode

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

Cube Voyager Reference Guide 435

Matrix Program Using the Matrix program

Working matrices STARTMW = 100

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

Introduction

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 of hierarchical logit model

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.

436 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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.
Cost-based examples of hierarchic logit models

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 models sensitivity to cost increases down the hierarchy.
Matrix script

Cube Voyager Reference Guide 437

Matrix Program Using the Matrix program

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

438 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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.
More complex absolute hierarchical models

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 of a large absolute hierarchical logit model Matrix script illustrating the complex example

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,

Cube Voyager Reference Guide 439

Matrix Program Using the Matrix program

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

Utility-based examples of hierarchic logit models Scale parameter in utility-based models

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.
Matrix script illustrating two-level hierarchy

440 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

Using the tree structure shown in Structure of hierarchical logit model on page 436 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.

Cube Voyager Reference Guide 441

Matrix Program Using the Matrix program

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.
Matrix script illustrating the complex example

A more complex utility-based example uses the model structure illustrated in Structure of a large absolute hierarchical logit model on page 439. 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

442 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

In this example a scale parameter of 0.4 is applied to the all-car subnest; also 0.667 to the all-PT sub-nest and 0.75 to the train sub-nest.

Destination choice
This section describes the destination-choice model. Topics include: Introduction Matrix script

Introduction

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 of destination choice model

For the absolute choice model, the probability of choosing destination zone j from origin zone i is given by Pij:

Cube Voyager Reference Guide 443

Matrix Program Using the Matrix program

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

444 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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.

Mode and destination choice

This section discusses the mode-and-destination-choice model. Topics include: Introduction Mode followed by destination choice Destination followed by mode choice

Introduction

The XCHOICE command supports both mode and destination choice in the same structure. This section considers first mode followed by destination choice, then destination followed by mode choice.

Cube Voyager Reference Guide 445

Matrix Program Using the Matrix program

Which form of model is appropriate for a study is determined during model calibration. The values of scale parameter for the various choice nests, which reflect sensitivity to cost differences, determine which form is used.
Mode followed by destination choice

Consider first an 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).

Mode followed by destination choice

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).
Matrix script

The script extract below is similar to previous examples shown in Incremental logit model on page 430 and Destination choice on page 443. 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,

446 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

; ; ; ; ; ; ; ; ; ;

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

Destination followed by mode choice

Now consider the case of destination followed by mode choice. The figure illustrates such a system with two modes, car and PT, and 100 destination zones (labelled d1, d2,..., d100).

Destination followed by mode choice

The total input demand is first by destination (into a matrix), which is then split by mode (giving two matrices representing car and PT demand).

Cube Voyager Reference Guide 447

Matrix Program Using the Matrix program

Matrix script

Starting from the top, the model structure specification splits the total demand by destination. The mode-choice sub-nests has scale parameters of 0.5, and the intermediate matrix is identified by the name distribution. This name, distribution, is then used as the link (or input) to the lower choice nest.
; Destination followed by mode choice model XCHOICE, ; List choices ALTERNATIVES = car pt, ; Input base demand and utility-difference matrices BASEDEMANDMW = 11,12, DUTILSMW = 16,17, ; Forecast demand matrices by mode ODEMANDMW = 21,22, ; Model Structure ; Destination choice DESTSPLIT = TOTAL 0.5 distribution, ; Mode choice SPLIT = distribution car pt, ; Working matrices STARTMW = 50

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

Availability of choices

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

448 Cube Voyager Reference Guide

Matrix Program Using the Matrix program

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.
Applying choice models to selected parts of matrices

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

Cube Voyager Reference Guide 449

Matrix Program Using the Matrix program

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 subkeyword should be specified immediately after the DESTSPLIT keyword in order to include or exclude the required zones.
Practical considerations: Incremental models

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 430, where, if Pcar=0 then Pcar=0 whatever costs are given. If this effect is a problem, then the modelling approach should be reviewed.
Practical considerations: Scale parameters

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 models sensitivity to cost increases down the hierarchy. Where these conditions are not met, an error message will be output.

450 Cube Voyager Reference Guide

Matrix Program Control statements

Control statements
The following control words are available in the Matrix program.
Control word ABORT ARRAY BREAK BSEARCH CALL CHOICE COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FREQUENCY GOTO IF ... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LOOKUP LOOP ... ENDLOOP PARAMETERS PRINT PRINTROW RENUMBER REPORT SET Description Abort current program Set arrays and values Break out of current process Finds a key or set of keys in a sorted array, or series of sorted arrays using a binary search. Call users dll (external process) Implement logit choice models (prior to v4.1) Compute variables from expressions Continue at end of loop statement Terminate current program Input files Output files Set path for temporary files Fill work matrices Accumulate distributions of one matrix versus another Immediate jump to :label Define IF ENDIF block Define a loop for destination zones (J) Define lookup tables (see Chapter 3, General Syntax) Define user controlled loop Set static parameters Print variable values Print a row of a matrix (see Chapter 3, General Syntax, for details) Set zone renumber specifications Select standard reports Set multiple variables/arrays to same value

Cube Voyager Reference Guide 451

Matrix Program Control statements

Control word SORT WRITE XCHOICE

Description Sort user arrays Writes records to a DBF file defined by RECO Implement logit choice models (starting at v4.1)

ABORT
Programs: Distribution, Fratar, Generation, Matrix

Aborts the entire run. MSG 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.
Keyword MSG |S| Description Optional message that can be printed when the program terminates.

Example
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

ARRAY
Programs: Distribution, Fratar, Generation, Matrix

Declares user single and multi-dimension arrays. TYPE= t, ARRAYNAME=n, ARRAYNAME=n1[,n2[,n3]...]]]

452 Cube Voyager Reference Guide

Matrix Program Control statements

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.

ARRAY keyword
Keyword ARRAYNAME |I,...| Description 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.

Cube Voyager Reference Guide 453

Matrix Program Control statements

ARRAY keyword
Keyword TYPE S Description 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 follows by the maximum string size; but any numeric value other than 1, 2 or 4 will automatically be cast as string. 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: arrayname.type - a string that is the same as in the TYPE keyword arrayname.dimension - the number of dimensions arrayname.size[] - 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.

454 Cube Voyager Reference Guide

Matrix Program Control statements

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.

Cube Voyager Reference Guide 455

Matrix Program Control statements

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

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

456 Cube Voyager Reference Guide

Matrix Program Control statements

IF (condition) BREAK ; jump to LOOP L3= ENDJLOOP LOOP L3=L2,L2+5 IF (condition) BREAK; ; jump to ABC= ENDLOOP ABC=... ENDLOOP

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.

Example
ARRAY MYARRAY=100, YOURARRAY=100

Cube Voyager Reference Guide 457

Matrix Program Control statements

some code to populate the arrays SORT ARRAY=MYARRAY,YOURARRAY BSEARCH MYARRAY=32, YOURARRAY=(MYARRAY[j]*3)

Example
FILEI ARRAY BSEARCH DBI[1]=MYDBF, AUTOARRAY=FIELD1 SORT=FIELD1 MYARRAY=100, YOURARRAY=100 DBA.1.FIELD1='875'

CALL
Programs: Distribution, Fratar, Generation, Matrix

Executes an external routine. DLL 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.
Keyword DLL |S| Description 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

458 Cube Voyager Reference Guide

Matrix Program Control statements

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: Saving the MW value from the passed structure: the suggested way if MWs need not be allocated, and there are many references to MWs. Saving the address returned from pfVarFind (MW...): the required way if MWs need to be allocated. Indirect referencing to MW from the passed structure; an efficient way if MWs need not be 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

Cube Voyager Reference Guide 459

Matrix Program Control statements

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, F is a 1 if the message is to be written to the error file E is the level of the message (0,1,2=Message, Warning, Fatal), N is the number of new lines to print before printing the message.
sMmessage The message string (ASCIIZ) to be printed; it may

contain any normal printer characters, including \n, \r,\f,\t etc.

Example
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);

460 Cube Voyager Reference Guide

Matrix Program Control statements

/* 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; }

CHOICE
Program: Matrix

Implements a logit-choice model.

NOTE: XCHOICE is the preferred command statement for

implementing logit-choice models. ALTERNATIVES BASECOSTS BASEDEMAND BASEUTILS COSTS DCOSTS DEMAND DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE) DUTILS OCOMPCOST OCOMPUTIL ODEMAND

Cube Voyager Reference Guide 461

Matrix Program Control statements

SPLIT (COEFF, SPLITINTO) STARTMW UTILITIES 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 costbased or utility-based models: CHOICE keywords: Cost-based models CHOICE keywords: Utility-based models
CHOICE keywords: Cost-based models
Keyword ALTERNATIVES Description 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. 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 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. 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 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.

BASECOSTS

COSTS

462 Cube Voyager Reference Guide

Matrix Program Control statements

CHOICE keywords: Cost-based models (continued)

Keyword DEMAND Description 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. The DESTSPLIT clause is used when the nest in the hierarchy corresponds to a destination choice model. It divides the 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. 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,

DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE)

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

ODEMAND

Cube Voyager Reference Guide 463

Matrix Program Control statements

CHOICE keywords: Cost-based models (continued)

Keyword SPLIT (COEFF, SPLITINTO) Description 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, 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 origindestination 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

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.

464 Cube Voyager Reference Guide

Matrix Program Control statements

CHOICE keywords: Utility-based models

Keyword ALTERNATIVES Description 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. 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. 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 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. Use the DESTSPLIT clause when the nest in the hierarchy corresponds to a destination-choice model. It divides the 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,

BASEDEMAND

BASEUTILS

DESTSPLIT (INCLUDE, EXCLUDE)

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.

Cube Voyager Reference Guide 465

Matrix Program Control statements

CHOICE keywords: Utility-based models (continued)

Keyword DUTILS Description 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. 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. 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.

OCOMPUTIL

ODEMAND

466 Cube Voyager Reference Guide

Matrix Program Control statements

CHOICE keywords: Utility-based models (continued)

Keyword SPLIT Description 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.

Cube Voyager Reference Guide 467

Matrix Program Control statements

CHOICE keywords: Utility-based models (continued)

Keyword STARTMW Description 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. 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.

UTILITIES

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 475. ALTERNATIVES COSTSMW BASECOSTSMW DCOSTSMW UTILITIESMW BASEUTILSMW DUTILSMW

468 Cube Voyager Reference Guide

Matrix Program Control statements

DEMANDMW DEMAND BASEDEMANDMW ODEMANDMW SPLITCOMP SPLIT (COEFF, SPLITINTO SPLITCOMP) DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE) STARTMW 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
XCHOICE keywords: Cost-based models
Keyword ALTERNATIVES Description 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. 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 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.

BASECOSTSMW

Cube Voyager Reference Guide 469

Matrix Program Control statements

XCHOICE keywords: Cost-based models (continued)

Keyword COSTSMW Description 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 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. The demand value for a destination-choice or mode- and destination-choice model. The demand matrix for a pure mode-choice model. Use the DESTSPLIT keyword when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand 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. 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,

DEMAND DEMANDMW DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE)

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 EXCLUDE = 88-100, = 0.3, SPLITINTO = allTrips,

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

470 Cube Voyager Reference Guide

Matrix Program Control statements

XCHOICE keywords: Cost-based models (continued)

Keyword SPLIT (COEFF, SPLITINTO, SPLITCOMP) Description 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, 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,

The SPLITCOMP subkeyword specifies the working matrix to store the composite costs or composite utilities for the nest defined by its parent SPLIT keyword.

Cube Voyager Reference Guide 471

Matrix Program Control statements

XCHOICE keywords: Cost-based models (continued)

Keyword SPLIT (continued) Description 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

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.

XCHOICE keywords: Utility-based models

Keyword ALTERNATIVES Description 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. 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.

BASEDEMANDMW

472 Cube Voyager Reference Guide

Matrix Program Control statements

XCHOICE keywords: Utility-based models (continued)

Keyword BASEUTILSMW Description 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 DEMANDMW DESTSPLIT (INCLUDE, EXCLUDE) The demand value for a destination-choice or mode- and destination-choice model. The demand matrix for a pure mode-choice model. Use when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand 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 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. 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.

ODEMANDMW

Cube Voyager Reference Guide 473

Matrix Program Control statements

XCHOICE keywords: Utility-based models (continued)

Keyword SPLIT Description 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. 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.

474 Cube Voyager Reference Guide

Matrix Program Control statements

XCHOICE keywords: Utility-based models (continued)

Keyword STARTMW Description 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. 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.

UTILITIESMW

Summary of syntax usage differences between XCHOICE 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 modeand 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

Cube Voyager Reference Guide 475

Matrix Program Control statements

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:

476 Cube Voyager Reference Guide

Matrix Program Control statements

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.

COMP
Programs: Distribution, Fratar, Generation, Matrix

Computes a variable, matrix, or matrix element.

VAR=expression MW[]=expression (INCLUDE EXCLUDE)

Cube Voyager Reference Guide 477

Matrix Program Control statements

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 keywords
Keyword MW Subkeyword |KN| Description 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 programs 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 loops 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

EXCLUDE

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

478 Cube Voyager Reference Guide

Matrix Program Control statements

COMP keywords (continued)

Keyword MW Subkeyword INCLUDE |IP| Description 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| VAR 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 -- dont 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.

Cube Voyager Reference Guide 479

Matrix Program Control statements

Supported expressions

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.
Variable MW[Rexpression] Description 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. 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.name

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. Special cases for the above two MI formats. 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. Transpose operation can only be applied to binary data. 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.

MI.n.name.T MI.n.matnum.T

ZI.n.name

480 Cube Voyager Reference Guide

Matrix Program Control statements

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, sqrtsee 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.
Matrix function descriptions
Function1 ARRAYSUM(array_name) LOWCNT Description Returns sum of an array (see Examples on page 555). 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

Cube Voyager Reference Guide 481

Matrix Program Control statements

Matrix function descriptions (continued)

Function1 LOWEST (mw,#) LOWEST(mw,#,lo,hi) LOWEST(mw,#,lo,hi,z,z,...) Description Sum of lowest # cells Sum of lowest # cells where lo>=value<=hi 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 on page 555). 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.

482 Cube Voyager Reference Guide

Matrix Program Control statements

Matrix function descriptions (continued)

Function1 ROWADD(d,s1...sn) Description Add matrix mw[1] + mw[sn] into mw[d] Same as:
MW[d] = MW[s1] + MW[s2] + MW[sn]

ROWAVE(mw) ROWAVE(mw,lo,hi) ROWCNT(mw) ROWCNT(mw,lo,hi)

Average cell value for nonzero values Average cell value for nonzero values, including only cells where: lo>=value<=hi Number of cells with nonzero values Number of cells with nonzero values, but include only cells where: lo>=value<=hi (this can include 0). Divide MW[d] by MW[s] making all divided-byzero cells equal to 0. Same as:
JLOOP IF (MW[s] == 0) MW[d] = 0 ELSE MW[d] = MW[d] / MW[s] ENDIF ENDJLOOP

ROWDIV(d,s)

ROWFAC (mw,fac)

Factors the row by fac. Same as:

MW[mw] = MW[mw] * fac

ROWFIX(mw) ROWFIX(mw,n)

Integerize mw (start at column intrazonal + 1, with rounding factor = 0); Integerize mw (start at column n, w/ rounding factor = 0)

Cube Voyager Reference Guide 483

Matrix Program Control statements

Matrix function descriptions (continued)

Function1 ROWFIX(mw,n,rnd) Description 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) ROWMIN(mw) ROWMPY(d,s) Maximum value in the row Minimum value in the row Multiply MW[d] by MW[s] Same as:
MW[d] = MW[d] * MW[s]

484 Cube Voyager Reference Guide

Matrix Program Control statements

Matrix function descriptions (continued)

Function1 ROWREAD(MW#, MATI#, I, M) Description Reads a random row from the input matrix 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) ROWSUM(mw,lo,hi)

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

Cube Voyager Reference Guide 485

Matrix Program Control statements

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

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.
Example
LOOP L1=1,3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ; no more processing for this origin zone LOOP L2=K1,K2,KINC

486 Cube Voyager Reference Guide

Matrix Program Control statements

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

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.
Example
IF (expression) EXIT

FILEI
NOTE: See FILEI on page 48 for general information about FILEI

and for important limitations when using Application Manager.

Programs: Distribution, Fratar, Generation, Matrix

Selects input data files. DBI (FIELDS name SORT DELIMITER AUTOARRAY MAXRECS JOINTODBI(JOINTOFIELDS) AUTOMDARRAY INDEXES ARRAYFIELDS) LOOKUPI MATI (PATTERN FIELDS AUTOMDARRAY MI I J RESTRICTION) RECI (FIELDS name SORT DELIMITER MAXERRS LISTERRS MAXRECS MAXSCAN)

Cube Voyager Reference Guide 487

Matrix Program Control statements

ZDATI (Z SELECT name (DEFAULT) AVE AVEX0 CNT FIRST LAST MAX MIN SUM) Note for v4.0 and later: Significant changes in RECI/RECO processing have been made from v3.2.x series. If running scripts developed under v3.2.x or earlier and using the RECI/RECO keywords you may need to make some slight modification to your scripts for proper processing. Refer to the descriptions below for the updated coding and comments on the processing.
FILEI input data is normally entered in either matrix format or zonal

vector format. Matrix data is read dynamically (at the start of each Iloop), 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

488 Cube Voyager Reference Guide

Matrix Program Control statements

one row having zones columns (users choice, it doesnt 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, EMME/2 matrices stored in an EMME/2 data bank file, 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. If MATI specifies an EMME/2 data bank file, then the file name must be emme2ban with no file extension. The Matrix program will not recognize any other file name as an EMME/2 data bank file. In this case, input matrices referenced in the script can be referenced by their matrix number in the bank just as they are in a binary Cube Voyager matrix file. 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). If ZDATI specifies an EMME/2 data bank file, the Matrix program can read the scalar and vector matrices stored in the EMME/2 data bank file as zonal data records. To specify an EMME/2 data bank file, the file name must be emme2ban with no file extension. The Matrix program will not recognize any other file name as an EMME/2 data bank file.

Cube Voyager Reference Guide 489

Matrix Program Control statements

FILEI keywords
Keyword DBI Subkeyword |KF9| Description 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 singlecolumn 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.

490 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword DBI (continued) Subkeyword Description The following special variables are available for all file formats: DBI.# String variable containing the full data record 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.#.NAME Name of the field DBI.#.TYPE Type of field (either N for numeric or C for character DBI.#.NFIELD Numeric value for the field (0 if DBI.#.TYPE=C) 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. See More on DBI on page 510. 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.

Cube Voyager Reference Guide 491

Matrix Program Control statements

FILEI keywords (continued)

Keyword DBI Subkeyword AUTOMDARRAY |S| Description FILEI DBI[]=, TYPE=, AutoMDArray=, Indexes=fld-size,fldsize,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. With the Indexes keyword, some of the 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=fld110,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:

492 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword DBI Subkeyword AUTOMDARRAY (continued) |S| Description 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.

Cube Voyager Reference Guide 493

Matrix Program Control statements

FILEI keywords (continued)

Keyword DBI Subkeyword DELIMITER |S2| Description 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.

494 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword DBI Subkeyword FIELDS |IPV| Description 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.

Cube Voyager Reference Guide 495

Matrix Program Control statements

FILEI keywords (continued)

Keyword DBI Subkeyword JOINTOFIELDS |SV8| Description 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.

496 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword DBI Subkeyword NAME |IP| Description 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 nothingor (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. 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.

LOOKUPI

|FKV999|

Cube Voyager Reference Guide 497

Matrix Program Control statements

FILEI keywords (continued)

Keyword MATI Subkeyword |KFV20| Description 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. If the input file name is specified as emme2ban with no file extension, then the Matrix program will recognize the file as an EMME/2 data bank file. You can reference input matrices from an EMME/2 data bank file in the script by matrix number. For example if FILEI MATI[1]=emme2ban, then MW[1]=mi.1.10 in the script would place matrix values from MF10 from the EMME/2 data bank into the internal working matrix MW[1] for each I-zone processed. See Example of FILEI statements on page 515 for an example of MATI usage when accessing an EMME/2 data bank file. MATI 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.

498 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword MATI Subkeyword AUTOMDARRAY (continued) |S| Description Selected I's and J's can be loaded into a smaller array. For example: FILEI MATI=xxx, AutoMDArray=name2, MI=4, I=11-15,2125, 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

Cube Voyager Reference Guide 499

Matrix Program Control statements

FILEI keywords (continued)

Keyword MATI Subkeyword FIELDS |S| Description 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-endnumflds) 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.

500 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword MATI Subkeyword PATTERN |S| Description 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

Cube Voyager Reference Guide 501

Matrix Program Control statements

FILEI keywords (continued)

Keyword MATI Subkeyword PATTERN (continued) Description This method allows Cube Voyager to read 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 511.

502 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword RECI Subkeyword |KF| Description Name of a DBF file, an element in a multidatabase file, or an ASCII record file with either delimited or fixed format records. NOTE: Cube Voyager may 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.

Cube Voyager Reference Guide 503

Matrix Program Control statements

FILEI keywords (continued)

Keyword RECI (continued) Subkeyword Description The following special variables are 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 513 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 494. Usage of DELIMITER is the same under both keywords.

504 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword RECI Subkeyword FIELDS |IPV| Description Only available in v4.0 and beyond. 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 15, 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] 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 reference as RECI.NFIELD[#], RECI.CFIELD[#] or as RI.FIELD# in stack statements. 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. 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. Places a limit on the number of records to be read in from the RECI file. Default value is no limit.

RECI

LISTERRS

|?|

RECI

MAXERRS

|I|

RECI

MAXRECS

|I|

Cube Voyager Reference Guide 505

Matrix Program Control statements

FILEI keywords (continued)

Keyword RECI Subkeyword MAXSCAN |I| Description 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. 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. 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. 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.

RECI

NAME

|IP|

RECI

SORT

|S5|

ZDATI

|KFV10|

506 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword ZDATI (continued) Subkeyword Description The file format can be: ASCII, DBF, MDB, EMME/2 data bank, 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, EMME/2 data bank, 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. If the file is a DBF, MDB, or a Cube 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. 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. If the file is an EMME/2 data bank file, then the file name must be emme2ban with no file extension. The program will not recognize any other file name as an EMME/2 data bank file. EMME/2 data bank files store zonal data as a vector matrix, referred to as either an origin-based matrix (MO#) or a destination-based matrix (MD#) where # is the reference matrix number. Bank files store scalar data (or constants) as a scalar matrix, referenced as MS#. To reference zonal data from an input Emme2 data bank file in the script, use the standard zi.#.name convention, where name is the EMME/2 bank matrix name for the origin, destination, or scalar matrix. See Example of FILEI statements on page 515 for an example of ZDATI usage when accessing an EMME/2 data bank file.

Cube Voyager Reference Guide 507

Matrix Program Control statements

FILEI keywords (continued)

Keyword ZDATI (continued) Subkeyword Description In general, string valued arrays are not supported at this time. ZDATI is the one exception to this rule with some limitations. ZI fields that have string values are valid but only up to 7 characters in length. AVE AVEX0 CNT DEFAULT |SV| |SV| |SV| |R| Average of all records. Average of all records, where the value from the file records is not 0. Count of the records that contain the variable. 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 ZDATI ZDATI ZDATI FIRST LAST MAX MIN |SV| |SV| |SV| |SV| Directly from the record from the FILEI with the lowest index []. Directly from the record from the FILEI with the highest index []. Maximum value of all the records. Minimum value from all the records.

ZDATI ZDATI ZDATI ZDATI

508 Cube Voyager Reference Guide

Matrix Program Control statements

FILEI keywords (continued)

Keyword ZDATI Subkeyword name |S| Description 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 doesnt 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. 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

SELECT

|S3|

Cube Voyager Reference Guide 509

Matrix Program Control statements

FILEI keywords (continued)

Keyword ZDATI Subkeyword Z |S| Description 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.
More on 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.

510 Cube Voyager Reference Guide

Matrix Program Control statements

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: 0 A match was found. 1 An error in setup occurred. 2 A match was not found, and DBI.#.RECNO is set to the record that is above the R selections. 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 on page 559 and Example 6 on page 560 for examples of DBI processing.

NOTE: You can create and populate arrays with just a FILEI DBI

statement; you do not need DBIRead functions.

More on MATI 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

Cube Voyager Reference Guide 511

Matrix Program Control statements

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 2 3 4 37.3912 167.1612 13.0612 31.6512 54.5413 269.2513 22.1213 54.2813 6.8414 35.5314 4.8514 12.2914 14.5015 75.1215 10.6815 31.3815

512 Cube Voyager Reference Guide

Matrix Program Control statements

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 FILEO MATO=temp1.mat PAR ZONES=4 MW[1]=mi.1.1 ENDRUN PATTERN=IJ:V MO=1 FIELDS=#1,0,2-5

More on 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)=1010, 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

Cube Voyager Reference Guide 513

Matrix Program Control statements

would sum the values of the variable VAR1 and once all records have been read (I=1) 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],'..',

514 Cube Voyager Reference Guide

Matrix Program Control statements

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

Example of FILEI statements

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

Cube Voyager Reference Guide 515

Matrix Program Control statements

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

These statements show an example of getting matrices from an EMME/2 data bank file:
RUN PGM=MATRIX FILEI MATI[1]="emme2ban" FILEO MATO[1]="M2_to_Voy.mat" mo=1-8 DEC=8*9 ; get matrices mf104 to mf111 from emme2ban ; and put into work matrices 1 to 8 MW[1]=MI.1.104 MW[2]=MI.1.105 MW[3]=MI.1.106 MW[4]=MI.1.107 MW[5]=MI.1.108 MW[6]=MI.1.109 MW[7]=MI.1.110 MW[8]=MI.1.111 ENDRUN

516 Cube Voyager Reference Guide

Matrix Program Control statements

These statements show an example of getting zonal vector and scalar matrices from an EMME/2 data bank file:
RUN PGM=MATRIX FILEI ZDATI[1]="emme2ban" FILEO RECO[1]="emmeVector2Voy.dbf" FIELDS=ms10(5.2),mo20(6.3),mo21(6.3),mo23(6.3), mo22(6.3),mo25(6.3),md22(6.3),md23(6),md25(6.3),md80(6), md81(6),md82(6) report zdat=t zones=900 ro.ms10=zi.1.ms10 ro.mo20=zi.1.mo20 ro.mo21=zi.1.mo21 ro.mo23=zi.1.mo23 ro.mo22=zi.1.mo22 ro.mo25=zi.1.mo25 ro.md22=zi.1.md22 ro.md23=zi.1.md23 ro.md25=zi.1.md25 ro.md80=zi.1.md80 ro.md81=zi.1.md81 ro.md81=zi.1.md82 write reco=1 ENDRUN

FILEO
Programs: Distribution, Fratar, Matrix

Outputs data files. MATO (FORMAT MO NAME DEC PATTERN DELIMITER FIELDS MAXFIELDS) PRINTO (APPEND) RECO (FIELDS EXCLUDERECI CFORM FORM REPORT) 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.

Cube Voyager Reference Guide 517

Matrix Program Control statements

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.
FILEO keywords
Keyword MATO Subkeyword |KFV20| Description 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 reference an existing EMME/2 data bank file in order to store matrix data into the existing data bank. EMME/2 data bank files must be named emme2ban. The program will overwrite an EMME/2 data bank file in the format specified by FORMAT if the name is not emme2ban. The data bank file must exist already. If it does not exist, the program will not create the data bank file.

518 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword DEC |SV*| Description Specifies numeric format of values in the output matrix. Specify a separate DEC for each MO. Valid entries vary by file format: Cube Voyager files Valid entries include: 0 through 9 Writes output matrix cells in fixedpoint 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 DEC=5, Cube Voyager stores 1,258,756.33715 as the integer 1,258,756,337, which translates to 1,258,756.337. S Writes output matrix cells in single-precision floating-point format (4 bytes). This format provides seven to eight significant digits. Additional digits may change from their original value when a program reads them. Certain matrices might require more precision. D Writes output matrix cells in double-precision floating-point format (8 bytes). This format provides 15 to 16 significant digits. If you do not specify DEC, 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. For example, for a cell computed as 10/3, the result is 3.33333333... to sixteen digits. If stored as fixed-point with DEC=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 DEC=2, the result is 3.33, and requires two bytes to store. If stored as single precision with DEC=S, the result is accurate to about seven digits, and requires four bytes to store. If stored as double precision with DEC=D, the result requires eight bytes to store.

Cube Voyager Reference Guide 519

Matrix Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword DEC (continued) Description MINUTP or Tranplan files Do not set DEC. The program ignores the DEC 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 levelof-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 DEC=S to write a single-precision matrix. However, you cannot use such a matrix as input to Cube Voyager. TRIPS files Set DEC to the number of digits after the decimal point (0 to 9). The program stores numbers as integers with implied decimal. If you set DEC to S or D, the program treats as DEC=0. If a numbers integer value with implied decimal exceeds the maximum integer value (2,147,483,647), the program substitutes the maximum integer value for that number. Text files Set DEC to the number of decimal places to format in text records. If you do not code DEC, 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 DEC as for Cub Voyager files. However, the program uses the DEC[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 records matrix data values, the program uses DEC[#] appropriately.

520 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword DEC (continued) Description EMME/2 data bank files Do not set DEC. The program stores values in singleprecision floating-point format in the data bank file. 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 doubleprecision 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, ' '.

Cube Voyager Reference Guide 521

Matrix Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword FIELDS |IV4| Description 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

MATO FORMAT |S|

I will always be in 1-4 J will always be in 5-8 V will be in 9-14,15-20,21-26 ... 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 ... 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 ... 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

PATTERN=I:JVM FIELDS=4,4,6,2

PATTERN=IJM:V FIELDS=4,4,0,8

Type of file written:

Default value is TPP, unless you set PATTERN. With PATTERN set, the default value is TXT. Ignored if MATO is set to emme2ban. In that case, the program updates an EMME/2 data bank file.

522 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword MAXFIELDS |I| Description 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, DEC=6*0, DEC[3]=2

Cube Voyager Reference Guide 523

Matrix Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword MO |IVP| Description 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. When writing output matrices to an EMME/2 data bank file, the program only writes the specified matrices. For other formats, the program starts output matrices at 1 and writes through the highest MO index. For example, with MO=1,8, MO[200]=7, the program will write 200 matrices, most set to 0. If writing to an EMME/2 data bank output file, the program will write MF1, MF2, and MF200. 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. For EMME/2 data bank output files, specifies names of output matrices, which you can use for internal documentation. For such files, the program stores the first four characters of NAME into the bank short name and the entire name into the bank long description. See Example: FILEO MATO for EMME/2 file on page 528 for an example of writing matrices to an EMME/2 data bank file, specifying matrix numbers and names.

524 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword PATTERN |S| Description 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 501. 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). Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=#. See APPEND under PRINT on page 66. 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 553. Currently, DBF, MDB and EMME/2 data bank files 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. If specifying an EMME/2 data bank file, the file name must be
emme2ban. The program will write any other file name to binary

PRINTO PRINTO RECO APPEND

|KF| |?| |KF20|

format and not in bank-file format. The bank file must exist already. If it does not exist, the program will not create the bank file. You can use RECO to write scalar or vector matrices into an EMME/2 data bank file. 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. Used to exclude selected fields when using the RECI.ALLFIELDS include macro described under FIELDS above.

RECO

EXCLUDERECI

|S|

Cube Voyager Reference Guide 525

Matrix Program Control statements

FILEO keywords (continued)

Keyword RECO Subkeyword FIELDS |S| Description 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 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. If specifying an EMME/2 data bank file with RECO, the format is: RECO=emme2ban FIELDS=Mx#, where x=S, O, or D, and # is a valid number for the data bank. EMME/2 references scalar matrices as MS#, origin matrices as MO#, and destination matrices as MD#. Cube Voyager usually refers to these as constants and zonal arrays. When the output file is an EMME/2 data bank, the program ignores any FIELDS not named with this format (Mx#). If you specify MO or MD, you must also specify a Z=variable to indicate for which zone to store the data. If using RECO in conjunction with matrix processing, a logical variable for Z would be I (Z=I) if there is one RECO per zone. See the Example: FILEO RECO for EMME/2 file on page 529 for an example of writing record data to an EMME/2 data bank file, specifying fields and field names.

526 Cube Voyager Reference Guide

Matrix Program Control statements

FILEO keywords (continued)

Keyword RECO Subkeyword FORM |R| Description 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 9but d must be at least 2 less than w; the default is 10.2. NOTE: Variable-specific formats can specify larger values of dup to 18, but d must still be at least 2 less than w. RECO NAME |S| Optional. Used in conjunction with the FIELDS subkeyword. For output to EMME/2 data bank files, specifies name in the data bank for scalar and vector matrices. Example:
reco[1] =..\emme2\emme2ban Z=I, fields=MS1 MO1 MD1 name=ms1 mo1 'md1 term time'

For this example, the script must set the variables .MS1, RO.MD1, and RO.MD2. Upon encountering each WRITE RECO=1 statement in the script, the program would update the data bank, changing the names as defined. 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. Optional. Used in conjunction with the FIELDS subkeyword. Required when writing MO or MD matrices. For output to EMME/2 data bank files, specifies zone for which the program stores the data.

RECO

|S|

Example: 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}

Cube Voyager Reference Guide 527

Matrix Program Control statements

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

Example: FILEO MATO for EMME/2 file

These statements demonstrate FILEO MATO to an EMME/2 data bank file.

RUN PGM=MATRIX FILEI MATI[1] = "Purpose_Trips.MAT" FILEI MATI[2] = "HWY_SKIMS.MAT" FILEI MATI[3] = "PT_SKIMS.MAT" FILEO MATO[1] = " EMME2BAN", MO=1-4,9-17,MO[17]=101-106,201-220,MO[171]=221-240,MO[191]=5-7,MO[206]=8, NAME=mf01,mf02,mf03,mf04,mf05,mf06,mf07,mf08,mf09,mf10,mf11,mf12,mf13, NAME=mf17,mf18,mf18,mf20,mf21,mf22,mf23,mf24,mf25,mf26,mf27,mf28,mf29, mf30,mf31,mf32,mf33,mf34,mf35,mf36,mf37,mf38,mf39,mf40,mf41,mf42, NAME[191]=mf191,mf192,mf193,NAME[206]=mf206 ; get mf01-mf04,mf191-mf193,mf206,mf05-mf13 FILLMW MW[1]=mi.1.1(9) MW[10]=mi.1.11,15,19,21,22,23,25,27 ; get mf17-mf22 FILLMW MW[101]=mi.2.4(6) ;get mf23-mf42, mf171-mf190 FILLMW MW[201]=mi.3.1(40)

528 Cube Voyager Reference Guide

Matrix Program Control statements

ENDRUN

Example: FILEO RECO for EMME/2 file

These statements demonstrate FILEO RECO to an EMME/2 data bank file.

RUN PGM=MATRIX FILEO RECO[1] = " EMME2BAN", Z=I FIELDS=ms02,ms10,mo20,mo21,mo22,mo23,mo25,md22,md23, md25,md80,md81,md82 FILEI ZDATI[1] = "VECTORDATA.DBF" FILEI MATI[1] = "HWY_SKIMS.MAT" ;get mo20, mo21, mo23 FILLMW MW[1]=mi.1.1(3) JLOOP IF (I=J) ro.z=I ro.mo20=MW[1][I] ro.mo21=MW[2][I] ro.mo23=MW[3][I] ro.mo22=zi.1.MO22 ro.md22=zi.1.MD22 ro.mo25=zi.1.MO25 ro.md25=zi.1.MD25 ro.md23=zi.1.MD23 ro.md80=zi.1.MD80 ro.md81=zi.1.MD81 ro.md82=zi.1.MD82 ro.ms02=8 ;scalar ro.ms10=34.7 ;scalar WRITE RECO=1 ENDIF ENDJLOOP ENDRUN

Cube Voyager Reference Guide 529

Matrix Program Control statements

FILET
Programs: Distribution, Fratar, Matrix

Sets temporary file paths. PATH FILET is used to specify where various temporary files are to be written.
FILET keyword
Keyword PATH |KS| Description 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.

530 Cube Voyager Reference Guide

Matrix Program Control statements

Example
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

FILLMW
Programs: Distribution, Fratar, Matrix

Fill work matrices 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. 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 keyword
Keyword MW |s| Description Specifies the matrices to be moved directly from their source to the destination work matrices named on the keyword.

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

Cube Voyager Reference Guide 531

Matrix Program Control statements

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

FREQUENCY
Program: Distribution, Fratar, Matrix

Stratifies one matrixs values based upon the values of another. BASEMW RANGE REPORT TITLE VALUEMW

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.
FREQUENCY keywords
Keyword BASEMW |I| Description Work matrix number ( MW[ ] ) whose values will be used for the stratification (the time matrix for a trip length distribution).

532 Cube Voyager Reference Guide

Matrix Program Control statements

FREQUENCY keywords (continued)

Keyword RANGE |RP| Description 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. 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 for identifying the final report at the end of the application. Work matrix number ( MW[ ] ) whose values will be accumulated according to the values of BASEMW (the trip matrix for a trip length distribution).

REPORT

IP|

TITLE VALUEMW

|S| |I|

Example
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

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.

Cube Voyager Reference Guide 533

Matrix Program Control statements

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.
Example
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.
Example
GOTO buildhwy . . :buildhwy IF (expression) GOTO :buildhwy

; It is permissible to go backwards.

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. Lengthy IF expression solutions could be time consuming; it is suggested that they be used judiciously. Although IF expressions can be quite powerful for

534 Cube Voyager Reference Guide

Matrix Program Control statements

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

JLOOP ... ENDJLOOP

Programs: Distribution, Fratar, Generation, Matrix

Control a J loop for processing matrices.

Cube Voyager Reference Guide 535

Matrix Program Control statements

J INCLUDE EXCLUDE 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: If J is specified, establish values for J, Jend, and Jinc. Else set J=1, Jend=Zones, Jinc=1. If (J < 1 or J > Zones or Jend <1 or Jend > Zones) fatal termination. If (INCLUDE, and J fails INCLUDE) go to ENDJLOOP. If (EXCLUDE, and J meets EXCLUDE) go to ENDJLOOP. Next statement. at ENDJLOOP: Add Jinc to J. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. If (INCLUDE, and J fails INCLUDE) go to ENDJLOOP. 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

536 Cube Voyager Reference Guide

Matrix Program Control statements

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. JLOOP and ENDJLOOP keywords
Keyword J Jbeg Jend |I| Description Sets Jbeg, Jend and Jinc. Expression to initialize J; the value may not be less than 1, nor greater than Zones. 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. 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.

Jinc

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 ().
Example
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

Cube Voyager Reference Guide 537

Matrix Program Control statements

LOOP ... ENDLOOP

Programs: Distribution, Fratar, Generation, Matrix

Control a general variable loop. LVAR = 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: Initialize LVAR to Lbeg. Proceed to next statement. at ENDLOOP: If Lend not specified, jump to next statement. Compute Lend. If Linc not specified: Set Linc to 1 or -1 (if Lbeg and Lend are constants, and Lbeg > Lend) Else compute Linc. Add Linc to LVAR. Compare LVAR to Lend. If (Linc > 0 and LVAR > Lend) jump to statement after ENDLOOP If (Linc > 0 and LVAR <= Lend) jump to statement after LOOP If (Linc < 0 and LVAR < Lend) jump to statement after ENDLOOP If (Linc < 0 and LVAR >= Lend) jump to statement after LOOP

538 Cube Voyager Reference Guide

Matrix Program Control statements

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 and ENDLOOP keywords
Keyword LVAR Description 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. Numeric expression to initialize LVAR. 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). 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).

Lbeg Lend

Linc

Example
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

PARAMETERS
Program: Matrix

Cube Voyager Reference Guide 539

Matrix Program Control statements

Sets general parameters. MATVALCACHE MAXMW MAXSTRING TRAM ZONEMSG ZONES

PARAMETERS keywords
Keyword MATVALCACHE |KI| Description 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. 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. Establishes the maximum length for a string variables 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.

MAXMW

|KI|

MAXSTRING

|KI|

540 Cube Voyager Reference Guide

Matrix Program Control statements

PARAMETERS keywords (continued)

Keyword TRAM |KI| Description 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 most efficient amount would be (Zones * Zones * 8 * NumberTransposes), but that would probably be more than the computer has available in real memory. However, if Windows is controlling the computer, it will provide that much memory, but a portion of it might be virtual memory (temporary work space on disk). The use of virtual memory is disastrous in terms of efficiency for the transposing process. The program can not detect if the ram is real or virtual; therefore, care should be taken to not specify a value that is too large. In general, 4MB (4000000) should be adequate for most applications; 4000000 is the default, and should not normally be reset. 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.

ZONEMSG

|IK|

Cube Voyager Reference Guide 541

Matrix Program Control statements

Example
ZONES=3000

PRINT
Programs: Distribution, Fratar, Generation, Matrix

Format and print a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See PRINT on page 66 for details about the standard Cube Voyager statement.
Example
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

PRINTROW
Program: Distribution, Fratar, Matrix

Prints row of matrices. MW J TITLE FORM MAXPERLINE BASE1 See PRINTROW on page 73 for details about the standard Cube Voyager statement.
Example

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'

542 Cube Voyager Reference Guide

Matrix Program Control statements

Resulting Output:
J: I=1 1: 1 2 27: 27 50: 50 73: 73 96: 96 J: I=1 1: 1 2 33: 33 57: 57 90: 90 J: I=1 1: 1 2 11: 11 21: 21 31: 31 41: 41 51: 51 61: 61 71: 71 81: 81 91: 91 J: I=1 1: 1 2 31: 31 41: 41 51: 51 81: -91: 91 PRINTROW MW[1] form=LRD Tot=5,050 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 97 98 99 100 PRINTROW MW[2] form=LRD Tot=2,390 3 4 5 - - - - - -- - - - - - - - - - -- - - - - - - - - - 31 32 34 - 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 58 59 60 -- - - - - - - - - - -- - - - - - - - - - -- - - - - - 91 92 93 94 95 96 97 98 99 100 PRINTROW MW[1] form=6D base1= Tot=5,050 3 4 5 6 7 8 9 10 12 13 14 15 16 17 18 19 20 22 23 24 25 26 27 28 29 30 32 33 34 35 36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 62 63 64 65 66 67 68 69 70 72 73 74 75 76 77 78 79 80 82 83 84 85 86 87 88 89 90 92 93 94 95 96 97 98 99 100 PRINTROW MW[2] form=6D base1= Tot=2,390 3 4 5 -- -- -- -- -32 33 34 -- 36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 -- -- -- -- -- -- -- -- 90 92 93 94 95 96 97 98 99 100

RENUMBER
Programs: Fratar, Matrix

Renumbers (aggregate, split) zones for output matrices FILE ZONEO ZONES MISSINGZI MISSINGZO FILES INRAM
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.

Cube Voyager Reference Guide 543

Matrix Program Control statements

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:
Field IPZONE OPZONE ROWPCT COLPCT Description Input zone number Output zone number Percentage of IPZONEs values to be assigned to OPZONE when renumbering the IPZONE row Percentage of IPZONEs 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:
Description District OPZONE IPZONEs Word that begins with the letter D (for traditional DISTRICT). The word may be any length, but the first character must be D. Output zone number; it MUST be followed by =. 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.

544 Cube Voyager Reference Guide

Matrix Program Control statements

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

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.
RENUMBER keywords
Keyword FILE |F| Description File that contains the zonal equivalencies. FILE and ZONEO are mutually exclusive. Only one of those two keywords can be used at one time.

Cube Voyager Reference Guide 545

Matrix Program Control statements

RENUMBER keywords (continued)

Keyword FILES |I| Description 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. 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 ZONEO |S| |S| Indicator similar to MISSINGZI. It indicates the level of error associated with gaps in the OPZONE structure. 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. Designates the highest new zone number and serves as an editor as the file records are read, to ensure that each OPZONE doesnt 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.

MISSINGZI

|S|

ZONES

|I|

Example[1]
FILEI MATI=IN.MAT FILEO MATO=OUT.MAT, MO=1

546 Cube Voyager Reference Guide

Matrix Program Control statements

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

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

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

Cube Voyager Reference Guide 547

Matrix Program Control statements

; 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

REPORT
Program: Matrix

Request reports and establish tracing MARGINS TRACE MARGINREC (CFORM FORM LIST FILE (PRINT))

548 Cube Voyager Reference Guide

Matrix Program Control statements

ZDAT (DEC) MATSTAT

REPORT keywords
Keyword MARGINREC Subkeyword |K?| Description 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. Format to use for any character data items that appear after this keyword. 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. Format to use for any numeric data items that appear after this keyword.

MARGINREC MARGINREC

CFORM FILE

|S| |F|

MARGINREC

FORM

|S|

Cube Voyager Reference Guide 549

Matrix Program Control statements

REPORT keywords (continued)

Keyword MARGINREC Subkeyword LIST |KSV| Description 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 MARGINS PRINT |?| |KIP| Switch that indicates that the FILE record is to also be written to the standard printed output. 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.

550 Cube Voyager Reference Guide

Matrix Program Control statements

REPORT keywords (continued)

Keyword TRACE Subkeyword |K?| Description 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. Switch that indicates that the zonal data arrays generated by any FILEI ZDATI keywords are to be formatted and reported. Sets the maximum number of decimal places to be printed for any variable. This one value applies to all variables on all ZDATI statements.

ZDAT

|?|

ZDAT

DEC

|I|

Example

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

Cube Voyager Reference Guide 551

Matrix Program Control statements

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

SET
Programs: Distribution, Fratar, Generation, Matrix

Stores numeric values into one, or more, variables. 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.
SET keywords
Keyword VAL |R| Description 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. 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.

VARS

|S|

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

552 Cube Voyager Reference Guide

Matrix Program Control statements

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

SORT
Programs: Distribution, Fratar, Generation, Matrix

Sort user-defined arrays. ARRAY NUMRECS See SORT on page 76 for details about the standard Cube Voyager statement.
Example
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

WRITE
Programs: Distribution, Fratar, Generation, Matrix

Output record data files to DBF format RECO

Cube Voyager Reference Guide 553

Matrix Program Control statements

Use WRITE to specify the record files that are to be written at the end of each I zone.
WRITE keyword
Keyword RECO |I| Description Number of the FILEO RECO[#] DBF file where you want to direct this print output.

554 Cube Voyager Reference Guide

Matrix Program Examples

Examples
This section contains examples that demonstrate the Matrix program: Example 1 Example 2 Example 3 Example 4

Example 1
RUN PGM=MATRIX /* Sample problem to generate 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 cbd */ 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

Example 2
; Get I-J values for records with trip tours on them. /*Sample setup to use the MATRIX program to process the tours.dat file

Cube Voyager Reference Guide 555

Matrix Program Examples

For each leg of the tour, look up highway or transit time based on the major mode for that journey, assuming 1 is highway otherwise transit The program will read each input record from the RECI file and do calculations as specified. The MatVal function is used to random 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

556 Cube Voyager Reference Guide

Matrix Program Examples

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

Example 3
/* This is an example of using RECI/RECO processing of 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),

Cube Voyager Reference Guide 557

Matrix Program Examples

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

Example 4
/* Example of using 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

558 Cube Voyager Reference Guide

Matrix Program Examples

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

Example 5
/* Example of DBI processing to combined two fields from different tables stored in a MDB file to a new table in the MDB file using the JOINTTODBI functionality. */ 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

Cube Voyager Reference Guide 559

Matrix Program Examples

ENDLOOP ENDRUN

Example 6
/* The same process as Example 5 but using AUTOARRAY functionality to accomplish the same 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

560 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 561

10

Distribution Program

10

Distribution Program

This chapter discusses the trip distribution process. Topics include: Introduction to the Distribution program Control statements Examples

562 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

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

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.

Cube Voyager Reference Guide 563

10

Distribution Program Introduction to the Distribution program

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

564 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

A mechanism must be established to obtain the travel function. Usually, a level-of-service matrix is used to obtain the zone-tozone 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 destinationchoice model with the CHOICE control statement in Matrix. See Examples on page 555 under the Matrix program for an example of a singly constrained gravity model.
Example 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

Cube Voyager Reference Guide 565

10

Distribution Program Introduction to the Distribution program

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 1 57 24 19 2 64 106 30 3 102 61 137 Total 223 191 186 Use2 258 210 138 Total 100 200 300 600

566 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

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 1 60 24 16 2 67 108 25 3 113 66 121 Total 240 198 162 Use3 258 212 136 Total 100 200 300 600

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,

Cube Voyager Reference Guide 567

10

Distribution Program Introduction to the Distribution program

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.

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

568 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

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.
Example 2: Three purpose - same P/A and FF file for all purposes
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.
Example 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

Cube Voyager Reference Guide 569

10

Distribution Program Introduction to the Distribution program

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.

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

570 Cube Voyager Reference Guide

Distribution Program Introduction to the Distribution program

10

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.

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

Cube Voyager Reference Guide 571

10

Distribution Program Introduction to the Distribution program

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.

572 Cube Voyager Reference Guide

Distribution Program Control statements

10

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 451 under the Matrix program. Matrix program statements not allowed in the Distribution program:
RENUMBER

Distribution program statements not in the Matrix program:

SETPA GRAVITY

Distribution program keywords not in the Matrix program:

PARAMETERS MAXITERS= MAXRMSE= REPORT ACOMP=

GRAVITY
Performs a standard gravity model. PURPOSE LOS FFACTORS KFACTORS LOSRANGE

Cube Voyager Reference Guide 573

10

Distribution Program Control statements

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.
GRAVITY keywords
Keyword FFACTORS |SN| Description 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 55 for hints about using Lookups to obtain friction factors. 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/#. 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/#. 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. Specifies which purpose this is calculation to: the results will be stored in MW[PURPOSE].

KFACTORS

|S|

LOS

|S|

LOSRANGE

[R]

PURPOSE

|I|

PURPOSE, LOS, and FFACTORS must be specified. Example

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,

574 Cube Voyager Reference Guide

Distribution Program Control statements

10

lookup[4]=1,result=5, lookup[5]=1,result=6, interpolate=y,setupper=n gravity purpose=1, los=mw[11], gravity purpose=2, los=mw[11], gravity purpose=3, los=mw[11], gravity purpose=4, los=mw[11], gravity purpose=5, los=mw[11],

ffactors=ff ffactors=ff, losrange=11-48 ffactors=ff ffactors=ff ffactors=ff, Kfactors=MI.1.K5

PARAMETERS
Sets general parameters. MATOEVERY MAXITERS MAXRMSE ZONES In addition to the standard Matrix-program parameters, the parameters described here may also be specified.
PARAMETERS keyword
Keyword MATOEVERY |K?| Description 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.

Cube Voyager Reference Guide 575

10

Distribution Program Control statements

PARAMETERS keyword (continued)

Keyword MAXITERS |KI| Description 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. 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. 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.

MAXRMSE

|KR|

ZONES

|KI|

REPORT
Specifies Matrix program reports.

576 Cube Voyager Reference Guide

Distribution Program Control statements

10

ACOMP (ITERATIONS)
REPORT keywords
Keyword ACOMP |KIP| Description 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). 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).

ITERATIONS

|IP|

Example
REPORT ACOMP=1-3,5 ITERATIONS=5,10,99 ; specified purposes and iterations REPORT ACOMP=6 ; for all iterations

SETPA
Establishes base productions and attractions. P A INCLUDE EXCLUDE 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

Cube Voyager Reference Guide 577

10

Distribution Program Control statements

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).
SETPA keywords
Keyword A EXCLUDE |NV| |IP| Description Expression that is solved to set the attractions for the indexed purpose. 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. 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.

INCLUDE

|IP|

578 Cube Voyager Reference Guide

Distribution Program Control statements

10

SETPA keywords (continued)

Keyword P |NV| Description Expression that is solved to set the productions for the indexed purpose.

Example
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

Cube Voyager Reference Guide 579

10

Distribution Program Examples

Examples
This section contains examples of the Distribution program: Distribution example 1 Distribution example 2 Distribution example 3

Distribution 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 example 2
/* Gravity Application illustrating several ways to do 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

580 Cube Voyager Reference Guide

Distribution Program Examples

10

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 example 3
/* Gravity Application illustrating use of GAMMA Impedance function */ ;-----------------------------------------------------; HBW GRAVITY MODEL USING GAMMA IMPEDANCES ;-----------------------------------------------------; 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=tripdist 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

Cube Voyager Reference Guide 581

10

Distribution Program Examples

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

582 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 583

11

Generation Program

11

Generation Program

This chapter discusses the Generation program. Topics include: Introduction to Generation program Control statements Examples

584 Cube Voyager Reference Guide

Generation Program Introduction to Generation program

11

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

Cube Voyager Reference Guide 585

11

Generation Program Introduction to Generation program

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

586 Cube Voyager Reference Guide

Generation Program Control statements

11

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 451. Matrix statements not allowed in Generation:
FREQUENCY PRINTROW RENUMBER

Matrix keywords not allowed in Generation:

FILEI MATI= FILEO MATO= COMP MW= PARAMETERS MAXMW= REPORT MARGINS= MARGINREC=

Generation statements not in Matrix:

PROCESS ... ENDPROCESS PHASE= BALANCE A2P= P2A= NHB=

Generation keywords not in Matrix:

FILEO PAO= COMP A= P= PARAMETERS MAXPURPS= REPORT PC= AC= P= A=

Cube Voyager Reference Guide 587

11

Generation Program Control statements

BALANCE
This statement is used to specify how the trip ends are to be adjusted in the Phase=Adjust process. P2A=list A2P=list NHB=list This statement makes the adjustment process much simpler. Typically, most users adjust the Attraction totals to match the Production Totals.
BALANCE keywords
Keyword A2P P2A NHB |IP| |IP| |IP| Description Specifies the purposes whose attraction totals are to be set to the production totals for that purpose. Specifies the purposes whose production totals are to be set to the attraction totals for that purpose. 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.

Example
BALANCE A2P=1,2,4-7 NHB=3

COMP
Computes a variable, P/A row, or P/A row element VAR=expression P/A[]=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 P and A array values. The reader is advised to read Introduction to Generation program on page 585 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

588 Cube Voyager Reference Guide

Generation Program Control statements

11

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 477 for details of COMP statements. The COMP statement may contain INCLUDE and EXCLUDE to cause selective processing.
COMP keywords
Keyword A[n][I] |N| Description 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. 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.

P[n][I]

|N|

Expressions may contain the functions ATOT(#) and PTOT(#), which return the attraction and production totals for purpose #.
Example
COMP P[1]= ZI.1.P1 COMP A[2]=0.90*ahbo IF (I=38-49) P[1]=ZI.4.SPECIAL

FILEO
Generates trip-end records. PAO (FORM CFORM PRINT LIST (DBF (NAMES))) 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

Cube Voyager Reference Guide 589

11

Generation Program Control statements

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 66. 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.
FILEO keywords
Keyword PAO PAO CFORM Subkeyword |KF10| |S| Description Name of a file where the formatted records are to be written. Format for following string list items. Normally, text variables will not be written to a PAO file. 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

DBF

|?|

590 Cube Voyager Reference Guide

Generation Program Control statements

11

FILEO keywords (continued)

Keyword PAO Subkeyword FORM |S| Description Format for following numerical list items. FORM=20.2SLR is recommended if the Distribution program is going to read the file. 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. 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

PAO

LIST

|S|

PAO

NAMES

|S|

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.

Cube Voyager Reference Guide 591

11

Generation Program Control statements

FILEO keywords (continued)

Keyword PAO Subkeyword PRINT |?| Description Indicates if the output records are to also be listed to the standard output. This is off, unless turned on.

Example
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])

PARAMETERS
Set general parameters. ZONES MAXPURPS
PARAMETERS keywords
Keyword ZONES |I| Description 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. 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.

MAXPURPS

|I|

Example
ZONES=3000 MAXPURPS=5

PROCESS ... ENDPROCESS

Establishes phase blocks. PHASE ENDPHASE

592 Cube Voyager Reference Guide

Generation Program Control statements

11

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.
PROCESS keywords
Keyword PHASE |KS| Description 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: ENDPHASE |K| ILOOP ADJUST

Defines the end of the user control statements for a stack.

Example
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

Cube Voyager Reference Guide 593

11

Generation Program Control statements

REPORT
Requests reports and establishes tracing. A P AC PC TRACE
REPORT keywords
Keyword AC A PC P TRACE |?| |?| |?| |?| |K?| Description Requests that the computed attractions be reported. This report precedes ADJUST processing. Requests that the final attractions be reported. This report follows any ADJUST processing. Requests that the computed productions be reported. This report precedes ADJUST processing. Requests that the final productions be reported. This report follows any ADJUST processing. Controls the listing of the stack statements as they are processed.

Example
REPORT AC=y A=y P=y

594 Cube Voyager Reference Guide

Generation Program Examples

11

Examples
This section contains examples of the Generation program: Generation example 1 Generation example 2

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

Cube Voyager Reference Guide 595

11

Generation Program Examples

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

596 Cube Voyager Reference Guide

Generation Program Examples

11

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

per

per

per

per

per

Cube Voyager Reference Guide 597

11

Generation Program Examples

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

598 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 599

12

Public Transport Program

12

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

600 Cube Voyager Reference Guide

Public Transport Program Overview

12

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

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

Cube Voyager Reference Guide 601

12

Public Transport Program Overview

Two methods (service-frequency and service-frequency-andcost) for loading demand on to transit choices at stops Analyses of loaded tripstransfers 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 matricesresults 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

602 Cube Voyager Reference Guide

Public Transport Program Overview

12

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.

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

Route enumeration and evaluation

During route enumeration and evaluation, the Public Transport model finds reasonable or attractive multiple discrete routes between zones, considering:

Cube Voyager Reference Guide 603

12

Public Transport Program Overview

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)

Skimming (levels of service matrices)

During skimming, the Public Transport model skims (extracts) the costsand the components of costsof 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.

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.

604 Cube Voyager Reference Guide

Public Transport Program Overview

12

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.

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

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

Cube Voyager Reference Guide 605

12

Public Transport Program Overview

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

606 Cube Voyager Reference Guide

Public Transport Program Processes

12

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.

Cube Voyager Reference Guide 607

12

Public Transport Program Processes

You control the main processes and their associated phases, within a prescribed hierarchy.

Public Transport program processes and associated phases

(With multiple user classes, processes in the blue boxes are performed separately for each class.) See Phases on page 641 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.

608 Cube Voyager Reference Guide

Public Transport Program Processes

12

Only context-sensitive dynamic control statements are available to the phases; the description of each phase lists valid control statements (see Phases on page 641). Only code phases that contain control statements; do not code empty phases.

Network development
During network development, the Public Transport program: Reads in the input network from FILEI NETI Processes public transport system data in FILEI SYSTEMI Processes the LINE control statements in FILEI LINEI Processes the FACTORS control statements in FILEI FACTORI 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.

Cube Voyager Reference Guide 609

12

Public Transport Program Processes

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 876 for examples of this task.
Inputs required for Public Transport network development
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[#]

Outputs produced by Public Transport network development

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

610 Cube Voyager Reference Guide

Public Transport Program Processes

12

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.
Associated phases

DATAPREP (mandatory)

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.

Cube Voyager Reference Guide 611

12

Public Transport Program Processes

See Route-enumeration process on page 820 for theory about route enumeration.
Inputs required for Public Transport route enumeration
A public transport network file, produced either by the current run of the Public Transport program, or produced previously and input with NETI.

Outputs produced by Public Transport route enumeration

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 808, can be examined through a series of reports specified on the REREPORT statement.
Associated phases

None

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

612 Cube Voyager Reference Guide

Public Transport Program Processes

12

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 routeevaluation 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 826 for the theory supporting route evaluation.
Inputs required for Public Transport route evaluation
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.
Outputs produced by Public Transport route evaluation1
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.

Cube Voyager Reference Guide 613

12

Public Transport Program Processes

Associated phases

MATI SELECTIJ

Skimming (level of service)

This section describes skimming in detail; see Skimming Quick reference on page 625 for a quick reference to the skimming functions. 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. Skimming is also described in Skimming process on page 839. See Public transport skimming on page 881 for examples of this process.
NOTE: All skim matrices have 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: Overview Wait-time skim functions Travel-time skim functions Penalty skim functions Fare skim functions Other skim functions

614 Cube Voyager Reference Guide

Public Transport Program Processes

12

Overview
Inputs required for Public Transport skimming
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.

Outputs produced by Public Transport skimming
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.

Associated phases

SKIMIJ (mandatory) MATO

Skimming functions

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:

Cube Voyager Reference Guide 615

12

Public Transport Program Processes

SkimName includes an explicit prefix, or a default, that denotes its type: COMP for composite skims CWD for crowded skims BEST for best skims All other skims are average skims

Arg1 is the route set number and can range from 0 to the number of route sets. If Arg1=0, the attribute skimmed is the total for the zone pair; if Arg1>0, the extracted skim is for the specified route set.
Example 1: Shows how skims requiring one argument are

invoked.
MW[2]=COMPCOST(0) MW[3]=ValOfChoice(0) MW[4]=IWAITA(0)

Currently only one route set is produced. Therefore, setting Arg1 to zero or one will produce the same result, 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

616 Cube Voyager Reference Guide

Public Transport Program Processes

12

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.

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

Cube Voyager Reference Guide 617

12

Public Transport Program Processes

Perceived transfer wait time

Actual crowding wait time

CWDWAITA(RouteSet)

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).
Actual initial wait time
IWAITA(RouteSet)

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 IWAITCURVE keyword, or, for nodes that have not been assigned one, from a default wait curve.
Actual transfer wait time
XWAITA(RouteSet)

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 XWAITCURVE keyword, or, for nodes that have not been assigned one, from a default wait curve.
Perceived crowding wait time
CWDWAITP(RouteSet)

Computes the average additional wait time due to crowding effects incurred at the transfer points of all attractive routes between zones, weighted by the WAITFACTOR keyword.

618 Cube Voyager Reference Guide

Public Transport Program Processes

12

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).
Perceived initial wait time
IWAITP(RouteSet)

Computes the average actual time incurred at the start of the trip for all attractive routes between zones, weighted by WAITFACTOR. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement, assigned to nodes by IWAITCURVE, or, for nodes that have not been assigned one, from a default wait curve.
Perceived transfer wait time
XWAITP(RouteSet)

Computes the average actual time incurred at the transfer points of all attractive routes between zones, weighted by WAITFACTOR. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement, assigned to nodes by XWAITCURVE, or, for nodes that have not been assigned one, from a default wait curve.

Travel-time skim functions

This section describes travel-time skim functions: Actual travel time Perceived crowded link travel time Perceived travel time

Actual travel time

TIMEA(RouteSet, Mode)

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.

Cube Voyager Reference Guide 619

12

Public Transport Program Processes

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.
Perceived crowded link travel time
CWDCOSTP(RouteSet, Mode)

For transit modes, this skim extracts the average additional invehicle 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, and RUNFACTOR. This component of cost is included in the perceived travel time skim, TIMEP, so care should be taken to avoid double-counting.
Perceived travel time
TIMEP(RouteSet, Mode)

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, RUNFACTOR and crowding factor. 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.

Penalty skim functions

This section describes penalty skim functions: Actual transfer penalty Perceived boarding penalty Perceived transfer penalty

620 Cube Voyager Reference Guide

Public Transport Program Processes

12

Actual transfer penalty

XFERPENA(RouteSet, Mode)

Extracts the average actual transfer penalty for all attractive routes between zones. It is taken from XFERPEN.
Perceived boarding penalty
BRDPEN(RouteSet, Mode)

Counts the boarding penalties associated with transit legs of the trip.
Perceived transfer penalty
XFERPENP(RouteSet, Mode)

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.

Fare skim functions

This section describes fare skim functions: Monetary units Generalized cost units

Monetary units
FAREA(RouteSet, Mode)

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.
Generalized cost units
FAREP(RouteSet, Mode)

Cube Voyager Reference Guide 621

12

Public Transport Program Processes

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.

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

Best trip time

BESTJRNY

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

622 Cube Voyager Reference Guide

Public Transport Program Processes

12

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.

Boardings
BRDINGS(RouteSet, Mode)

Extracts the average number of boardings used by the attractive routes between zone pairs.
Composite cost
COMPCOST(RouteSet)

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)

Distance
DIST(RouteSet, Mode)

Extracts the average distance travelled by the attractive routes between zone pairs. It is taken directly from the network link data.

Cube Voyager Reference Guide 623

12

Public Transport Program Processes

Excess demand
EXCESSDEMAND

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.
Excess demand as a proportion
EXCESSPROP

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).
Value of choice
ValOfChoice(RouteSet)

Indicates level of choice available in the public transport system by computing average travel cost skim minus the composite travel cost skim.

624 Cube Voyager Reference Guide

Public Transport Program Processes

12

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.

Skimming 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 Skimming (level of service) on page 614 for a detailed description.
Summary of skim functions
Function BESTJRNY BRDINGS(RouteSet, Mode) BRDPEN(RouteSet, Mode) COMPCOST(RouteSet) CWDCOSTP(RouteSet) CWDWAITA(RouteSet) CWDWAITP(RouteSet) DIST(RouteSet, Mode) EXCESSDEMAND EXCESSPROP FAREA(RouteSet, Mode) FAREP(RouteSet, Mode) IWAITA(RouteSet) IWAITP(RouteSet) Description Skims best trip times Skims number of boardings Skims boarding penalty (perceived) Skims composite costs Skims crowding link travel times (perceived) Skims crowding wait times (actual) Skims crowding wait times (perceived) Skims distance Skims excess demand (where demand exceeds capacity in crowding model) Skims excess proportion (where demand exceeds capacity in crowding model) Skims fares in monetary units Skims fares in generalized time units Skims initial wait times (actual) Skims initial wait times (perceived)

Cube Voyager Reference Guide 625

12

Public Transport Program Processes

Summary of skim functions (continued)

Function TIMEA(RouteSet, Mode) TIMEP(RouteSet, Mode) ValOfChoice(RouteSet) XFERPENA(RouteSet, Mode) XFERPENP(RouteSet, Mode) XWAITA(RouteSet) XWAITP(RouteSet) Description Skims travel time (actual) Skims travel time (perceived) Skims value of choice Skims transfer penalty (actual) Skims transfer penalty (perceived) Skims transfer wait times (actual) Skims transfer times (perceived)

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 826 and the loading theory is described in Loading process on page 842. 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.

626 Cube Voyager Reference Guide

Public Transport Program Processes

12

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 883 for an example of this function.
Inputs required for Public Transport loading
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[#]).

Outputs produced by Public Transport loading

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.

Associated phases

MATI

Cube Voyager Reference Guide 627

12

Public Transport Program Processes

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 708 for more information.
Inputs required for Public Transport select 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.
Outputs produced by Public Transport select 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

Associated phases

SKIMIJ (mandatory) MATO

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

628 Cube Voyager Reference Guide

Public Transport Program Processes

12

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:

Cube Voyager Reference Guide 629

12

Public Transport Program Processes

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

Selection for particular links

To select demand traversing a link, the expression takes the form

L = ANode-BNode

630 Cube Voyager Reference Guide

Public Transport Program Processes

12

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

Cube Voyager Reference Guide 631

12

Public Transport Program Processes

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.

Select node

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

632 Cube Voyager Reference Guide

Public Transport Program Processes

12

Select mode

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.

Select operator

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.
Combining selection criteria together

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:

Cube Voyager Reference Guide 633

12

Public Transport Program Processes

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.

634 Cube Voyager Reference Guide

Public Transport Program Processes

12

Using simultaneous selection 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)

Use of the not and not equals operators

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.

Cube Voyager Reference Guide 635

12

Public Transport Program Processes

Selecting particular types of movement

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 notequals (!= 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:

636 Cube Voyager Reference Guide

Public Transport Program Processes

12

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).
Obtaining matrices of proportion or percentage of demand meeting a criterion

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.

Cube Voyager Reference Guide 637

12

Public Transport Program Processes

Loading the select link demand

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

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

638 Cube Voyager Reference Guide

Public Transport Program Processes

12

Transfers between modes

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

Transfers between operators

Report produced if loading is performed and output to the main print file: Passenger transfers between transit and nontransit modes

Stop-to-stop movements

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.

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

Cube Voyager Reference Guide 639

12

Public Transport Program Processes

See Crowding on page 857 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.

640 Cube Voyager Reference Guide

Public Transport Program Phases

12

Phases
The Public Transport program executes its main processesdata processing and modelingwithin 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.

Cube Voyager Reference Guide 641

12

Public Transport Program 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 653 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.

642 Cube Voyager Reference Guide

Public Transport Program Phases

12

A diagram showing how the phases would be used in a typical public transport model follows:

Processing phases in a public transport model

Cube Voyager Reference Guide 643

12

Public Transport Program Phases

NODEREAD
In the NODEREAD phase, you can compute node-based information from the input networks 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 878 for an example of this phase.
Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO

644 Cube Voyager Reference Guide

Public Transport Program Phases

12

IF... ELSEIF ... ELSE ... ENDIF LOOP ... ENDLOOP PRINT Public Transport variables available in this phase

ZONES

LINKREAD
In the LINKREAD phase, you can compute link-based information from the input networks 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 878 for an example of this phase.
Control statements available in this phase ABORT

Cube Voyager Reference Guide 645

12

Public Transport Program Phases

BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF LOOP ... ENDLOOP PRINT Public Transport variables available in this phase

ZONES LINKNO

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 876 for examples of this phase.
Control statements available in this phase ABORT BREAK

646 Cube Voyager Reference Guide

Public Transport Program Phases

12

COMP CONTINUE EXIT GENERATE GOTO IF... ELSEIF ... ELSE ... ENDIF LINKLOOP ... ENDLINKLOOP LOOP ... ENDLOOP PRINT Public Transport variables available in this phase

ZONES

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 MATI, 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 MATI 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.

Cube Voyager Reference Guide 647

12

Public Transport Program Phases

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 MATI, and then manipulate, report, and save those matrices with FILEO MATO. 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 883 for an example of this phase.
Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LOOP ... ENDLOOP PRINT PRINTROW

648 Cube Voyager Reference Guide

Public Transport Program Phases

12

Public Transport variables available in this phase

ZONES USERCLASS I J

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.

Cube Voyager Reference Guide 649

12

Public Transport Program Phases

Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF PRINT PRINTROW Public Transport variables available in this phase

ZONES USERCLASS I J

SKIMIJ
The SKIMIJ phase extracts skims and select-link outputs with special functions described in Select-link functions on page 628, then saves them, generally in working matrices with the COMP MW[#] statement. The Public Transport program invokes SKIMIJ for each zone pair, I-J, immediately after route evaluation. See Public transport skimming on page 881 for an example of this phase.

650 Cube Voyager Reference Guide

Public Transport Program Phases

12

MATO
In the MATO phase, the Public Transport program revises, combines, reports and writes work matrices to the FILEO MATO 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 881 for an example of this phase.
Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LOOP ... ENDLOOP PRINT PRINTROW

Cube Voyager Reference Guide 651

12

Public Transport Program Phases

Public Transport variables available in this phase

ZONES USERCLASS I J

652 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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 contextsensitive control statements; see each phases description in Phases on page 641 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.
Control statement ABORT BREAK COMP CONTINUE CROWDCRVDEF CROWDMODEL EXIT FACTORS FARESYSTEM FILEI FILEO Public Transport Public Transport Cube Voyager Cube Voyager Static Static Static Static Public Transport Static Availability Cube Voyager Cube Voyager Cube Voyager Cube Voyager Type Dynamic Dynamic Dynamic Dynamic

Cube Voyager Reference Guide 653

12

Public Transport Program Control statements

Control statement GENERATE GOTO IF... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LINE LINKLOOP ... ENDLINKLOOP LOOP ... ENDLOOP MODE NT OPERATOR PARAMETERS PRINT PRINTROW REPORT REREPORT VEHICLETYPE WAITCRVDEF

Availability Public Transport Cube Voyager Cube Voyager Cube Voyager Public Transport Public Transport Cube Voyager Public Transport Public Transport Public Transport Public Transport Cube Voyager Cube Voyager Cube Voyager Public Transport Public Transport

Type Dynamic Dynamic Dynamic Dynamic Static Dynamic Dynamic Static Static Static Static Dynamic Dynamic Static Static Static

ABORT
Terminates a run.
ABORT MSG = text

ABORT keyword
Keyword MSG |S| Description Optional. Message printed when the program terminates.

654 Cube Voyager Reference Guide

Public Transport Program Control statements

12

Example

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

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.

Cube Voyager Reference Guide 655

12

Public Transport Program Control statements

When used within the Public Transport programs 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.
Example 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

Example 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

Example 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

656 Cube Voyager Reference Guide

Public Transport Program Control statements

12

IF(I==20) BREAK MW[1] = MW[1] * 1.2 ENDPHASE

COMP
Computes a variable, matrix, or matrix element from an expression.
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 functions on page 38) Row-based functions, which process the cells in a row (see Matrix function descriptions on page 481)
NOTE: You cannot use row-based functions within a J-loop.

Cube Voyager Reference Guide 657

12

Public Transport Program Control statements

Skimming functions, which produce skim (level of service) matrices of total trip costs and their components (see Skimming (level of service) on page 614)
COMP keywords

Keyword MW

Subkeyword |KD|

Description Optional. Value for a working matrix. You can specify this keyword in two formats: MW[n] Defines the value for row n of a working matrix. Matrices can contain up to MAXMW rows, 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 loops current J. MW[n][o] Defines the value for column o in row n. The second index, o, must be between one and Zones. The program solves the expression one time only, with J being the loops 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.

658 Cube Voyager Reference Guide

Public Transport Program Control statements

12

COMP keywords (continued)

Keyword MW Subkeyword INCLUDE |I| Description 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 variables 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.

Cube Voyager Reference Guide 659

12

Public Transport Program Control statements

Examples of computation statements in Public Transport

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)

CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements.

660 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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

Example 4
PHASE=SELECTIJ

Cube Voyager Reference Guide 661

12

Public Transport Program Control statements

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 Jloop after zone 455.

CROWDCRVDEF
Defines crowding curves, used to compute crowded travel time for particular combinations of transit lines and user-class. 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).

662 Cube Voyager Reference Guide

Public Transport Program Control statements

12

Input CROWDCRVDEF statements must be input in the public transport system data file with SYSTEMI.
CROWDCRVDEF keywords
Keyword CURVE |R| Description Defines X-Y pairs for the crowding curves used to compute link travel times under crowded conditions. Utilization (measured as a percentage) is the curves X-axis and the crowding factor is the curves Y-axis. The values for utilization vary from 0.0 (where the crowding factor is at least 1.0) to 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.

Maximum value: 10,000. LONGNAME NAME NUMBER |S| |S| |I| Optional. Specifies a second text-string identifier for a crowding curve. It is in addition to NAME. Optional. Specifies a text-string identifier for a crowding curve. 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.

Cube Voyager Reference Guide 663

12

Public Transport Program Control statements

Example

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

CROWDMODEL
Specifies the crowding model used in the run of the Public Transport program.
CROWDMODEL keywords
Keyword ADJUSTLINK |?| Description 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 PERIOD |I| |I| Specifies the number of iterations performed during a crowd-modeling run. Valid values are 1 to 99. 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.

Example
CROWDMODEL, APPLY = T, ADJUSTWAIT = T, ITERATIONS = 10

664 Cube Voyager Reference Guide

Public Transport Program Control statements

12

Specifies a run with 10 iterations of crowd modeling, including a wait-time adjustment.

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.
Example
LOOP iter=1,10 . IF (expression) EXIT . ENDLOOP

This loop terminates either when iter=11 or the condition specified by expression is met.

EARLYCRVDEF
Defines an earliness curve (in similar style to wait curves.) Curves should be such that y values never decrease as X increases. Which curve is used is defined in the factor file for the user class.
EARLYCRVDEF keywords
Keyword NUMBER Subkeyword |I| Description Unique number that identifies an earliness curve. NOTE: Must be the first keyword coded in an EARLYCRVDEF control statement. Valid values range from 1 to 255. NUMBER NUMBER NAME LONGNAME |S| |S| Optional. Unique string that identifies the earliness curve. Optional. Second unique string that identifies the earliness curve (in addition to NAME).

Cube Voyager Reference Guide 665

12

Public Transport Program Control statements

Keyword NUMBER

Subkeyword CURVE |RKV1 0000|

Description List of X-Y coordinates that define the earliness 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.

FACTORS
Specifies the generalized cost factors and control information for the route enumeration and evaluation processes.
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.
FACTORS keywords
Keyword ACCESSIBILITY Subkeyword |K?| Description When true, performs an accessibility run (to obtain travel time skims for mapping isochrones.) Default is false. Requires just DAYTYPE and either PERIOD or TIMEPOINT values to be specified in FACTORS file. All other factors are rejected as irrelevant.

666 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword ALPHA Subkeyword |RK| Description 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 travelers choice. A travelers 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.

Cube Voyager Reference Guide 667

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword BESTPATHONLY Subkeyword |?K| Description 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. Do not set BESTPATHONLY to true if PARAMETERS keyword FARE is true or AONMETHOD has value 3. The best-path-only method cannot be used with either the crowding model or the service frequency and cost model. 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. 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 none of BESTPATHS, QUICKESTPATH or QUICKESTMULTI path are true, full multi-routing takes place (i.e. enumerates multiple paths for each departure time and each path is included in evaluation.)

668 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword BRDPEN Subkeyword |RKV999*| Description 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:

CHOICECUT > e ( Costi CostBest )

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. Cost to destination by choice i

Costi

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.

Cube Voyager Reference Guide 669

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword DELACCESSMODE Subkeyword |IKV999| Description 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. EARLYPENCURVE |KI| Specifies the curve used when earliness/lateness penalties are used in the model (because there is no route I?J in the modeled period, we choose one before or after that period). The penalty value is read from the y axis where the x value is how many minutes outside the interval the required departure time is. If no curves are specified, the default curve (y=x) will be used. 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 686 for more information. Valid values range from 0 to 10. The default value is 3.

EXTRAXFERS1

|IK|

670 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword EXTRAXFERS2 Subkeyword |IK| Description 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 686.). 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.

Cube Voyager Reference Guide 671

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword FARESYSTEM Subkeyword MODE |IVt|1 Description 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. Optional. Flag that determines wait-time calculation: False Calculated at the transit-leg bundle level True Calculated at the (lower) mode level

FREQBYMODE

|?K|

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

672 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword IWAITCURVE Subkeyword |IK| Description 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=10002000, 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 systems 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. When true, uses Kirchoff (power-function) to determine choices. Default is false. Requires KBETA when true. 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.

KIRCHOFF

|K?|

LAMBDAA

|RK|

Cube Voyager Reference Guide 673

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword LAMBDAW Subkeyword |RK| Description 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. LATEPENCURVE |KI| Specifies the curve used when earliness/lateness penalties are used in the model (because there is no route I?J in the modeled period, we choose one before or after that period). The penalty value is read from the y axis where the x value is how many minutes outside the interval the required departure time is. If no curves are specified, the default curve (y=x) will be used. 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.

MAXCOMPD

|IK|

674 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword MAXFERS Subkeyword |IK| Description 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 686. 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. Specifying varName will use ni.varName from the input network. Optional. Specifies the name of a node variable which holds the minimum time taken for transfer at each node. 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.

MINXFERVAR

|KS|

Cube Voyager Reference Guide 675

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword MUMEXTRACOST Subkeyword |RK| Description Optional. Additional cost allowed on enumerated routes of a required mode (a mode specified in MUSTUSEMODE). For example, if the cheapest route for an origindestination 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. PERIOD |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 timetabling runs. QUICKESTPATH QUICKESTMULTI REBESTPATHCOST |K?| |K?| |?K| When true, enumerates a single path. Default is false. When true, enumerates a single fastest path for each departure time. Default is false. 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 797 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.

676 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword RECOSTMAX Subkeyword |RK| Description 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 nontransit legs are left unchanged. REFAREFACTOR values are typically >= 1.0 as they inflate the perceived cost to take account of fares.

Cube Voyager Reference Guide 677

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword REWAITMAX Subkeyword |RK| Description Optional. Maximum weighted wait time for any leg bundle in route enumeration. The program computes a leg bundles wait time from the sum of the frequencies of the bundles 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 bundles wait time from the sum of the frequencies in the bundles legs: (60./Frequency)/2 For example, if a leg bundles 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.

678 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword RUNFACTOR Subkeyword |RKVm*|3 Description 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. Service model to be used in routeevaluation, skimming, loading, and loading-analyses processes. Valid choices are: FREQUENCY Specifies Service-frequency model FREQUENCYCOST Specifies Servicefrequency-and-cost model

Default value is FREQUENCY.

Cube Voyager Reference Guide 679

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword SHORTESTWALK Subkeyword |?K| Description 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 (see SPREADFUNC on page 681). Applies only to route enumeration; not applicable when modeling best-path routes. 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 (see SPREADFUNC on page 681). Applies only to route enumeration; not applicable when modeling best-path routes. 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.

680 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword SPREADFUNC Subkeyword |IK| Description 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. 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. SPREADFUNC applies only to route enumeration; it is not applicable when modeling best-path routes. Default value is 1. TIMEPOINT |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.

Cube Voyager Reference Guide 681

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword VALUEOFTIME Subkeyword |RKVt*|1 Description 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. For example, consider:
WAITFACTOR=1.5, NODES=1000-2000, 30004500

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 networks 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 networks highest mode number.

682 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword XFERFACTOR Subkeyword |RKVt [t]|1 Description 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 networks 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 networks highest mode number.

Cube Voyager Reference Guide 683

12

Public Transport Program Control statements

FACTORS keywords (continued)

Keyword XFERPEN Subkeyword |RKVt [t]|1 Description 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 networks highest mode number. XFERPEN TO Integer specifying to mode for transfer penalty specified with XFERPEN. Valid values range from 1 to the networks highest mode number.

684 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FACTORS keywords (continued)

Keyword XWAITCURVE Subkeyword |IK| Description 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 systemgenerated 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 networks highest node number. 1. t indicates number of transit modes 2. o indicates number of transit operators 3. m indicates number of modes

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

Cube Voyager Reference Guide 685

12

Public Transport Program Control statements

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,

Route generation MAXFERS 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: MINXOD+EXTRAXFERS2
EXTRAXFERS1 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.

686 Cube Voyager Reference Guide

Public Transport Program Control statements

12

The following table shows the number of transfers that the program explores for various values of EXTRAXFERS2 if MAXFERS=5 and EXTRAXFERS1=4 (the default condition).
Number of transfers explored
MINXOD 0 EXTRAFERS2 0 1 2 3 4 0 1 2 3 4 1 1 2 3 4 4 2 2 3 4 4 4 3 3 4 4 4 4 4 4 4 4 4 4 5 5 5 5 5 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.

FARESYSTEM
Defines fare systems that the program uses to calculate trip fares. Use separate FARESYSTEM statements to define multiple fare systems in public transport network.

Cube Voyager Reference Guide 687

12

Public Transport Program Control statements

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 845 for a description of fares modeling.

Example 1: Distance with IBOARDFARE + UNITFARE + SAME=SEPARATE
FARESYSTEM NUMBER=4, NAME=DISTANCE, LONGNAME="WITHOUT FAREFROMFS", STRUCTURE=DISTANCE, SAME=SEPARATE, IBOARDFARE=1.35, UNITFARE=0.83

Example 2: Zone based FROMTO fare system with no FAREFROMFS

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

688 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FARESYSTEM keywords
Keyword FAREFROMFS Subkeyword |RVn|
1

Description 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. FAREMATRIX |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.

Cube Voyager Reference Guide 689

12

Public Transport Program Control statements

FARESYSTEM keywords (continued)

Keyword FARETABLE Subkeyword |RKV32000| Description Optional. List of X- and Y-coordinates that define the table used to compute fares for a trips 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, 44.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.

690 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FARESYSTEM keywords (continued)

Keyword FARETABLE (continued) Subkeyword Description When STRUCTURE is COUNT, X values must 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. FARETABLE INTERPOLATE |?| 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.

Cube Voyager Reference Guide 691

12

Public Transport Program Control statements

FARESYSTEM keywords (continued)

Keyword FAREZONES Subkeyword |S| Description Name of node variable in the input network file that contains the nodes 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. IBOARDFARE |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. LONGNAME NAME NUMBER |S| |S| |I| Optional. Second unique string identifier for a userdefined fare system. Optional. Unique string identifier for a user-defined fare system. 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.

692 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FARESYSTEM keywords (continued)

Keyword STRUCTURE Subkeyword |S| Description 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 845. STRUCTURE SAME |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.

Cube Voyager Reference Guide 693

12

Public Transport Program Control statements

FARESYSTEM keywords (continued)

Keyword UNITFARE Subkeyword |R| Description 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

FILEI
NOTE: See FILEI on page 48 for general information about FILEI

and for important limitations when using Application Manager. Specifies files that may be input to the Public Transport program. 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.

694 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEI keywords
Keyword FACTORI Subkeyword |FKVu|
1

Description 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, routeevaluation, 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 666 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.

Cube Voyager Reference Guide 695

12

Public Transport Program Control statements

FILEI keywords (continued)

Keyword FAREI Subkeyword |FK| Description 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 routeevaluation and skimming processes. See FARESYSTEM on page 687 for a list of keywords you can use. FAREI LIST |?| Optional. Flag that indicates whether the list the fare systems as input. Possible values: FAREMATI |FKV| Y Lists the fare systems as input N Do not list the fare systems as input

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.). Row number. There must be a row for each fare zone that will use the matrix. Column number for the 1st f[j] that follows.

I J

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.

696 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEI keywords (continued)

Keyword LINEI Subkeyword |FKVf|2 Description 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, routeevaluation, 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 745 for a list of keywords you can use. Valid index numbers range from 1 to 32. LINEI LIST |?| Optional. Flag that indicates whether to list the lines file as input. Possible values: LINEI MAXERRS |I| Y List the lines file as input N Do not list the lines file as input

Default value is N. 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.

Cube Voyager Reference Guide 697

12

Public Transport Program Control statements

FILEI keywords (continued)

Keyword LOOKUPI Subkeyword |FKV999| Description 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.

698 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEI keywords (continued)

Keyword NETI Subkeyword |FK| Description 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.

Cube Voyager Reference Guide 699

12

Public Transport Program Control statements

FILEI keywords (continued)

Keyword NTLEGI Subkeyword |FKVf|2 Description 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 759 for a list of keywords you can use. Index values can range from 1 to 32. 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. 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 networks highest zone number.

700 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEI keywords (continued)

Keyword ROUTEI Subkeyword J |IV1000| Description Optional. List of destination zones for the routeevaluation, 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 networks 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 networks highest zone number. 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 networks highest zone number. See Evaluated routes on page 788 for an example of this report.

Cube Voyager Reference Guide 701

12

Public Transport Program Control statements

FILEI keywords (continued)

Keyword ROUTEI Subkeyword SELECTBYMAT |S| Description 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 TRACEI |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 networks 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 networks 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 Analysts 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.

702 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEI keywords (continued)

Keyword SYSTEMI Subkeyword |FK| Description 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.

Cube Voyager Reference Guide 703

12

Public Transport Program Control statements

FILEI keywords (continued)

Keyword TURNPENI Subkeyword |FKV2| Description 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). 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. 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 lines travel times with RUNTIME RT or NNTIME.

704 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEI keywords (continued)

Keyword TURNPENI Subkeyword BASEDATA |?| Description 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 turnpenalty values used.

Default value is F.

Cube Voyager Reference Guide 705

12

Public Transport Program Control statements

FILEI keywords (continued)

Keyword TURNPENI Subkeyword MAXLINKDELAY |SVn|3 Description 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 delayreduction 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: TURNPENI NOTMODES |I| 0 Program ignores such errors. 1 Program prints a warning message. 2 Program generates a fatal error message.

Default value is 0. 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.

706 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEI keywords (continued)

Keyword TURNPENI Subkeyword SETS |I| Description 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

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

Cube Voyager Reference Guide 707

12

Public Transport Program Control statements

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.
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.
FILEO keywords
Keyword INTERCEPTO Subkeyword |FKV10| Description 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.

708 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword LINEO Subkeyword NET |S| Description 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 BASEGDBNETWORK |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. 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.

Cube Voyager Reference Guide 709

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword LINKO Subkeyword |FKV4| Description 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.

710 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword LINKO Subkeyword BYCLASS |?| Description 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 classspecific fields have names with suffixes, like _1 and _2. N Program writes data not separated by user class

Default value is N. LINKO FMVOLS |?| Optional. Flag indicating whether outputs from a crowding run contain demand volumes or flowmetered 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. LINKO LINES |?| Optional. Flag indicating whether lines data is included in the output links file. Possible choices: LINKO NTBYLINK |?| Y Include line per link data. N Do not include line data.

Default value is Y. 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.

Cube Voyager Reference Guide 711

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword LINKO Subkeyword NTLEGS |?| Description 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: DIST Link length LINECNT Count of lines traversing the link PERHOUR Total services traversing the link per hour in the specified HDWAYPERIOD TVOL Transit loading for the link 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.

712 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword LINKO Subkeyword ONOFFS |?| Description 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 Anode. * 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 711). Do not use ONOFFS when ONELINKREC is set to Y.

Cube Voyager Reference Guide 713

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword LINKO Subkeyword SKIP0 |?| Description 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. 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.

MATO |FKV10|

Default value is Y. 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.

714 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword MATO Subkeyword DEC |SV*255| Description 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 floatingpoint format. D Store cells in double-precision floatingpoint format.

Default value is 2. See Considerations on numeric formats on page 728 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.

Cube Voyager Reference Guide 715

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword MATO Subkeyword TYPE or FORMAT |S| Description Optional. String specifying the format of the output matrix file. Possible values: NETO |FK| TPP Standard TP+/Cube Voyager matrices MINUTP Standard MINUTP matrices TRANPLAN Standard Tranplan matrices TXT ASCII records of matrix values

Default value is TPP. Name of the output network file. 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 networkdevelopment process.

716 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword NETO Subkeyword DEC |S| Description 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 floatingpoint format D Store cells in double-precision floatingpoint format

The value of DEC 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. 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 controlstatement format. NTLEGO BASEGDBNETWORK |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.

Cube Voyager Reference Guide 717

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword NTLEGO Subkeyword Description |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.

NET

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: NTLEGO XN |?| Y Write loads with nontransit legs. N Do not write loads with nontransit legs.

Default value is Y. 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 759. 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 routeevaluation processes. All diagnostics from these processes are output to the standard Public Transportprogram print file.

718 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword ROUTEO Subkeyword |FKVu|1 Description 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 routeenumeration 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 dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to the networks 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 dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to the networks highest zone number. By default, the program enumerates and saves routes bound for all zones.

Cube Voyager Reference Guide 719

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword ROUTEO Subkeyword REPORTI |IV1000| Description Optional. List of origin zones for which the program reports enumerated and evaluated routes. Specify the list as a set of single numbers or dashseparated 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 loadinganalyses processes. The program reports routes in the file specified in REPORTO. Valid values range from 1 to the networks 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 dashseparated pairs of numbers that specify a range. Delimit each number or pair with a comma. See Enumerated routes on page 787 and Evaluated routes on page 788 for examples of these reports. Valid values range from 1 to the networks 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 loadinganalyses 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.

720 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword ROUTEO Subkeyword TRACEI |IV1000| Description 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 dashseparated 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 networks highest zone number. ROUTEO TRACEJ |IV1000| Optional. List of destination zones for which the program prints evaluated routes using the tabularformat route report. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. See Evaluated routes on page 788 for examples of these reports. Valid values range from 1 to the networks highest zone number.

Cube Voyager Reference Guide 721

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword SCREENLINEO Subkeyword |FKV10| Description 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 networks 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 SCREENLINEO COUNTVAR DEFCONF |S| |I| Name of the input networks link variable that contains the link-count data. 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.

722 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword SCREENLINEO Subkeyword MEUSESNT |?| Description 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 networks 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.

Cube Voyager Reference Guide 723

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword STOP2STOPO Subkeyword |FKV4| Description 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) 1=FIRSTLAST 2=ADJACENT 3=ALLONOFFS 4=FIRSLASTBYMODE 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 729.

724 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword STOP2STOPO Subkeyword ACCUMULATE |S| Description Optional. Specifies types of transit movements included in the stop-to-stop analysis. Possible types include: FIRSTLAST Movements from a trips first node to last node. ADJACENT Movements 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 729. Default value is FIRSTLAST. 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 networks highest mode number.

Cube Voyager Reference Guide 725

12

Public Transport Program Control statements

FILEO keywords (continued)

Keyword STOP2STOPO Subkeyword GROUPS |IV9999| Description 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 nodes stop-group number on the input networks node record in the variable specified in STOPGROUP. Specify the list as a set of single numbers or dashseparated 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 networks 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.

726 Cube Voyager Reference Guide

Public Transport Program Control statements

12

FILEO keywords (continued)

Keyword STOP2STOPO Subkeyword MODES |IV999| Description 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 dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to the networks 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 dashseparated 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 networks 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

Example

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

Cube Voyager Reference Guide 727

12

Public Transport Program Control statements

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

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 files 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 DEC level specified. The

728 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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 32bit integer, the program stores the cell as a double-precision value. If DEC 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, DEC 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 DEC is 0, the result is 3, and the cell would require only one byte to storea significant reduction. However, that might not be precise enough for the programs that read it. If DEC 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 DEC were S, the value would be stored as a 4-byte single-precision, and if DEC were D, it would be stored as an 8-byte double-precision. The S and D formats require more storage space.

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

Cube Voyager Reference Guide 729

12

Public Transport Program Control statements

Example of ACCCUMULATE subkeyword

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
Value of ACCUMULATE FIRSTLAST ADJACENT ALLONOFFS FIRSLASTBYMODE Movements analyzed 1-10 1-2, 3-4, 5-6, 7-8, 9-10 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 1-10 mode 1 5-6 mode 2 1-4 mode 1 5-6 mode 2 7-10 mode 1

ADJACENTBYMODE

GENERATE
Generates nontransit legs in the public transport network. 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 AnodeB-node combination in the tablethe leg with the lowest EXTRACTCOST, followed by the leg with the lowest distance (DIST ),

730 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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 linkgenerating 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 modes MAXCOST. If the cost for at least one of the modes is less than the modes 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 694.

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.

Cube Voyager Reference Guide 731

12

Public Transport Program Control statements

GENERATE keywords
Keyword ACCESSLINK |R| Description 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 links cost and distance. If ACCESSLINK only contains one value, the program adds that value to the links cost. Valid values for A and S are 1 to the networks highest node number.

732 Cube Voyager Reference Guide

Public Transport Program Control statements

12

GENERATE keywords (continued)

Keyword COST |N| Description 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. DIRECTION |I| Optional. Integer indicating direction of the generated nontransit legs. Possible values: DIRECTLINK |I| 1 Forward direction, FROMNODE to TONODE 2 Reverse direction, TONODE to FROMNODE 3 Both directions, FROMNODE to and from TONODE

Default value is 3. Optional. Maximum number of network links a nontransit leg can traverse. By default, the program applies no limit to number of links. EXCLUDELINK |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.

Cube Voyager Reference Guide 733

12

Public Transport Program Control statements

GENERATE keywords (continued)

Keyword EXTRACTCOST |N| Description 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. FROMNODE |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 networks highest node number. INCLUDELINK |N| Optional. Expression that computes network links included in the generation of nontransit legs. Enclose expressions in parentheses. The expression can use network data items, such as link distance, cost, and classifiers, to determine included links. LIST |?| 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 738.

734 Cube Voyager Reference Guide

Public Transport Program Control statements

12

GENERATE keywords (continued)

Keyword MAXCOST |RVt*|1 Description 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). MAXNTLEGS |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.

MINCOST

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

NTLEGMODE

|I|

Nontransit mode assigned to the generated nontransit legs. Valid values range from 1 to 999. You must specify a value.

ONEWAY

|?|

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.

Cube Voyager Reference Guide 735

12

Public Transport Program Control statements

GENERATE keywords (continued)

Keyword READNTLEGI |I| Description 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. SLACK |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.

736 Cube Voyager Reference Guide

Public Transport Program Control statements

12

GENERATE keywords (continued)

Keyword TONODE |S| Description 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 networks highest number. By default, set to include all nodes (number of zones +1 to the networks highest node number). XFERMETHOD |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

Cube Voyager Reference Guide 737

12

Public Transport Program Control statements

Example

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

More on using LIST keyword

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-nodethe one with the lowest EXTRACTCOST, followed by the one with the lowest distance (DIST ), followed by the one with the lowest NTLEGMODE.

738 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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 Link 2052 1 36 0.18 GEN2 GEN3 Link 1 2052 35 0.18 Link 2052 1 35 0.18 M(625): 2 Nontransit Legs 0.36 0.36 1 3674 1 3674

0.36 0.36

1 3674 1 3674

The final nontransit legs saved will be: 1 - 2052 - 35 (and reverse)

GOTO
Jumps immediately to a named statement.
GOTO label

Cube Voyager Reference Guide 739

12

Public Transport Program Control statements

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 (:).
Example

In this example, the GOTO statement passes control in the forward and backward directions.
GOTO hwybuild ..... ..... :hwybuild IF (expression) GOTO

:hwybuild

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

740 Cube Voyager Reference Guide

Public Transport Program Control statements

12

COMP CONTINUE EXIT GOTO PRINT

Example

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

JLOOP ... ENDJLOOP

Controls a loop over the column cells (J) of the current row (I) in a matrix. 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 MW control statement.
JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks.

Cube Voyager Reference Guide 741

12

Public Transport Program Control statements

JLOOP keywords
Keyword J |I| Description 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 loops 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 loops control variable, J. Valid values range from 1 to the networks maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1. Jinc defines the increment for the loops 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: If J is specified, establish values for Jend and Jinc. Else set J=1, Jend=Zones, Jinc=1. If (J < 1 or J > Zones or Jend <1 or Jend > Zones), terminate fatally. Process statements within JLOOP. At ENDJLOOP: Add Jinc to J. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. Control passes to statement following ENDJLOOP.

742 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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 (:label statement must be inside current JLOOP) IF... ELSEIF ... ELSE ... ENDIF PRINT

JLOOP processing varies by phase.

Phase NODEREAD and LINKREAD1 DATAPREP1 MATI and MATO JLOOP processing Program executes JLOOP for each node or link processed. Program executes JLOOP once. Program executes JLOOP once per matrix row (or origin zone). You may use J keyword to select destination zones. JLOOP is invalid (the phase is executed once per IJ pair)

SELECTIJ and SKIMIJ

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.

Cube Voyager Reference Guide 743

12

Public Transport Program Control statements

Example 1

Compute the sum of each row for two matrices.

ROWSUM1 = 0 ROWSUM3=0 JLOOP ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP

Example 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

LATECRVDEF
Defines a lateness curve (in similar style to wait curves.) Curves should be such that y values never decrease as X increases. Which curve is used is defined in the factor file for the user class.
LATECRVDEF keywords
Keyword NUMBER Subkeyword |I| Description Unique number that identifies a lateness curve. NOTE: Must be the first keyword coded in an LATECRVDEF control statement. Valid values range from 1 to 255. NUMBER NUMBER NUMBER NAME LONGNAME CURVE |S| |S| |RKV1 0000| Optional. Unique string that identifies the lateness curve. Optional. Second unique string that identifies the lateness curve (in addition to NAME). List of X-Y coordinates that define the lateness 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.

744 Cube Voyager Reference Guide

Public Transport Program Control statements

12

LINE
Describes the attributes of public transport lines, including the nodes the line traverses and attributes of those nodes.
LINE keywords describe the lines 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 programs Loading Models append results of a crowd run to the output LINE data with the FMCAPACITY 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, NNTIME, RT, SPEED, TF, TIME, and XYSPD). The Public Transport programs loading models append the results of the loading process to line nodes, using the keywords FMOFF, FMON, FMVOL, OFF, ON, and VOL. 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.

Cube Voyager Reference Guide 745

12

Public Transport Program Control statements

Several of the LINE keywords and NODES subkeywords adjust network link times by line. See Calculation of line/link times on page 755 for an explanation of how they interact with each other to produce the adjusted link times.
LINE keywords
Keyword NAME ALLSTOPS Subkeyword |S| |?| Description Unique string identifier for a transit line. NAME must be the first keyword in a LINE control statement. Optional. Flag indicating whether all nodes in the line are stop nodes. Possible values: CIRCULAR |?| T Program makes all the lines nodes into stop nodes, even those explicitly designated as nonstop nodes. F Program uses node designation.

Default value is F. 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 boardingthat is, boarding and transfer penalties plus wait timefor routes passing this node. 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.

746 Cube Voyager Reference Guide

Public Transport Program Control statements

12

LINE keywords (continued)

Keyword CRUSHCAP Subkeyword |I| Description 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 linespecific capacity instead. Valid values range from 1 to 20,000. Default values are those specified in the VEHICLETYPE control statement. DAYTYPE FARESYSTEM |IPa*| |I| List of day types on which line operates. List required and no default provided. Optional. Lines 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 687), 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. Lines 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 1 to 2000.

Cube Voyager Reference Guide 747

12

Public Transport Program Control statements

LINE keywords (continued)

Keyword HEADWAY_R Subkeyword |RV5| Description 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 1 to 2000. The default value is the value of HEADWAY (the value in the forward direction). INTERVAL |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. Optional. Load distribution factorthe 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 MODE |S| |I| Optional. Second unique string identifier for a transit line, in addition to NAME. Integer indicating mode of the transit line. Valid values range from 1 to 999.

LOADDISTFAC

|R|

748 Cube Voyager Reference Guide

Public Transport Program Control statements

12

LINE keywords (continued)

Keyword NODES or N Subkeyword |I| Description List of nodes that the transit line traverses. Use negative node numbers to indicate nonstopping nodes. You 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 links 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 lines 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 networks 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 lines 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 lines last node allows exiting (that is, that nodes 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.

Cube Voyager Reference Guide 749

12

Public Transport Program Control statements

LINE keywords (continued)

Keyword NODES Subkeyword DELAY_C |R| Description 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. 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. 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. NODES FMOFF
1

|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 639). Valid values are numbers greater than or equal to 0. Optional. Flow-metered number of 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 639). Valid values are numbers greater than or equal to 0. Optional. Flow-metered number of 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 639). Valid values are numbers greater than or equal to 0.

NODES

FMON

|R|

NODES

FMVOL

|R|

750 Cube Voyager Reference Guide

Public Transport Program Control statements

12

LINE keywords (continued)

Keyword NODES Subkeyword NNTIME |R| Description 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. 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 lines 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.
NODES=1,2,3,4, NNTIME=-1, NODES=5,6,7, NNTIME=5

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. Do not use NNTIME for two-way lines; doing so produces an error.

Cube Voyager Reference Guide 751

12

Public Transport Program Control statements

LINE keywords (continued)

Keyword NODES Subkeyword OFF
1

Description |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. 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. Optional. Intermediate run time from the lines 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.

NODES

ON

|R|

NODES

RT

|R|

NODES

SPEED

|R|

Optional. Speed for all 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.

752 Cube Voyager Reference Guide

Public Transport Program Control statements

12

LINE keywords (continued)

Keyword NODES Subkeyword TIME |R| Description 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. NODES VOL
1

|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. Optional. Sets the lines 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.

NODES

XYSPD

|R|

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.

Cube Voyager Reference Guide 753

12

Public Transport Program Control statements

LINE keywords (continued)

Keyword RUNTIME Subkeyword |R| Description Optional. Lines 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 lines links so that the time sums to this value. The program only scales the links 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. 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. 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. 07000900) may be specified. Ranges are expanded into discrete runs using the interval value immediately preceding the start times 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. 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.

TIMEFAC

|R|

754 Cube Voyager Reference Guide

Public Transport Program Control statements

12

LINE keywords (continued)

Keyword XYSPEED Subkeyword |R| Description 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. 1. The Public Transport program saves the results of a loading operation to this NODES subkeyword.

Example
LINE NAME="GMB1-24M", MODE=7, OWNER=11, ONEWAY=T, CIRCULAR=F, HEADWAY=12, N=778, -777, 776, 773, 774, 765, 3674, 764, -763, 759, 760, -3673, -756, 752

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 twopart approach to process the keywords and obtain a lines final link times:
1. Establish the base time for each link:

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 TIMEFAC, SPEED, or TF.

If the link does not exist in network, but both nodes have coordinates and either XYSPEED or XYSPD is coded: Set link time to the computed X-Y distance divided by either XYSPEED or XYSPD, as appropriate. Set link time to TIME if specified. Add DELAY or DELAY_C to link time, if specified. Add turn penalties to the approach link of the modelled intersection.

Cube Voyager Reference Guide 755

12

Public Transport Program Control statements

2. Adjust link times based on applicable keywords: NODES NNTIME NODES RT RUNTIME

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.

LINKLOOP ... ENDLINKLOOP

Controls a loop for processing link records. You may nest LINKLOOP blocks, but do not overlap LINKLOOP blocks with IF blocks. 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.
Example

Double LW.VAR for even number zones

IF (I%2==0) LINKLOOP LW.VAR=LW.VAR*2 ENDLINKLOOP ENDIF

; no [LINKNO] subscript needed

756 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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.

Cube Voyager Reference Guide 757

12

Public Transport Program Control statements

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.
Example 1

Executes the code within the LOOP block 10 times.

LOOP iter=1,10 . . ENDLOOP

Example 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

MODE
Defines the transit and nontransit modes that the public transport system uses. 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.

758 Cube Voyager Reference Guide

Public Transport Program Control statements

12

Input MODE statements in the public transport system data file, specified with SYSTEMI.
MODE keywords
Keyword NUMBER |I| Description Unique numeric identifier for a mode. NUMBER must be the first keyword on the MODE control statement. Valid values range from 1 to 999. NAME LONGNAME |S| |S| Optional. Unique string identifier for a mode. Optional. Second unique string identifier for a mode. Use to supplement NAME.

NT
Specifies the format of nontransit legs in the Public Transport network. 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.

Cube Voyager Reference Guide 759

12

Public Transport Program Control statements

NT keywords
Keyword LEG |S| Description 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. ACTION |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. COST DIST FMVOL |R| |R| |R| Cost, in user-specified units, to traverse the nontransit leg. Valid values are great than or equal to 0.01. Length, in user-specified units, of the nontransit leg. Valid values are great than or equal to 0.01. 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.

760 Cube Voyager Reference Guide

Public Transport Program Control statements

12

NT keywords (continued)
Keyword FMVOLT |R| Description 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. MODE ONEWAY |I| |?| Mode of the nontransit leg. Valid values range from 1 to 999. Optional. Flag indicating whether nontransit leg is a one-way leg. Possible values: SPEED |R| T Nontransit leg is a one-way leg F Nontransit leg is a two-way leg

Default is T. 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. VOL |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. VOLT |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.

Example

A selection of nontransit legs generated by the Public Transport program.

NT LEG=6-800 MODE=5 TIME=1.92 DIST=39.00 ONEWAY=T NT LEG=6-2054 MODE=5 TIME=5.40 DIST=53.00 ONEWAY=T XN=792

Cube Voyager Reference Guide 761

12

Public Transport Program Control statements

NT NT NT NT NT NT

LEG=6-2056 MODE=5 TIME=5.92 DIST=43.00 ONEWAY=T XN=800 LEG=7-803 MODE=5 TIME=1.52 DIST=41.00 ONEWAY=T LEG=7-806 MODE=5 TIME=8.35 DIST=52.00 ONEWAY=T XN=2058 LEG=7-2058 MODE=5 TIME=4.35 DIST=29.00 ONEWAY=T LEG=8-814 MODE=5 TIME=0.88 DIST=12.00 ONEWAY=T LEG=9-812 MODE=5 TIME=1.16 DIST=29.00 ONEWAY=T

OPERATOR
Defines the operators in the public transport system. 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 SYSTEMI.
OPERATOR keywords
Keyword NUMBER |I| Description 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. NAME LONGNAME |S| |S| Optional. Unique string that identifies a transit operator. Optional. Unique secondary string that identifies a transit operator. Supplements NAME.

762 Cube Voyager Reference Guide

Public Transport Program Control statements

12

PARAMETERS
Specifies global parameters for the Public Transport run.
PARAMETERS keywords
Keyword AONMETHOD |IK| Description Optional. Integer specifying all-or-nothing path-building algorithm to use. Possible values: CHANGEATLASTSTOP |?K| 0 Use latest available algorithm 3 Use algorithm from version 3.2 4 Use algorithm from version 4.0

Default value is 0. 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. EXTENDREPORT |?| Optional. Flag that specifies whether to print messages for excessive calculated travel times. Possible values: T Program prints messages when a lines 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 lines run time with the EXTENDRUNTIMES keyword.

Cube Voyager Reference Guide 763

12

Public Transport Program Control statements

PARAMETERS keywords (continued)

Keyword EXTENDRUNTIMES |?| Description 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. FARE |?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.

764 Cube Voyager Reference Guide

Public Transport Program Control statements

12

PARAMETERS keywords (continued)

Keyword FAREMSG |IK| Description 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. HDWAYPERIOD |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. MAPSCALE |RK| Optional. Factor indicating coordinate units divided by distance unite. The program uses this value in conjunction with LINE XYSPEED. If not specified, the program estimates a value from the link data. MAXMW |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. 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.

MEUSESNT

|?|

You can override this default setting with keywords in the FILEO SCREENLINEO statement. Default value is Y.

Cube Voyager Reference Guide 765

12

Public Transport Program Control statements

PARAMETERS keywords (continued)

Keyword NOROUTEERRS |IK| Description 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. NOROUTEMSGS |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. SKIPBADLINES |?| 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.

766 Cube Voyager Reference Guide

Public Transport Program Control statements

12

PARAMETERS keywords (continued)

Keyword TRANTIME |NKVt|1 Description 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 TRANTIME computed TRANTIME = LI.name = LW.TRANTIME; LW.TRANTIME was in the LINKREAD phase. = (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)

Cube Voyager Reference Guide 767

12

Public Transport Program Control statements

PARAMETERS keywords (continued)

Keyword TRIPSIJ |NVu|2 Description 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. USERCLASSES |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 769. V4ROUTEFORMAT |?K| Optional. Flag indicating formatting of route file. Possible values: T Program writes older, version 4-compatible route file format with FILEO ROUTEO F Program writes current route file format

Default value is F.

768 Cube Voyager Reference Guide

Public Transport Program Control statements

12

PARAMETERS keywords (continued)

Keyword ZONEMSG |IK| Description 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

Example

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

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

Cube Voyager Reference Guide 769

12

Public Transport Program Control statements

System data input with SYSTEMI Demand data, input with MATI Nontransit legs, generated with the GENERATE control statement, input with NTLEGI, or both Line data, input with LINEI

Other data and processes vary by user class: Factor data, input with FACTORI, specifies cost functions that can vary by user class. Skim data, output with MATO, specifies level-of-service data that can vary by user class. Routes are enumerated and evaluated by user class. Routes are input with ROUTEI, 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 (MATO), and skims and select link analyses. You define input and output files for user classes with the FILEI and
FILEO control statements.

770 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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 66 for details about the standard Cube Voyager control statement.

PRINTROW
Specifies format for reporting work matrices to the main print file. See PRINTROW on page 73 for details about the standard Cube Voyager control statement.
Example

Print two skim matrices, ten columns per line.

PRINTROW MW=2 FORM 10.2 TITLE='COMPCOST' PRINTROW MW=2 FORM 10.2 TITLE='TIMEA''

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).
PTRUN keywords
Keyword OFLINE DAYTYPE Subkeyword |Sc| |IPa*| Description Specifies which line this service is a run of. Specifies what day types the run operates on. Reads a list of single values and/or ranges. No default values, so list is required. Defines a timing point where timing data is read as sub-keywords.

NODES

|IPD|

Cube Voyager Reference Guide 771

12

Public Transport Program Control statements

Keyword NODES NODES NODES

Subkeyword AT ARR DEP |RPD*| |RPD*| |RPD*|

Description Specifies the time when the service calls at the stop (hhmm) Specifies the arrival time when the services wait at the stop (hhmm) Specifies the departure times of services waiting at the stop (hhmm)

REPORT
Generates two reports: 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.
REPORT keywords
Keyword LINES Subkeyword |?| Description 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 793 for an example of this report. LINES 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.

772 Cube Voyager Reference Guide

Public Transport Program Control statements

12

REPORT keywords (continued)

Keyword LINES Subkeyword SKIP0 |?| Description Optional. Flag indicating whether to omit lines without loads in the summary report produced by LINES. Possible values: LINES SORT |S| T Omit lines without loads F Include lines without loads

Default value is F. 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. LINEVOLS |?| Optional. Flag indicating whether to report passenger 8loadings (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 794 for an example of this report. LINEVOLS DEC |I| Optional. Number of decimal places in passenger loading fields. Valid values range from 0 to 5. Default is 2. LINEVOLS SKIP0 |?| 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.

Cube Voyager Reference Guide 773

12

Public Transport Program Control statements

REPORT keywords (continued)

Keyword LINEVOLS Subkeyword STOPSONLY |?| Description Optional. Flag indicating whether to include stop nodes only. Possible values: LINEVOLS USERCLASSES |IV10| T Produce passenger loadings report for stop nodes only; do not include nonstopping nodes. F Include all nodes in report.

Default value is F. Optional. List of user classes that require individual passenger loadings reports. Specify the list as a set of single numbers or dashseparated 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.

REREPORT
Produces reports showing the input simplified public transport network and allied data structures that the route enumeration process uses. These basic reports help you understand the network-simplification and route-enumeration processes. For examples, see Network simplification on page 808. A run can have multiple REREPORT statements. A statements selections apply to the reports generated by that statement. The statement outputs reports to the file specified with REPORTO.

774 Cube Voyager Reference Guide

Public Transport Program Control statements

12

None of the REREPORT keywords are trigger keys; you must code all on a REREPORT statement.
REREPORT keywords
Keyword ACCESSLEGS |?| Description 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. EGRESSLEGS |?| F Do not produce this report. Default value is F. 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. LINE |S| F Do not produce this report. Default value is F. 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 lines 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.

Cube Voyager Reference Guide 775

12

Public Transport Program Control statements

REREPORT keywords (continued)

Keyword LINES |?| Description 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. LINELINELEG |?| F Do not produce this report. Default value is F. 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-andnontransit-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. LINEZONLEG1 |?| F Do not produce this report. Default value is F. Optional. Flag indicating whether to produce a line-ordered lineto-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.

776 Cube Voyager Reference Guide

Public Transport Program Control statements

12

REREPORT keywords (continued)

Keyword LINEZONLEG2 |?| Description 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. N |IV1000| F Do no produce this report. Default value is F. 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. STOPNODES |?| 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.

TLEGS |IP|

Default value is F. 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).

Cube Voyager Reference Guide 777

12

Public Transport Program Control statements

REREPORT keywords (continued)

Keyword TRNLEGS1 |?| Description 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] TRNLEGS2 |?| F Do not produce this report. Default value is F. 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 bundles fastest line and shows that legs 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 bundles top leg also includes the estimated wait time for the bundle. F Do not produce this report. Default value is F.

778 Cube Voyager Reference Guide

Public Transport Program Control statements

12

REREPORT keywords (continued)

Keyword TRNLEGS3 |?| Description 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] TRNLEGS4 |?| F Do not produce this report. Default value is F. 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. TTDEPS |?| F Do not produce this report. Default value is F. Set to true to obtain report of all lines/runs departing from the specified node. Can use sub-keyword N= to specify required nodes. 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. 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.

TTLEGS

|?|

USERCLASS

|IPa|

Cube Voyager Reference Guide 779

12

Public Transport Program Control statements

REREPORT keywords (continued)

Keyword XFERLEGS |?| Description Optional. Flag indicating whether to produce a direct-andnontransit-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.

Example

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

VEHICLETYPE
Defines the main vehicle types used by the transit lines operating public transit services. 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.

780 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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 SYSTEMI.
VEHICLETYPE keywords
Keyword NUMBER |I| Description 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. CROWDCURVE |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. CRUSHCAP |I| Vehicles 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. LOADDISTFAC |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. LONGNAME NAME SEATCAP |S| |S| |I| Optional. Second unique string that identifies the vehicle type (in addition to NAME). Optional. Unique string that identifies the vehicle type. Optional. Vehicles seated capacity. Required for adjustment to link travel time. Valid values range from 1 to 10,000. By default, vehicle has unlimited seating capacity.

Cube Voyager Reference Guide 781

12

Public Transport Program Control statements

Example

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

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 797 for a description of the wait-time calculation. You may define up to 255 wait curves. You may allocate two wait curves to each stop node with IWAITCURVE and XWAITCURVE. Use IWAITCURVE when the node is a trips first boarding point and use XWAITCURVE at transfer points. Use the mode-specific WAITFACTOR to weight the wait time. You must input WAITCRVDEF statements in the Public Transport system data file, specified with SYSTEMI. 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 783 for details about wait curves.
WAITCRVDEF keywords
Keyword NUMBER |I| Description 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. NAME LONGNAME |S| |S| Optional. Unique string that identifies a wait curve. Optional. Second unique string the identifies the wait curve (in addition to NAME).

782 Cube Voyager Reference Guide

Public Transport Program Control statements

12

WAITCRVDEF keywords (continued)

Keyword CURVE |RKV10000| Description 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 783 for information about default wait curves.

Example

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

More on wait 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: IWAITCURVE, used when the node is the trips first boarding point, and XWAITCURVE, used at transfer points in the trip.

Cube Voyager Reference Guide 783

12

Public Transport Program Control statements

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.

Default wait curve for initial boarding

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.
Rules for 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.

784 Cube Voyager Reference Guide

Public Transport Program Control statements

12

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.

Cube Voyager Reference Guide 785

12

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 808 for examples of these reports.

786 Cube Voyager Reference Guide

Public Transport Program Reports

12

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.
Sample enumerated-route report
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.

Cube Voyager Reference Guide 787

12

Public Transport Program Reports

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 788) 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.

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. The following topics show: Example produced with REPORTI Example produced with TRACEI

788 Cube Voyager Reference Guide

Public Transport Program Reports

12

Example produced with REPORTI

Sample evaluated-route report produced with REPORTI
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

Cube Voyager Reference Guide 789

12

Public Transport Program Reports

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

Example produced with TRACEI

Sample evaluated-route report produced with TRACEI
REval Route(s) from Origin 1129 to Destination 757 N: 1129 Mode WaitA TimeA Actual B/XPen Percvd Dist -> 5409 30 14.00 14.00 14.00 0.75 -> 4544 2 5.00 11.00 30.00 3.00 38.00 9.03 79(0.016) 80(0.953) -> 4538 31 3.00 33.00 41.00 0.25 -> 4209 7 7.50 34.85 75.35 1.00 91.85 8.92 -> 757 30 16.00 91.35 107.85 0.10 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 -> 5409 30 14.00 14.00 14.00 0.75 -> 4249 2 5.00 20.00 39.00 3.00 47.00 18.27 76(0.667) 79(0.333) -> 4201 31 1.30 40.30 48.30 0.11 -> 4209 7 7.50 17.70 65.50 1.00 82.00 4.53 -> 757 30 16.00 81.50 98.00 0.10 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 Total Lines(weight) 0.75 9.78 76(0.031) 10.03 18.95 949(1.000) 19.05

Total Lines(weight) 0.75 19.02 19.13 23.66 1359(1.000) 23.76

790 Cube Voyager Reference Guide

Public Transport Program Reports

12

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.

Cube Voyager Reference Guide 791

12

Public Transport Program Reports

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 FAREMATI and used by fare systems defined by the FARESYSTEM control statement.
Sample fare-matrices report
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

792 Cube Voyager Reference Guide

Public Transport Program Reports

12

Transit line summary

You can produce a report summarizing transit lines with the LINES keyword in the REPORT control statement.
Sample transit-line-summary report (with line loadings)
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.

Cube Voyager Reference Guide 793

12

Public Transport Program Reports

Transit line loadings

You can produce a report of transit line loadings with the LINEVOLS keyword in the REPORT control statement.
Sample of transit-line-loading report
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.

794 Cube Voyager Reference Guide

Public Transport Program Reports

12

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.
Sample of transfers-between-modes report
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

Cube Voyager Reference Guide 795

12

Public Transport Program Reports

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.
Sample of transfers-between-operators report
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

796 Cube Voyager Reference Guide

Public Transport Program Theory

12

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

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 Walk time (nontransit time) Wait time In-vehicle time Inconvenience Boarding penalty Transfer penalty

Cube Voyager Reference Guide 797

12

Public Transport Program Theory

Cost Fare

The route-evaluation process considers each component separately. The route enumeration process, described in Route enumeration cost calculation on page 801, uses a slightly simpler estimation. A trips 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.

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.

798 Cube Voyager Reference Guide

Public Transport Program Theory

12

A links 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.

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 IWAITCURVE and XWAITCURVE keywords in the FACTORS control statement. You can weight the wait times with the node-specific WAITFACTOR keyword. The program uses default wait curves at nodes where you do not assign wait curves. See Default wait curves on page 784 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 WAITFACTOR keyword in the FACTORS control statement.

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.

Cube Voyager Reference Guide 799

12

Public Transport Program Theory

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.

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.

Transfer 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 zerothat 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.

800 Cube Voyager Reference Guide

Public Transport Program Theory

12

Fare
By defining fare models, you can include fares in the routeevaluation 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 FARESYSTEM keyword Through their mode or operator attribute, with the FACTORS control statement and FARESYSTEM keyword

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 RUNFACTOR (using the value of the bundles fastest transit line) Boarding penalty Wait time, weighted by WAITFACTOR and subject to a range defined by REWAITMIN and REWAITMAX

Cube Voyager Reference Guide 801

12

Public Transport Program Theory

The route-enumeration process uses a simple estimate of wait time for each leg bundle. The process computes the headway for each bundles boarding node from the sum of the frequencies of the bundles 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
FREQBYMODE:

When true (default value), the process computes these times for individual modes (and the value for fastest mode subsequently used in enumeration). 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 836 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 WAITFACTOR (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 XFERCONST, XFERFACTOR, and XFERPEN) when identifying discrete routes.

802 Cube Voyager Reference Guide

Public Transport Program Theory

12

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

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

Cube Voyager Reference Guide 803

12

Public Transport Program Theory

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 origindestination pair.

For example, suppose travelers waiting at node N have a choice between two routes to reach the trips 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

804 Cube Voyager Reference Guide

Public Transport Program Theory

12

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.

Network 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 808 for a description of these data structures.

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.

Cube Voyager Reference Guide 805

12

Public Transport Program Theory

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 attributesbasic cost and number of transfersand 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 820 for a detailed description of this process.

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.

806 Cube Voyager Reference Guide

Public Transport Program Theory

12

For best-path models, the route-evaluation process identifies the best path using a similar evaluation method, and assigns all demand to that route.

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-modea mode that must be used during at least one leg of a public transport route in order for the Public Transport programs route-enumeration process to select that route.

Advantages of the Public Transport 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.

Cube Voyager Reference Guide 807

12

Public Transport Program Theory

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

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 DELMODE, DELACCESSMODE, and DELEGRESSMODE 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

808 Cube Voyager Reference Guide

Public Transport Program Theory

12

Transit 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-attribute report
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 DisLine 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

Cube Voyager Reference Guide 809

12

Public Transport Program Theory

Use the REREPORT control statement and TRNLEGS3 keyword to produce a line-ordered transit-leg report.
Sample transit-leg report for the GMB1-1B transit 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 DisLeg 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.

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

810 Cube Voyager Reference Guide

Public Transport Program Theory

12

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.
Excerpt from node-ordered transit-leg-bundle report
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 DisLine 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

Cube Voyager Reference Guide 811

12

Public Transport Program Theory

time) with *. All legs in a bundle have the same actual in-vehicle time, but the REnum time for the bundles top leg includes an estimate of the bundles waiting time. (Do not confuse this waiting time with the wait time calculated during the route-evaluation process. See Generalized cost on page 797.)

Nontransit 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 transfersthose occurring at a node and those between two nodes connected with a physical nontransit leg.

812 Cube Voyager Reference Guide

Public Transport Program Theory

12

Use the REREPORT control statement and ACCESSLEGS, EGRESSLEGS, and XFERLEGS keywords to produce nontransit-leg reports.
Sample nontransit-leg report: REREPORT ACCESSLEGS
REPORT: ACCESS LEGS DestiDisOrigin 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

Sample nontransit-leg report: REREPORT EGRESSLEGS

REPORT: EGRESS LEGS DestiDisOrigin 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

Cube Voyager Reference Guide 813

12

Public Transport Program Theory

Sample nontransit-leg report: REREPORT XFERLEGS

REPORT: TRANSFER LEGS DestiDisOrigin 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.

Line-zone legs
During network simplification, the program expands access and egress nontransit legslegs from zone to stop node and vice versainto 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:

814 Cube Voyager Reference Guide

Public Transport Program Theory

12

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

Cube Voyager Reference Guide 815

12

Public Transport Program Theory

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.

816 Cube Voyager Reference Guide

Public Transport Program Theory

12

Use the REREPORT control statement and LINEZONLEG1 LINEZONLEG2 keywords to produce line-to-zone nontransit-leg reports.
Sample line-ordered line-to-zone nontransit-leg report (REREPORT LINEZONLEG1)
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

Cube Voyager Reference Guide 817

12

Public Transport Program Theory

Sample zone-ordered line-to-zone nontransit-leg report (REREPORT LINEZONLEG2)

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

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:

818 Cube Voyager Reference Guide

Public Transport Program Theory

12

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 lines first node; passengers must use the line before transferring. Do not permit transfers to a transit lines 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.

Interchanges between two parallel lines

In this case, the program only records one transfer location between Lines A and B instead of fourthe 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

Cube Voyager Reference Guide 819

12

Public Transport Program Theory

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.
Sample line-to-line transfer-leg report (REREPORT LINELINELEG)
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

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 control statement to control the routeenumeration process. The program measures trip cost differently during routeenumeration than during route-evaluation. See Route enumeration cost calculation on page 801.

820 Cube Voyager Reference Guide

Public Transport Program Theory

12

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

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 multirouteenumeration process, described in Enumerating routes on page 824. Because the process starts with transit-leg bundles rather than individual transit legs, the process might disaggregate a minimumcost 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 nontransittransfer 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.

Cube Voyager Reference Guide 821

12

Public Transport Program Theory

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 MAXFERS 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 userspecified 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 destinations minimum-cost route uses more than MAXFERS 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 AONMAXFERS transfers and the route meets any must-use-mode requirements.

Establishing connectivity between 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 MAXFERS, EXTRAXFERS1, and EXTRAXFERS2.

822 Cube Voyager Reference Guide

Public Transport Program Theory

12

Each connector consists of a set of lines: the from line, the to line, and intervening lines required to reach the to line. The connectors 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 routein the next stage. For example, consider the illustrated public transport network.

Simple public transport network illustrating line connectivity

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

Cube Voyager Reference Guide 823

12

Public Transport Program Theory

Line-to-line legs handle all transfersdirect, between lines A and B and lines B and C, and by walking, between lines A and B and lines A and D.

Enumerating routes
After generating the connectors for a transit line, the routeenumeration 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 Record the beginning of the first route: origin zone and nontransit (access) leg. Examine the transfer points between the first two lines of the connector. If the transit leg used on the first line is the bundles 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. Examine each interchange between the two lines in the same way. Repeat the process for the subsequent lines in the connector set until connections have been fully expanded. Output valid routes Examine expanded routes to find routes that link to nontransit legs terminating in zones. 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.

824 Cube Voyager Reference Guide

Public Transport Program Theory

12

For example, consider the connector, line A to line C via line B, shown in the example in Establishing connectivity between lines on page 822. The route-enumeration process generates the routes in the following table.
Origin Zone O O O O O Nontransit Leg O-A (access) O-A (access) O-A (access) O-A (access) O-A (access) A (ride) A (ride) A (ride) A (ride) A-B1 (walk) A-B2 (direct) A-B1 (walk) A-B2 (direct) C (ride) C (ride) C-D (egress) C-D (egress) Transit Leg Nontransit Leg Transit Leg Nontransit Leg Destination Zone x x x D D

The process does not re-record the common parts of routes, shown in italics.

Enumerating routes with 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 821. If this value exceeds the total of the cost (along the minimum-cost path) plus MUMEXTRACOST, 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.

Cube Voyager Reference Guide 825

12

Public Transport Program Theory

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.

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

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

826 Cube Voyager Reference Guide

Public Transport Program Theory

12

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 routeenumeration process only ensures that at least one line in a transitleg 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 routes 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 servicefrequency model; the process does not support the servicefrequency-and-cost model. The calculations of the servicefrequency model are described in Deriving cost used on page 828, Models applied at decision points on page 830, and

Cube Voyager Reference Guide 827

12

Public Transport Program Theory

SFM and SFCM examples on page 836. 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 FREQBYMODE 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 FREQBYMODE is set to F) and allocates all demand to that route forward towards the destination.

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

828 Cube Voyager Reference Guide

Public Transport Program Theory

12

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:
1.0 C ( comp ) = --------- ln

e
alt

( ECD alt )

Where: C(comp)

is the composite cost is a scale parameter which reflects the travelers sensitivity to cost differences is the expected (generalized) cost to destination via a particular alternative

ECDalt

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.

Cube Voyager Reference Guide 829

12

Public Transport Program Theory

Models applied at decision points

This section describes the mathematical models that calculate the conditional probabilities for choices made at a routes decision points. Models are available for cases where there are: Walk choices Transit choices Alternative alighting choices Opportunities for transfer

Walk choices

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:
i ai e P ( walktoi ) = ---------------------------------------------- ( CW i + ECD j ) e

( CW + ECD )

830 Cube Voyager Reference Guide

Public Transport Program Theory

12

Where: P(walk to i)

is the probability of walking to boarding stop i is the scaling factor for the model (LAMBDAW) 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 travellers choice. For example, a travellers willingness to walk may relate to familiarity with the network. is the expected (generalized) cost to destination from i. is the expected (generalized) cost to destination from j.

CWi

ECDi ECDj

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.

Cube Voyager Reference Guide 831

12

Public Transport Program Theory

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 alternativesthat is, more trips are allocated to the best route. Conversely, low scaling factors produce trips spread over a wider range of alternatives.

Impact of the different values of scaling factor LAMBDAW

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.

832 Cube Voyager Reference Guide

Public Transport Program Theory

12

Transit choices

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 836 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 servicefrequency 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.
Frequency lineI P uselineI = ----------------------------------------------Frequency lineK

where: P(use line l) is the probability of using line l.

Frequency(line l) is the frequency of line l (in services per hour). Frequency(line k) is the frequency of line k (in 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 828.

Cube Voyager Reference Guide 833

12

Public Transport Program Theory

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 lines 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 lines 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:
Frequency ( combined ) =

P(use l) Frequency(line l)
l

834 Cube Voyager Reference Guide

Public Transport Program Theory

12

where: P(use l) Frequency(line l) is the probability of using line l when a service is at the stop. 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:
P (use l) Frequency (line l) Pr (line l) = -------------------------------------------------------Frequency (combined) Alternative alighting choices

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:
e P (alight at i) = ------------------------- ECD j e
ECD i

Cube Voyager Reference Guide 835

12

Public Transport Program Theory

where: P(alight at i) is the probability of alighting at stop 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 832. ECDi ECDj is the expected (generalized) cost to destination via alternative alighting point i. is the expected (generalized) cost to destination via alternative alighting point j.

Opportunities for 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.

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

Example of the service-frequency model

This example shows: Choices available Results of the service frequency model

836 Cube Voyager Reference Guide

Public Transport Program Theory

12

Choices available
(6) (4) (1) Line 1 2 3 4 5 (2) TravelTime 20 21 22 24 26 (3) Frequency 5 6 2 1 1 Cum Frequency 5 11 13 14 15 (5) Wait Time 12.0 5.455 4.615 4.286 4.0 Cum Travel Time 100 226 270 294 320 (7) Average Travel Time 20 20.545 20.769 21 21.333 (8) Travel + Wait Times 32.0 26.0 25.385 25.286 25.333 (9) Include Line Y Y Y Y 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)

Results of the service frequency model

(3) (1) Line 1 2 3 4 5 (2) Line Frequency 5 6 2 1 1 Cum Frequency at Stop 5 11 13 14 (4) Proportion of Trips 0.357 0.429 0.143 0.0714 0.0

Cube Voyager Reference Guide 837

12

Public Transport Program Theory

Notes: Column(4) = (2)/cumulative frequency at stop

Example of the service-frequency-and-cost model

This example shows: Choice set Results of the service frequency & cost model

Choice set
(4) Average travel time excluding this line (5) Excess travel time over average (6) Wait time without this line (7) Proportion of time when line used (8) Cum effective frequency (9) Wait time including this line (10) Average travel time including this line

(2) (1) Line Line frequency

(3) Travel time

1 2 3 4 5

5 6 2 1 1

20 21 22 24 26

20 20.52 20.707 20.798

1 1.48 3.293 5.202

12 5.714 5.007 4.868

1 0.917 0.742 0.342 0

5 10.500 11.983 12.326 -

12 5.714 5.007 4.868 -

20 20.52 20.707 20.798

Notes: Example uses a wait factor of 2 to weight the waiting times. Column (7) = 1-MIN( (5)/(6)),1) Column (8) = (2)*(7), accumulated over lines Column (9) = 60.0/(7) * 0.5 * Wait Factor Column (10) = ((2)*(3)*(7), accumulated over lines) / (8)

838 Cube Voyager Reference Guide

Public Transport Program Theory

12

Results of the service frequency & cost model

(3) (2) (1) Line 1 2 3 4 5 Line frequency 5 6 2 1 1 Effective frequency at stop 5 5.500 1.483 0.343 (4) Cum frequency at stop 5 10.500 11.983 12.326 (5) Proportion of trips 0.406 0.446 0.120 0.028 -

Notes: Column(5) = (3)/cumulative frequency at stop

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 614 and Skimming Quick reference on page 625.

Cube Voyager Reference Guide 839

12

Public Transport Program Theory

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

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.

840 Cube Voyager Reference Guide

Public Transport Program Theory

12

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 Walk (nontransit) Wait In-vehicle Inconvenience Boarding Transfer Cost 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 valuestrue measures of the costor perceived valuesthe costs 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.

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

Cube Voyager Reference Guide 841

12

Public Transport Program Theory

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

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 pairs trips to the available routes according to each routes probability of use, calculated during the route-evaluation process.

842 Cube Voyager Reference Guide

Public Transport Program Theory

12

For example, consider the reports of enumerated and evaluated routes between zones 1 and 3.
Enumerated routes between zones 1 and 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

Evaluated routes between zones 1 and 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,

Cube Voyager Reference Guide 843

12

Public Transport Program Theory

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

844 Cube Voyager Reference Guide

Public Transport Program Theory

12

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.

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

Overview
Fares are a fundamental element of a public transport trip. Therefore, it is import 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.

Cube Voyager Reference Guide 845

12

Public Transport Program Theory

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 programwide fare system that describes each transit lines 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)

846 Cube Voyager Reference Guide

Public Transport Program Theory

12

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.
STRUCTURE IBOARDFARE FAREFROMFS UNITFARE FARETABLE FAREMATRIX FAREZONE FLAT Required Optional NA NA NA NA DISTANCE Optional Optional Optional
1

HILOW Permissible Optional NA NA Required Required

COUNT Permissible Optional NA Required NA Required

3

FROMTO Permissible Optional NA NA Required Required

ACCUMULATE Permissible Optional NA Required NA Required

Optional2 NA NA

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

Cube Voyager Reference Guide 847

12

Public Transport Program Theory

Trip 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.
Description of trip-length units
Value of STRUCTURE FLAT Method for calculating trip length and fare 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)

848 Cube Voyager Reference Guide

Public Transport Program Theory

12

Description of trip-length units (continued)

Value of STRUCTURE COUNT Method for calculating trip length and fare 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.

Cube Voyager Reference Guide 849

12

Public Transport Program Theory

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.

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

FAREFROMFS Fare incurred when transferring from lines

using other defined fare systems. See FAREFROMFS on page 689.

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

850 Cube Voyager Reference Guide

Public Transport Program Theory

12

See FARETABLE on page 690 for more information about coding FARETABLE. Some graphic examples follow.

Fare table for STRUCTURE=DISTANCE and INTERPOLATE=T

Fare table for STRUCTURE=DISTANCE and INTERPOLATE=F

Cube Voyager Reference Guide 851

12

Public Transport Program Theory

Fare table for fare-zone based fare systems

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

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.

852 Cube Voyager Reference Guide

Public Transport Program Theory

12

The HILOW structure requires an annular fare zone system while the other structures require sequential fare zones. To identify and code fare zones for fare systems with a FROMTO, COUNT, or ACCUMULATE 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

Example of a sequential fare zone system

To identify and code fare zones for fare systems with a HILOW structure
1. Display the network in Cube.

Cube Voyager Reference Guide 853

12

Public Transport Program Theory

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.

Example of an annular zone system

854 Cube Voyager Reference Guide

Public Transport Program Theory

12

Examples
This section shows how fares are calculated for a four-leg trip using different fare models, individually and in combination.
Boarding & alighting points A-B B-C C-D D-E In-vehicle distance (miles) 10 3 2 1

Leg 1 2 3 4

Mode 1=British Rail 2=Underground Piccadilly 2=Underground Bakerloo 3=Bus

Example 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 Leg B-C 2} Leg C-D to 2} Leg D-E 2} = 100 {IBOARDFARE for A-B} + = 75 {FAREFROMFS[1] for B-C, for transferring from FARESYSTEM 1 to = = 0 {FAREFROMFS[2] for C-D, for transferring from FARESYSTEM 2 0 {FAREFROMFS[2] for D-E for transferring from FARESYSTEM 2 to

Example 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

Cube Voyager Reference Guide 855

12

Public Transport Program Theory

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.
Example 3: FROMTO 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.
Example 4: COMBINATION of FROMTO and DISTANCE fare systems

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.

856 Cube Voyager Reference Guide

Public Transport Program Theory

12

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)

Crowding
An iterative process, crowd modeling enables a public transport systems capacity to influence the systems 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

Link-travel-time adjustment
A link-travel-time adjustment models a passengers 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.

Cube Voyager Reference Guide 857

12

Public Transport Program Theory

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 40that is, 34 seatsare 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.

Example of crowding factor values (as a function of vehicle load)

858 Cube Voyager Reference Guide

Public Transport Program Theory

12

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 100. The corresponding crowding curve is shown below.

Crowding curve definition, as a function of utilization

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:
T c = T u CCrv v, c ( U )

where: Tc Tu is the crowded link travel time is the link travel time (in uncrowded conditions)

CCrvv,c (U) is the crowd curve value (where the curve is specific to a vehicle type, v, and a user class, c) for utilization U U is the utilization measure (as a percentage)

Cube Voyager Reference Guide 859

12

Public Transport Program Theory

The utilization measure, U, is defined by the expression:

P ( LDF v SeatCap ) U = -----------------------------------------------------------------------CrushCap ( LDF v SeatCap )

where: P SeatCap is the passenger demand (per hour). 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.)

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

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.

860 Cube Voyager Reference Guide

Public Transport Program Theory

12

Without crowding, the program assigns demand with the servicefrequency 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 bottlenecknot 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.

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

Cube Voyager Reference Guide 861

12

Public Transport Program Theory

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 routechoice process is more responsive to changes in costs.

862 Cube Voyager Reference Guide

Public Transport Program Using the Public Transport program

12

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

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

Cube Voyager Reference Guide 863

12

Public Transport Program Using the Public Transport program

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.

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 653. This section shows which files contain which data items.
FILEI/O keyword FAREI LINEI NTLEGI SYSTEMI LINEO NTLEGO File description Fare system Lines Nontransit leg Public transport system Lines Nontransit leg Valid control statements defining data FARESYSTEM LINE NT MODE, OPERATOR, VEHICLETYPE, WAITCRVDEF, and CROWDCRVDEF LINE NT

864 Cube Voyager Reference Guide

Public Transport Program Using the Public Transport program

12

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 lines 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 networks 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 lines travel times up or down to match these control values. You might use control values in base-year models to ensure that the lines travel time matches an expected value.

Cube Voyager Reference Guide 865

12

Public Transport Program Using the Public Transport program

For forecast years, when you do not know the lines 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 lines 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 lines 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 lines 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 nodes 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.

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

866 Cube Voyager Reference Guide

Public Transport Program Using the Public Transport program

12

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

Transit 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 lines base linktime in a variety of way, as described in LINE on page 745.) You can use different techniques to specify a links transit time. Possible techniques include: Set a links 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.

Cube Voyager Reference Guide 867

12

Public Transport Program Using the Public Transport 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 records 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 878.

Nontransit 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 costsperceived or actualconsistent with the cost components that the routeenumeration 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.

868 Cube Voyager Reference Guide

Public Transport Program Using the Public Transport program

12

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

Generating nontransit access and egress legs

The GENERATE statement is a powerful and flexible tool that generates the components of the nontransit networkaccess, egress, and transfer legs. However, misuse can generate unnecessary legs, resulting in poor quality routing.
Example 1: Drive-walk nontransit 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

Cube Voyager Reference Guide 869

12

Public Transport Program Using the Public Transport program

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 routeenumeration 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.)

870 Cube Voyager Reference Guide

Public Transport Program Using the Public Transport program

12

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 AM4L89Cost= 30.8287 Probability=0.2803 1 -> 4322 4322 -> 4325 -> 4325 lines AM4L5 AM4L6- AM4L18 4325 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 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 AM4L89Cost= 34.98 Probability=0.0959 1 -> 4322 4322 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 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.

Cube Voyager Reference Guide 871

12

Public Transport Program Using the Public Transport program

Some useful GENERATE keywords to control the excessive generation of nontransit legs are:
SLACK MAXNTLEGS DIRECTLINK

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.

872 Cube Voyager Reference Guide

Public Transport Program Using the Public Transport program

12

Example 1: Drive-only route

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

Cube Voyager Reference Guide 873

12

Public Transport Program Using the Public Transport program

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

874 Cube Voyager Reference Guide

Public Transport Program Using the Public Transport program

12

In this example, the transit routes are much slower than the driveonly 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 nontransitonly 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 869.

Cube Voyager Reference Guide 875

12

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

Example 1: Preparing a public transport network

This example prepares a public transport network from: Network program-produced network, providing the basic infrastructure of zones, nodes and links (input with NETI) Line data (input with LINEI[1]) Public Transport system data (input with SYSTEMI) Factor data for route-enumeration and route-evaluation processes (input with FACTORI)
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.

876 Cube Voyager Reference Guide

Public Transport Program Examples

12

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

Cube Voyager Reference Guide 877

12

Public Transport Program Examples

Example 2: Preparing a public transport network from TRIPS link data

This example prepares a public transport network from TRIPSformatted 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

878 Cube Voyager Reference Guide

Public Transport Program Examples

12

;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

Cube Voyager Reference Guide 879

12

Public Transport Program Examples

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

880 Cube Voyager Reference Guide

Public Transport Program Examples

12

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, DEC=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) MW[5]=XWAITA(0) MW[6]=IWAITP(0) MW[7]=XWAITP(0) MW[8]=TIMEA(0,ALLMODES) ;initial wait time, actual, avg ;transfer wait time, actual, avg ;initial wait time, perceived, avg ;transfer wait time, perceived, avg ;time for all modes, actual

Cube Voyager Reference Guide 881

12

Public Transport Program Examples

MW[9]=TIMEA(0,1,7,8,11) actual, avg MW[11]=TIMEP(0,ALLMODES) MW[12]= TIMEP(0,TMODES) perceived, MW[13]= TIMEP(0,33,-35)

;in-vehicle time for transit modes, ;time for all modes, perceived, avg ;in-vehicle time for transit modes, ;avg ;walk/ride time for non-transit modes, ;perceived, avg ;boarding penalty for all modes, avg ;boarding penalty for transit modes, ;transfer penalty for all modes, ;transfer penalty for transit modes, ;avg

MW[14]= BRDPEN(0,ALLMODES) MW[15]= BRDPEN(0,TMODES) avg MW[16]= XFERPENA(0, ALLMODES) actual, avg MW[17]= XFERPENP(0, 1,7,-8,11) perceived,

MW[18]= DIST(0,ALLMODES) MW[19]= DIST(0,TMODES) modes, avg MW[20]= DIST(0,NTMODES) modes, avg MW[21]= BRDINGS(0,ALLMODES) avg MW[22]= BRDINGS(0,TMODES) modes, same as

;distance for all modes, avg ;in-vehicle distance for transit ;walk/ride distance for non-transit

;number of boardings for all modes, ;number of boardings for transit ;above, avg

MW[23]=BESTJRNY ENDPHASE

;best travel time

;MATO loops over J for each I. All skims extracted above are reported PHASE=MATO if(ROWSUM(2) if(ROWSUM(3) FORM=10.2 if(ROWSUM(4) if(ROWSUM(5) if(ROWSUM(6) if(ROWSUM(7) > 0) PRINTROW mw=2 TITLE='Compcost', BASE1=T, FORM=10.2 > 0) PRINTROW mw=3 TITLE='ValOfChoice', BASE1=T,

> > > >

0) 0) 0) 0)

PRINTROW PRINTROW PRINTROW PRINTROW

mw=4 mw=5 mw=6 mw=7

TITLE='IWAITA', TITLE='XWAITA', TITLE='IWAITP', TITLE='XWAITP',

BASE1=T, BASE1=T, BASE1=T, BASE1=T,

FORM=10.2 FORM=10.2 FORM=10.2 FORM=10.2

882 Cube Voyager Reference Guide

Public Transport Program Examples

12

if(ROWSUM(8) FORM=10.2 if(ROWSUM(9) FORM=10.2 if(ROWSUM(11) FORM=10.2 if(ROWSUM(12) FORM=10.2 if(ROWSUM(13) FORM=10.2 if(ROWSUM(14) FORM=10.2 if(ROWSUM(15) FORM=10.2 if(ROWSUM(16) FORM=10.2 if(ROWSUM(17) FORM=10.2 if(ROWSUM(18) FORM=10.2 if(ROWSUM(19) FORM=10.2 if(ROWSUM(20) FORM=10.2 if(ROWSUM(21) FORM=10.2 if(ROWSUM(22) FORM=10.2 if(ROWSUM(23) ENDPHASE ENDRUN

> 0) PRINTROW mw=8 > 0) PRINTROW mw=9

TITLE='TIMEA ALLMODES', BASE1=T, TITLE='TIMEA TMODES', BASE1=T,

> 0) PRINTROW mw=11 > 0) PRINTROW mw=12 > 0) PRINTROW mw=13

TITLE='TIMEP ALLMODES', BASE1=T, TITLE='TIMEP TMODES', BASE1=T, TITLE='TIMEP NTMODES', BASE1=T,

> 0) PRINTROW mw=14 > 0) PRINTROW mw=15 > 0) PRINTROW mw=16 > 0) PRINTROW mw=17

TITLE='BRDPEN ALLMODES', BASE1=T, TITLE='BRDPEN TMODES', BASE1=T, TITLE='XFERPEN ALLMODES', BASE1=T, TITLE='XFERPEN TMODES', BASE1=T,

> 0) PRINTROW mw=18 > 0) PRINTROW mw=19 > 0) PRINTROW mw=20

TITLE='DIST ALLMODES', BASE1=T, TITLE='DIST TMODES', BASE1=T, TITLE='DIST NTMODES', BASE1=T,

> 0) PRINTROW mw=21 > 0) PRINTROW mw=22 > 0) PRINTROW mw=23

TITLE='BRDINGS ALLMODES', BASE1=T, TITLE='BRDINGS TMODES', BASE1=T, TITLE='BESTJRNY', BASE1=T, FORM=10.2

Public transport loading

This example loads a trip matrix, input with MATI[1], on to a previously prepared public transport network.

Cube Voyager Reference Guide 883

12

Public Transport Program Examples

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 reportsline 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 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 NETI Lines input on LINEI[1] Factors input on FACTORI[1] and FACTORI[2]

884 Cube Voyager Reference Guide

Public Transport Program Examples

12

Public Transport system data input on SYSTEMI

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 MATO[1] and MATO[2], and reports. Loading Loads trip matrices input on any MATI 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

Cube Voyager Reference Guide 885

12

Public Transport Program Examples

FILEI LINEI[1] = ISL_PTLINES.LIN FILEI NETI =LDHWN00A.NET ;Globals PARAMETERS PARAMETERS PARAMETERS PARAMETERS

TRANTIME=li.TrnsTime USERCLASSES=1,2 TRIPSIJ[1] = Mi.01.1 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

886 Cube Voyager Reference Guide

Public Transport Program Examples

12

ENDRUN

Cube Voyager Reference Guide 887

12

Public Transport Program Examples

888 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 889

13

TRNBUILD Program

13

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 Example Converting from TRNPTH to TRNBUILD

890 Cube Voyager Reference Guide

TRNBUILD Program Using TRNBUILD in Cube Voyager

13

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.

Cube Voyager Reference Guide 891

13

TRNBUILD Program Using TRNBUILD in Cube Voyager

The process is static; you cannot alter processes on a zone-byzone basis.

892 Cube Voyager Reference Guide

TRNBUILD Program Introduction to TRNBUILD

13

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 modechoice 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 combinationsa more complex process than path development for highway processing. A transit network contains lines and support links. Lines are userdefined transit routes. Support linksnontransit links that provide connectivity between different transit lines and between zone centroids and linesare 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 lines 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

Cube Voyager Reference Guide 893

13

TRNBUILD Program Introduction to TRNBUILD

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 links A-node, rather than from the zone to a stop node at the links B-node. You must initiate zonal access with the ZONEACCESS control statement.

894 Cube Voyager Reference Guide

TRNBUILD Program Introduction to TRNBUILD

13

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-toPNR-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.
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 928).

Cube Voyager Reference Guide 895

13

TRNBUILD Program Introduction to TRNBUILD

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 lines 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 60minute 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 paths 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

896 Cube Voyager Reference Guide

TRNBUILD Program Introduction to TRNBUILD

13

segment modes (see FACTOR on page 905). 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 segments 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

Cube Voyager Reference Guide 897

13

TRNBUILD Program Introduction to TRNBUILD

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 line-combining process

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. TRNBUILDs 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 modes 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 lines 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.

898 Cube Voyager Reference Guide

TRNBUILD Program Introduction to TRNBUILD

13

A new wait time is computed for each line by subtracting the best run time from the lines 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 lines 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.

Cube Voyager Reference Guide 899

13

TRNBUILD Program Introduction to TRNBUILD

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

Trip matrix processing

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

900 Cube Voyager Reference Guide

TRNBUILD Program Introduction to TRNBUILD

13

Level-of-service extraction

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 912. 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 927.
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 links nodes. See also FILEO on page 912.

Cube Voyager Reference Guide 901

13

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 cant 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.
Control word COMBINE FACTOR FARE FARELINKS FILEI FILEO LINE LINK MATRICES MULTIACCESS PARAMETERS PHASE1 Specify basic parameters Initialization parameters Description Line combination specifications Various mode and mode-to-mode factors Compute fares from path Establish fare links Input files Output files Describe public transport lines Insert underlying links for LINES Compute path level-of-service matrices

902 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

Control word PNR REPORT SEGLIMITS SELECT SUPPLINK SUPPORT TRIPS XFERGEN XY ZONEACCESS

Description Drive access specifications Request standard reports Travel segment limits Select process zones Describe single nontransit links Describe multiple non-transit links Input trip matrices Generate transfer support links Add / modify node coordinates Walk access specifications

COMBINE
Line-combining specification. IF MAXDIFF

Cube Voyager Reference Guide 903

13

TRNBUILD Program Control statements

COMBINE keywords
Keyword IF |s255*| Description 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: MAXDIFF |R255*| 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

<0> is the first process tested in the combination decision process. If the lines total time does not exceed best time + MAXDIFF, the line will be combined with the best line.

904 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

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

FACTOR
Wait, xfer, mode factors. BOARDPEN IWAITFAC IWAITMAX IWAITMIN MODEFAC NOX XPEN XPENFAC XWAITFAC XWAITMAX XWAITMIN MAXWAITTIME (NODES)
FACTOR keywords
Keyword BOARDPEN Subkeyword |KRV15*| Description 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. Factor to convert initial wait time for a mode to perceived wait time. Maximum actual initial wait time allowed. Minimum actual initial wait time allowed. Factor to convert link time to perceived time. Used to preclude a path from going directly between links which have certain modes. A true value is used to preclude the path. Value to be added to the path time at each node. The value is in actual time and must be 0-60.

IWAITFAC IWAITMAX IWAITMIN MODEFAC NOX

|KRV255*| |KRV255*| |KRV255*| |KRV255*| |K?V255[255]*|

XPEN

|KRV255[255]*|

Cube Voyager Reference Guide 905

13

TRNBUILD Program Control statements

FACTOR keywords (continued)

Keyword XPENFAC XWAITFAC XWAITMAX XWAITMIN MAXWAITTIME Subkeyword |KRV255[255]*| |KRV255*| |KRV255*| |KRV255*| |R| Description Factor to convert XPEN to perceived time. Factor to convert transfer wait time to perceived wait time. Maximum actual transfer wait time allowed. Minimum actual transfer wait time allowed. <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. 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-1000000 can be used to set all nodes. The English short name is N.

MAXWAITTIME

NODES

|IPV|

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

906 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

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

FARE
Fare values MODEFARE XFARE

Cube Voyager Reference Guide 907

13

TRNBUILD Program Control statements

FARE keywords
Keyword MODEFARE |KIV255*| Description 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 variable. The highest MODEFARE encountered for a path is stored in the MAXMODEFARE variable. The MODEFARE and MAXMODEFARE variables can be accessed via the MATRICES statement. 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 variable, and the highest XFARE is saved in the MAXXFARE variable. The XFARE and MAXXFARE variables can be accessed via the MATRICES statement.

XFARE

|KIV255*255|

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 924).

908 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

Example
FARE MODEFARE=3*50,0,0,4*75,0 ; sets transit fares for modes 1-10 XFARE[11] = 10*50, XFARE[12] = 10*50;

FARELINKS
Set fare links. FARE MODES L ONEWAY 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

Cube Voyager Reference Guide 909

13

TRNBUILD Program Control statements

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.
FARELINKS keywords
Keyword FARE MODES L |R| |IVP| |IVP| Description Fare assessed to the links on the statement. Modes for which the specified links apply. Each statement must specify at least one valid mode. 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. 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.

ONEWAY

|?|

Example
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

FILEI
Input data files

910 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

NETI MATI FAREMATI

FILEI keywords
Keyword NETI MATI FAREMATI |KF| |KF| |KFV255| Description Name of the input network file. Name of the input trips matrix file. See TRIPS on page 945 for details. 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

Cube Voyager Reference Guide 911

13

TRNBUILD Program Control statements

there are entries for any combinations of the modes 100-101-102103, 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.)
Example
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

FILEO
Output files MATO NETO (MODES STOPSONLY) Currently Disabled! SUPPORTO (MODES FIXED ONEWAY) LINKO

912 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

NODEO LINEVOLO (ID FORMAT) LINKVOLO (ID FORMAT)

FILEO keywords
Keyword LINEVOLO Subkeyword |KF| Description 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. Specifies the format for writing LINEVOLO records. Possible values: LINEVOLO ID |S| TXT CSV (or any word that begins with C) Indicates comma separated values. T Indicates fixed-length fields (default value).

LINEVOLO

FORMAT

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

Cube Voyager Reference Guide 913

13

TRNBUILD Program Control statements

FILEO keywords (continued)

Keyword LINKO Subkeyword |KF| Description 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). LINKVOLO |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.

914 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

FILEO keywords (continued)

Keyword LINKVOLO Subkeyword FORMAT |S| Description Specifies the format for writing LINKVOLO records. Possible values: LINKVOLO MATO NETO ID |S| |KF| |KF| TXT CSV (or any word that begins with C) Indicates commaseparated values. T Indicates fixed-length fields (default).

ID that the program writes as the last field in the LINKVOLO records. Name of the file where program writes MATRICES. 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. Modes included when writing links to the NETO file. If no modes are designated, the program includes all modes by default. 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.

NETO NETO

MODES STOPSONLY

|IVP| |?|

NODEO

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

|KF|

Cube Voyager Reference Guide 915

13

TRNBUILD Program Control statements

FILEO keywords (continued)

Keyword SUPPORTO Subkeyword FIXED |?| Description Flag that indicates how the program writes the data fields to statements in the SUPPORTO file: SUPPORTO ONEWAY |?| False Indicates statements are completely free form. True Indicates fixed-length fields, providing easier browsing, but requiring more disk space. 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.

Flag that indicates how the program writes support links:

SUPPORTO

MODES

|IVP|

Support modes that program selects when writing to SUPPORTO file. If you designate no modes, the program will issue a fatal message.

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

916 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

SUPPLINK N=7593-3 MODE=11 DIST=20 SPEED=2.5 ONEWAY=Y . .

LINE
Defines transit lines. NAME MODE OWNER FREQUENCY FREQUENCYR ONEWAY TIMEFAC RUNTIME ALLSTOPS XYSPEED COLOR GLOBAL (CLEAR) NODES (ACCESS ACCESS_C DELAY DELAY_C RT SPEED TIME TF XYSPD)
LINE keywords
Keyword ALLSTOPS Subkeyword |?| Description 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 FREQUENCY |I| |RV5*|

Color that Cube Base uses to display the line. 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. 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.

FREQUENCYR

|RV5*|

Cube Voyager Reference Guide 917

13

TRNBUILD Program Control statements

LINE keywords (continued)

Keyword GLOBAL Subkeyword |?| Description 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 transitnetwork editing in Cube Base. Therefore, Citilabs recommends that you not use global values. GLOBAL CLEAR |?| 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. Mode for this line; it may not conflict with support modes used. 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.

MODE NAME

|I| |S|

918 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

LINE keywords (continued)

Keyword NODES Subkeyword |IV| Description List of nodes that the line passes through. Follow each node by another node, or one of the NODES subkeywords. Two adjacent nodeseven if there are intervening subkeywordsform a transit link. Positivenumbered 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 ACCESS |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 lines reverse direction. NODES ACCESS_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 NODES DELAY DELAY_C |R| |R| Additional time delay added to the link time. Code DELAY between two nodes. Additional time delay added to all subsequent links, until program encounters another DELAY_C or DELAY subkeyword.

Cube Voyager Reference Guide 919

13

TRNBUILD Program Control statements

LINE keywords (continued)

Keyword NODES Subkeyword RT |R| Description 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 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. Resets the LINE TIMEFAC value from the current link until the program encounters another TF subkeyword. Sets the operation time for the link surrounding this keyword. 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. ONEWAY |?| 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.

NODES NODES NODES

TF TIME XYSPD

|R| |R| |R|

920 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

LINE keywords (continued)

Keyword RUNTIME Subkeyword |R| Description 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 lines 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. TIMEFAC |R| Multiplier used to compute times along the lines 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. Speed for a lines 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).

XYSPEED

|R|

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 lines working parameters equal to the lines global parameters.

After reading a LINE statement without errors, if GLOBAL is true, the program saves the current line parameters in the lines global area for use by subsequent lines. The program can use a LINE statement with no NAME and no NODES to reset the lines global area. If all

Cube Voyager Reference Guide 921

13

TRNBUILD Program Control statements

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: If TIME has a value, set link time = TIME Else if SPEED has a value, set link time to distance/SPEED Else set link time to link time * TIMEFAC Else if the link is not found but has coordinates: If TIME has a value, set link time to TIME If XYSPEED has a value, set link time to X-Y distance/XYSPEED Else produce an error Else the link can not be determined, so produce an error

Example
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

LINK
Link data for use by LINE definitions (must precede the LINE statement that includes the link).

922 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

NODES DIST SPDCODE LANES SPEED TIME MODES ONEWAY GLOBAL (CLEAR)
LINK keywords
Keyword CLEAR |?| Description Flag that indicates whether the program sets the links global area to all zeroes before beginning any other statement processing. Applies no matter where CLEAR appears on the statement. Distance for the link, usually considered as hundredths of miles, or kilometers. The value may not exceed 20,000. Flag that indicates whether the program saves link values into the links global area. When reading the statement, the program initializes link values from the links global area, and then updates current values based on the statements keyword settings. If GLOBAL is true, the program updates the links 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 891 for notes about the use of GLOBAL. LANES MODES |I| |IVP| Number of directional lanes on the link. See SPDCODE for more details. The value must be 1-9. 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. Indicates the nodes that compose the link. Code the link as a pair of nodes separated by a dash. Flag that indicates which links the program saves: True Program saves A-B and B-A. False Program only saves A-B.

DIST GLOBAL

|I| |?|

NODES ONEWAY

|IVP| |?|

Cube Voyager Reference Guide 923

13

TRNBUILD Program Control statements

LINK keywords (continued)

Keyword SPDCODE |I| Description 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. Time, in minutes, for the link. If specified, the program does not use any keywords associated with speed. The value must be 0-999.

TIME

|R|

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

MATRICES
Output matrix definitions NAME MW[ ]

924 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

MATRICES keywords
Keyword NAME |SV| Description Name of extracted level-of-service matrix written to FILEO MATO. Must be unique.

Cube Voyager Reference Guide 925

13

TRNBUILD Program Control statements

MATRICES keywords (continued)

Keyword MW |NV| Description 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 sum of all mode fares as input via the FARE control statement 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). *** STEPFUNC is a function that scans a set of increasing X 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,

926 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

MATRICES keywords (continued)

Keyword Description 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).

Example
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

MULTIACCESS
Multiaccess assignment keywords. MAXTIMEDIFF MAXPCTDIFF The presence of either of these keywords triggers the multiaccess process discussed in Path building on page 895.
MULTIACCESS keywords
Keyword MAXTIMEDIFF |R| Description 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. 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.

MAXPCTDIFF

|R|

Cube Voyager Reference Guide 927

13

TRNBUILD Program Control statements

Example
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

PARAMETERS
General parameters FREQPERIOD LISTINPUT MAXPATHTIME MAXRUNTIME ONLINE PATHSTYLE BUILDPATHS SEQSIZE USERUNTIME WALKSPEED XYFACTOR ZONEMSG
PARAMETERS keywords
Keyword BUILDPATHS |K?| Description Flag that controls ILOOP processing and path building: FREQPERIOD |KI| True Default value. Program processes the ILOOP and builds paths. False Program skips the ILOOP and builds no paths.

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

LISTINPUT

|K?|

Insert this keyword to reduce volume printed by suppressing certain types of input. MAXPATHTIME |KR| Perceived time limit for path selection. Program does not save paths that exceed this value. Because the pathbuilding 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. Maximum run time length. The program issues a warning for lines with run times that exceed this value.

MAXRUNTIME

|KR|

928 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

PARAMETERS keywords (continued)

Keyword ONLINE |KI| Description 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.

PATHSTYLE

|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 (onethird or one-quarter the length of the default method) and uses less memory. However, this method can produce problems if certain modeto-mode combinations are precluded, or restricted, due to transfer penalties.

SEQSIZE

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

USERUNTIME

|K?|

Cube Voyager Reference Guide 929

13

TRNBUILD Program Control statements

PARAMETERS keywords (continued)

Keyword WALKSPEED |KR| Description 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. 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. 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.

XYFACTOR

|KR|

ZONEMSG

|KI|

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

PHASE1
Initial parameters

930 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

HWYTIME LINKDUMP MAXNODE WORKRAM

PHASE1 keywords
Keyword HWYTIME |KS| Description 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 links 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. LINKDUMP MAXNODE |KI| |KI| Specifies the number of links to be printed for inspection. Used primarily for debugging purposes. 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. 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.

WORKRAM

|KI|

Cube Voyager Reference Guide 931

13

TRNBUILD Program Control statements

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.
Example
MAXNODE=22000 HWYTIME=trantime ; increase highest node PHASE1 MAXNODE=2100

PNR
Specifies park-and-ride link generation. NODE MODE TIME LOTMODE COST DISTFAC MAXTIME ONEWAY SELECT ZONES GLOBAL (CLEAR)
PNR keywords
Keyword CLEAR |?| Description 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. GLOBAL |?| 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 891 for notes about the use of GLOBAL. LOTMODE MAXTIME |I| |R| Mode assigned to the lot link. The value must not conflict with any transit modes being used. 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.

932 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

PNR keywords (continued)

Keyword MODE |I| Description Mode assigned to the zone-to-node support link developed. The value must not conflict with any transit modes being used. Node to which the program generates an access link from each zone specified in ZONES via the PNR accessdevelopment process. That process builds the best highwaytime 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 statements 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. ONEWAY |?| Flag that indicates whether to configure generated (zoneto-node and lot) links as one-way.

NODE

|IVP|

Cube Voyager Reference Guide 933

13

TRNBUILD Program Control statements

PNR keywords (continued)

Keyword SELECT |?| Description 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.

TIME ZONES |R| |IVP|

Time assigned to the lot link. 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 links 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.
Example
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

REPORT
Report requests CAPACITY LINES LINESTRING LINEVOL (LINESORT MODES STOPSONLY) LINKVOL (FULL MODES STOPSONLY)

934 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

NODEVOL (MODES) SPEED RUNTIMEADJ

REPORT keywords
Keyword CAPACITY Subkeyword |?| Description Flag that indicates whether to produce a report of the capacities stored in the input highway networks SPDCAP table. 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. 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.

LINES

|SV|

LINESTRING

|S|

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. LINEVOL |?| 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 lines 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.

Cube Voyager Reference Guide 935

13

TRNBUILD Program Control statements

REPORT keywords (continued)

Keyword LINEVOL Subkeyword LINESORT |?| Description Flag that indicates order of line-volume report: LINEVOL LINEVOL MODES STOPSONLY |IP| |?| True Write report sorted by line name False Write report in input order

Transit modes included in line-volume report. If not specified, report includes all transit modes. Flag that indicates whether to restrict the line-volume report to stop-to-stop links only: True Line-volume report only includes stop-tostop 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.

LINKVOL |?|

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. Flag that indicates whether to include all linkseven zero-volume linksin the link-volume report: True Include all links. False Default value. Include only used links.

LINKVOL

FULL

|?|

LINKVOL LINKVOL

MODES STOPSONLY

|IP| |?|

Transit modes included in link-volume report. If not specified, report includes all transit modes. Flag that indicates whether to restrict the link-volume report to stop-to-stop links only: True Link-volume report only includes stop-tostop links; the report does not consider intermediate nodes to be link nodes False Link-volume report includes all links.

NODEVOL |?|

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.

936 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

REPORT keywords (continued)

Keyword NODEVOL RUNTIMEADJ Subkeyword MODES |IP| |?| Description Transit modes included in node-volume report. If not specified, report includes all transit modes. 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 networks 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. Example
REPORT REPORT REPORT REPORT REPORT REPORT CAPACITY=n SPDCODE=y RUNTIMEADJ=y LINKVOL=y FULL=y ;list all links in the network. LINEVOL=y, LINESORT=y, STOPSONLY=n LINES= Name, Mode, ORDER; LINESTRING=MU?## ;report all MUNI numbered lines NODEVOL=y MODES=1,3-7,10

SEGLIMITS
Limits nontransit travel segments during path building (not during network construction).

Cube Voyager Reference Guide 937

13

TRNBUILD Program Control statements

MAXDIST MAXTIME MODES

SEGLIMITS keywords
Keyword MAXDIST MAXTIME MODES |I| |R| |IP| Description Maximum distance (in 1/100 miles) allowed in a segment. Maximum time (in minutes) allowed in a segment. 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.
Example
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

SELECT
Zone and miscellaneous selection

938 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

ACCESSMODES I J IJ SKIPMODES TRACE

SELECT keywords
Keyword ACCESSMODES |KIVP| Description 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 J IJ |KIPV| |KIPV| |Ks| Origin zones to be processed. If not specified, the program processes all I zones. Destination zones to be processed. If not specified, the program processes all J zones. 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). Modes not included in path building. Use to preclude a certain type of access. TRACE |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.

SKIPMODES

|KIPV|

Example
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

Cube Voyager Reference Guide 939

13

TRNBUILD Program Control statements

SUPPLINK
Direct input of nontransit links. 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. NODES MODE TIME SPEED DIST ONEWAY XYFAC XYALL
SUPPLINK keywords
Keyword DIST MODE NODES |I| |I| |IP| Description Distance (in 100th of units) to be assigned to the link. Mode assigned to the link. The value may not conflict with transit modes being used. Nodes of a support (nontransit) link. The link must have a valid distance. See Logic for obtaining link distance on page 944 for a description of the logic used to obtain the distance. N is an alternate form for this keyword. Flag that indicates whether to save link in one or both directions: SPEED |R| True Save the generated links as one-way links (a-b only). False Default value. Save the generated links as twoway links (a-b and b-a).

ONEWAY

|?|

Speed used for computing the link time.

940 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

SUPPLINK keywords (continued)

Keyword TIME XYALL |R| |?| Description Travel time for the link. 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.

XYFAC

|?|

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 944. 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.
Example
SUPPLINK MODE=13, SPEED=60, N=21-22 DIST=300 SUPPLINK NODES=21-22 MODE=15 DIST=500 TIME=20

SUPPORT
Direct input of nontransit links.

Cube Voyager Reference Guide 941

13

TRNBUILD Program Control statements

NODES MODES SPEED DIST XYFAC XYALL LISTLINK GLOBAL (CLEAR)

SUPPORT keywords
Keyword CLEAR |?| Description 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. DIST GLOBAL |I| |?| Distance assigned to a link generated in a node string, if the string generates only one link. 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. LISTLINK MODES |?| |IV| Flag that indicates whether to list all the generated links. Use primarily for debugging. Modes assigned to the generated links on this statement. The values must not conflict with transit modes being used.

942 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

SUPPORT keywords (continued)

Keyword NODES |IV| Description 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 944. 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. ONEWAY |?| Flag that indicates whether to save link in one or both directions: SPEED |R| True Save the generated links as one-way links (a-b only). False Default value. Save the generated links as twoway links (a-b and b-a).

Speed used to compute the link times for all generated links.

Cube Voyager Reference Guide 943

13

TRNBUILD Program Control statements

SUPPORT keywords (continued)

Keyword XYALL |?| Description 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.

XYFAC

|?|

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 944. 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).

Logic for obtaining 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: If nodes have valid coordinates, compute distance from the coordinates 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

944 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

Example
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

TRIPS
Specify trip processing MATRIX (ASSIGN (VOLUMES BOARDS EXITS OLINKS) )
TRIPS keywords
Keyword MATRIX Subkeyword |S| Description 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 nonTP+ 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.

Cube Voyager Reference Guide 945

13

TRNBUILD Program Control statements

TRIPS keywords (continued)

Keyword MATRIX Subkeyword ASSIGN |?| Description 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 |?| EXITS |?| Flag that indicates whether to accumulate separate boarding volumes for each stop node. 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. MATRIX ASSIGN (continued) 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

946 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

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.
Example
TRIPS TRIPS TRIPS TRIPS MATRIX=MI.1.3, MATRIX=?14.1 ; MATRIX=MI.1.3, MATRIX=MI.1.3, ASSIGN=y, BOARDS=n,EXITS=n matrix 1 from xxxx14.DAT -- MINUTP notation ASSIGN=Y, OLINKS=5000-5001,5100-5101,5101-5100 ASSIGN=Y, OLINKS=5000-5001,5100--5101 ; same

XFERGEN
Generate transfer support links. MODE MAXDIST 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.
XFERGEN keywords
Keyword MODE MAXDIST |I| |RV255| Description Mode assigned to the generated links. The value must be a nontransit mode. Maximum distance to search for a stop node for the mode. The keywords 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:

Cube Voyager Reference Guide 947

13

TRNBUILD Program Control statements

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.

XY
Insert or revise coordinates NODE (X Y) XY
XY keywords
Keyword NODE Subkeyword |I| Description Node for which the statement defines coordinates. The value must be between 1 and MAXNODE (or highest node in the network). X-coordinate for NODE. The value must be 12147483647. Y-coordinate for NODE. The value must be 12147483647. 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 commaseparated coordinates (X-coordinate, Ycoordinate); uses spaces to separate additional pairs of coordinates. The program automatically increments the node for additional coordinates.

NODE NODE XY

X Y

|I| |I| |IV|

Example
XY NODE=137, X=234123, Y=327500, NODE=138, X=234123, Y=327510 XY XY[137]= 234123,327500 234123,327510 ;Same as above

948 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

ZONEACCESS
Zonal access development (not PNR) parameters GENERATE (DIRECTION LIST MAXLINKS MAXSTOPS MAXDIST MODE SELECT) LINK (DIST MODE ONEWAY)
ZONEACCESS keywords
Keyword GENERATE GENERATE DIRECTION Subkeyword |?| |I| Description Flag that indicates whether to generate zonal-access support links. Direction of all zonal-access links: GENERATE LIST |?| 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.

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

MAXLINKS

|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

MAXDIST

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

Cube Voyager Reference Guide 949

13

TRNBUILD Program Control statements

ZONEACCESS keywords (continued)

Keyword GENERATE Subkeyword MAXSTOPS |IV255*| Description Maximum number of access links allowed for any zone to each mode. The value must be 0-20. Default value is 5. GENERATE MODE |I| Mode assigned to the generated links. You must code this keyword. The value may not conflict with transit modes being used. GENERATE SELECT |?| 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. LINK |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 LINK LINK DIST MODE ONEWAY |I| |I| |?| Distance assigned to all the specified links. If DIST is not coded, program treats links distance as 0. Mode assigned to the specified links. If not specified, defaults to the mode specified by GENERATE MODE. 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 zonalaccess links. The functions are independent: Even if the statement

950 Cube Voyager Reference Guide

TRNBUILD Program Control statements

13

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 links A-node as an equivalent stop node to the transit modes that stop at the links B-node. The program then generates a zonal-access link directly from the origin zone to the links A-node. To use the statement properly, the transit stop at the links 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.
Example
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

Cube Voyager Reference Guide 951

13

TRNBUILD Program Example

Example
/* 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 with Viper. */ 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

952 Cube Voyager Reference Guide

TRNBUILD Program Converting from TRNPTH to TRNBUILD

13

Converting from TRNPTH to TRNBUILD

TRNBUILD is a more robust transit processor than the TRNPTH program, found in MINUTP. However, some TRNPTH data does not convert directly to TRNBUILD. LINE records are the largest part of the programs data, but the LINE structures are somewhat different. Using TRNPTH, you can convert LINE records to TRNBUILD format. TRNBUILD offers no translation capability. To initiate conversion in TRNPTH, use a TRNBUILD statement. When TRNPTH encounters a TRNBUILD statement, it closes any previously opened TRNBUILD files, opens another file, and sets up the process to convert any LINE statements that follow the TRNBUILD statement. By judiciously using TRNBUILD statements, you can segregate the LINE data into separate files. If a TRNBUILD file remains open after processing all input, TRNPTH writes equivalent PNR statements to the file. The format of the TRNPTH TRNBUILD statement is:
TRNBUILD filename

When converting TRNPTH files to TRNBUILD, you need not run a complete TRNPTH job. Use STOP=1 to complete the conversion, and preclude full processing.

Cube Voyager Reference Guide 953

13

TRNBUILD Program Converting from TRNPTH to TRNBUILD

954 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 955

14

Utilities

14

Utilities

This chapter describes utilities. Topics include: UB2TPP TPP2UB SYNCHIMP Saturn conversion

956 Cube Voyager Reference Guide

Utilities UB2TPP

14

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.
Statement FILEI FILEO PARAMETERS Description Specify input SUMMIT UB file Specify output TPP/Cube Voyager file Set static parameters

FILEI
Inputs data file. MATI
Keyword MATI |KF| Description Specifies the filename of the binary user benefit file created by the FTA SUMMIT program

Cube Voyager Reference Guide 957

14

Utilities UB2TPP

FILEO
Outputs data files. MATO VARO
Keyword MATO VARO |KF| |KF| Description Specifies the filename of the converted TP+/Cube Voyager binary matrix file. 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

PARAMETERS
Sets general parameters. HEADERONLY
Keyword HEADERONLY |?| Description <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.

958 Cube Voyager Reference Guide

Utilities TPP2UB

14

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.
Control statement FILEI FILEO PARAMETERS Description Specify input TP+/Cube Voyager input file and the user benefit variable file. Specify output binary user benefit file. Set static parameters.

FILEI
Inputs data files. MATI VARI
Keyword MATI VARI |KF| |KF| Description Specifies the filename of the binary TP+/Cube Voyager matrix file to be converted. Specifies an optional variable file that contains the variable information for the user benefit file header.

FILEO
Outputs data files. MATO
Keyword MATO |KF| Description Specifies the filename of the converted binary user benefit file.

Cube Voyager Reference Guide 959

14

Utilities TPP2UB

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
PARAMETERS keywords
Keyword ALTNAME AUTOCOEF PURPOSE TOD TRNCOEF |KS| |KS| |KS| |KS| |KS| Description User Benefit ALTNAME value User Benefit AUTOCOEF value User Benefit PURPOSE value User Benefit TOD value User Benefit TRNCOEF value

960 Cube Voyager Reference Guide

Utilities SYNCHIMP

14

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 Tools menu.

The following control statements are available in the Cube Voyager SYNCHMP utility program.
Control statement FILEI FILEO PARAMETERS Description Specify input SYNCHRO files. Specify output Cube Voyager files. Set static parameters.

FILEI
Inputs data files. LAYOUTI LANESI PHASINGI TIMINGI VOLUMEI
FILEI keywords
Keyword LANESI LAYOUTI |KF| |KF| Description Specifies the filename of the input SYNCHRO LANES file. Specifies the filename of the input SYNCHRO LAYOUT file.

Cube Voyager Reference Guide 961

14

Utilities SYNCHIMP

FILEI keywords (continued)

Keyword PHASINGI TIMINGI VOLUMEI |KF| |KF| |KF| Description Specifies the filename of the input SYNCHRO PHASING file. Specifies the filename of the input SYNCHRO TIMING file. Specifies the filename of the input SYNCHRO VOLUME file.

FILEO
Outputs data files. NODEO LINKO JUNCDATAO
Keyword JUNCDATAO LINKO NODEO |KF| |KF| |KF| Description Specifies the filename of the output intersection data file. Specifies the filename of the output link file. Specifies the filename of the output node file.

PARAMETERS
Sets general parameters. The values of these parameters are stored in the associated SYNCHRO input CSV data files. PLANID VOLDATE VOLTIME

962 Cube Voyager Reference Guide

Utilities SYNCHIMP

14

UNITS
PARAMETERS keywords
Keyword PLANID VOLDATE VOLTIME UNITS |KS| |KS| |KS| |KS| Description Specifies the PLAN ID value in the TIMING file. Specifies the date value in the VOLUME file. Specifies the time value in the VOLUME file. Specifies the units of the LANES file. Valid values are meters or feet.

Cube Voyager Reference Guide 963

14

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 several ways: Windows Explorer Command line or batch file Cube Base (from the Tools menu choose Convert Saturn Path File to Voyager Path File)

This section discusses: Running from program window Running from command line

Running from program window

If you access SaturnPath from Cube Base or 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.

964 Cube Voyager Reference Guide

Utilities Saturn conversion

14

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. Convert Click to run the utility and convert the specified

input into a Cube Voyager-formatted path file and write the results to the specified output file.
Close Click to close the program window. Show Saturn File Statistics Click to show statistics about the Saturn file (number of paths, minimum and maximum zone number, node number, class number, route number, flow, and number of nodes in path).

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.

Cube Voyager Reference Guide 965

14

Utilities Saturn conversion

966 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 967

15

Cube Cluster

15

Cube Cluster

This chapter discusses Cube Cluster, an optional extension you can use with Cube Voyager. Topics include: Using Cube Cluster Control statements Utilities

968 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

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 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. Highperformance 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 nodes calculations affect future calculations on other nodes.

Cube Voyager Reference Guide 969

15

Cube Cluster Using Cube Cluster

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

970 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

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.

Typical 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

Cube Voyager Reference Guide 971

15

Cube Cluster Using Cube Cluster

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

972 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

independently processed (see Procedures that disable intrastep distributed processing on page 982 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

Cube Voyager Reference Guide 973

15

Cube Cluster Using Cube Cluster

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 networks 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 control statement summary

Control statement DISTRIBUTE DistributeMULTISTEP EndDistributeMULTISTEP Wait4Files Description Global control for DP options. Initiates MDP script block in Pilot unless the global switch is off. Ends a MDP script block in Pilot. 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
Control statement DistributeINTRASTEP Description Initiates IDP of the current Matrix or Highway step.

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

974 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

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 Intrastep distributed processing (IDP) Multistep distributed processing (MDP) Procedures that disable intrastep distributed processing Using IDP for steps that summarize zonal values

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.

Cube Voyager Reference Guide 975

15

Cube Cluster Using Cube Cluster

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.

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

976 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

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

Cube Voyager Reference Guide 977

15

Cube Cluster Using Cube Cluster

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

Multistep distributed processing (MDP)

To implement MDP, add the following statement in the CLUSTER script at the beginning of the distributed script block:

978 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

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 992 for additional information on getting multiple instances of Cube Voyager open and configured in wait mode. The ProcessID and the ProcessNum number are used to make up the name of the wait file. ProcessID is the same as defined above for IDP. ProcessNum 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 users 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 Wait4Files 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

The Files keyword specifies a list of all the files to wait for and the CheckReturnCode 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

Cube Voyager Reference Guide 979

15

Cube Cluster Using Cube Cluster

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 Wait4Files 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.
Examples

Intrastep distributed processing:

Run pgm=Matrix

980 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

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

Cube Voyager Reference Guide 981

15

Cube Cluster Using Cube Cluster

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

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 Cube Avenue (dynamic traffic assignment)
FILEO SUBAREAMATO FILEO ESTMICPO FILEO ESTMDATO

982 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

FILEO PATHO REPORT VDTSPD LOG

Matrix program
FREQUENCY RENUMBER REPORT MARGINREC REPORT MARGINS FILEI RECI 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. IF (I=1) and IF (I=Zones) type statements to perform certain calculation/initialization/summary 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:

Cube Voyager Reference Guide 983

15

Cube Cluster Using Cube Cluster

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

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.Zone Type] if (i = zones) ; write RECO at last zone

984 Cube Voyager Reference Guide

Cube Cluster Using Cube Cluster

15

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.Zone Type] 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

Cube Voyager Reference Guide 985

15

Cube Cluster Using Cube Cluster

ro.ZoneType = zt ro.SFDU = zi.1.SFDU[zt] write reco=1 endloop exit endrun

986 Cube Voyager Reference Guide

Cube Cluster Control statements

15

Control statements
This section describes the control statements for Cube Cluster: DISTRIBUTE DISTRIBUTEMULTISTEP ENDDISTRIBUTEMULTISTEP WAIT4FILES DISTRIBUTEINTRASTEP

DISTRIBUTE
The DISTRIBUTE statement globally controls the DP options to turn on/off intrastep or multistep distribute processing. MULTISTEP INTRASTEP
DISTRIBUTE keywords
Keyword MULTISTEP INTRASTEP |?| |?| Description Global MULTISTEP DP on/off Global INTRASTEP DP on/off

DISTRIBUTEMULTISTEP
Invoke multistep distributed processing. PROCESSID PROCESSNUM COMMPATH

Cube Voyager Reference Guide 987

15

Cube Cluster Control statements

DISTRIBUTEMULTISTEP keywords
Keyword PROCESSID |S| Description 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@). 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). 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.

PROCESSNUM

|I|

COMMPATH

|S|

ENDDISTRIBUTEMULTISTEP
Statement to end current MULTISTEP subprocess.

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 users responsibility to check for sub-process completion before using output files generated by the

988 Cube Voyager Reference Guide

Cube Cluster Control statements

15

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. FILES CHECKRETURNCODE UPDATEVARS PRINTFILES DELDISTRIBFILES
WAIT4FILES keywords
Keyword CHECKRETURNCODE |?| Description Specifies if the return codes from the subprocesses should be checked. When true, the whole run will stop if a sub-process returns with a code 2 (fatal) or higher. Controls the disposition of the MDP temporary communication files. The default is true, meaning to remove all temporary files.

DELDISTRIBFILES

|?|

Cube Voyager Reference Guide 989

15

Cube Cluster Control statements

WAIT4FILES keywords (continued)

Keyword FILES |S| Description 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@). 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. Specifies a list of global variables computed in Pilot and logged from individual programs that should be merged back from the subprocess 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.

PRINTFILES

|S|

UPDATEVARS

|S|

DISTRIBUTEINTRASTEP
Programs: Matrix, Highway

Invoke intrastep distributed processing. Currently only available in Matrix and Highway. PROCESSID PROCESSLIST MINGROUPSIZE SAVEPRN

990 Cube Voyager Reference Guide

Cube Cluster Control statements

15

COMMPATH
DISTRIBUTEINTRASTEP keywords
Keyword COMMPATH |S| Description Common path for checking for availability of processors. Defaults to null (working directory used). 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. The ProcessID is the prefix for the file names used to communicate with the sub-processes. 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. Switch to control if the sub-process print files should be saved or not.

MINGROUPSIZE

|I|

PROCESSID PROCESSLIST

|S| |I|

SAVEPRN

|?|

Cube Voyager Reference Guide 991

15

Cube Cluster Utilities

Utilities
This section describes: Cluster executable Utility functions

Cluster executable
Use the cluster.exe utility program, found in the Cube program folder, to start multiple processing nodes on the local machine. You can access this utility from Cube Base. From the Tools menu, choose Cluster Node Management to open the Cluster Node Management dialog box.

992 Cube Voyager Reference Guide

Cube Cluster Utilities

15

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 Close Nodes to close any processing node (remote or local), and click List Nodes to return the status of any processing node (remote or local). 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/Close/List] [Exit]

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

Cube Voyager Reference Guide 993

15

Cube Cluster Utilities

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.

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 dont 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')

994 Cube Voyager Reference Guide

Cube Cluster Utilities

15

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@

Cube Voyager Reference Guide 995

15

Cube Cluster Utilities

996 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 997

16

Cube Avenue

16

Cube Avenue

This chapter discusses Cube Avenue, an optional extension to Cube Voyager. Topics include: Using Cube Avenue Control statements Theory Examples

998 Cube Voyager Reference Guide

Cube Avenue Using Cube Avenue

16

Using Cube Avenue

This section provides information useful when using Cube Avenue: Cube Avenue introduction Phases

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: Operational traffic models Planning models

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.

Cube Voyager Reference Guide 999

16

Cube Avenue Using Cube Avenue

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.

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

1000 Cube Voyager Reference Guide

Cube Avenue Using Cube Avenue

16

Phases
This section describes the typical phases in Cube Avenue: SETUP phase LINKREAD phase ILOOP phase ADJUST phase CONVERGE phase

SETUP phase
This phase behaves identically in Cube Avenue and standard Cube Voyager Highway assignments.

LINKREAD 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

Cube Voyager Reference Guide 1001

16

Cube Avenue Using Cube Avenue

C T0 T1 STORAGE

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

1002 Cube Voyager Reference Guide

Cube Avenue Using Cube Avenue

16

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

Cube Voyager Reference Guide 1003

16

Cube Avenue Using Cube Avenue

Essentially, this value is the maximum frequency with which a vehicle can be discharged from or admitted to a link. Thus, a zerocapacity link can delay packets forever.
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*Speed/Distance. If all else fails, a default of zero will be applied.
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.
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).

1004 Cube Voyager Reference Guide

Cube Avenue Using Cube Avenue

16

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 packets 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 links storage slightly.

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 networks 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 networks 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 discarded; they just have their volumes modified according to the factors generated by the COMBINE methodology in force. Thus for COMBINE=AVE, the volumes in the packets generated during the current iteration will be given by {expression value}/{iteration number} and the new

Cube Voyager Reference Guide 1005

16

Cube Avenue Using Cube Avenue

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 iterations 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 packets departure from that packets 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 As 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 Bs 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.

1006 Cube Voyager Reference Guide

Cube Avenue Using Cube Avenue

16

CONVERGE phase
The CONVERGE phase is only executed once per iteration. It executes exactly the same as it would in a static highway assignment.

Cube Voyager Reference Guide 1007

16

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.

DYNAMIC
Changes the value of the capacity variable by time segment. Only use this command during the LINKREAD phase.
Keyword C |NV99| Description 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 links 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

1008 Cube Voyager Reference Guide

Cube Avenue Control statements

16

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 60minute 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.

DYNAMICLOAD
DYNAMICLOAD is the dynamic analog of the static PATHLOAD

statement. DEMANDISHOURLY = t/f INCLUDEJ = list EXCLUDEJ = list VOL[n] = list PATH = time/cost/list EXCLUDEGRP = list PACKETSIZE = value PENI = list

Cube Voyager Reference Guide 1009

16

Cube Avenue Control statements

PENIFACTOR = value MW[n] = TRACE(real, expr, list) NOACCESS=real This 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 1012 for a description on running combined DYNAMICLOAD and static PATHLOAD in the same run. Most of the clauses have the same syntax and meaning as the corresponding clauses of the PATHLOAD statement, so only the differences are noted in this document. 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. Several clauses of the DYNAMICLOAD statement require timesegmented 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. The DYNAMICLOAD PATH= clause may take, as its value, TIME, COST, or a list of input link attributes (that is, LI. Variables or LW.Variables; 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. The predicted disutility for a vehicle of

1010 Cube Voyager Reference Guide

Cube Avenue Control statements

16

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. The DYNAMICLOAD DEMANDISHOURLY = clause 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. The DYNAMICLOAD VOL[n] = clause is similar to the PATHLOAD VOL[n] = clause. 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. The DYNAMICLOAD PACKETSIZE = clause specifies the target number of vehicles per packet. The DYNAMICLOAD MW clause specifies skims. The value must take the form:
TRACE(time, expression, penalty)

Cube Voyager Reference Guide 1011

16

Cube Avenue Control statements

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.

Combined use of DYNAMICLOAD and static PATHLOAD

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.
Case 1: Static assignment

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.

1012 Cube Voyager Reference Guide

Cube Avenue Control statements

16

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.

Case 2: Dynamic assignment

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

Cube Voyager Reference Guide 1013

16

Cube Avenue Control statements

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.

FILEO
Highway program output files are not supported under FILEO if running a dynamic assignment process under AVENUE. SUBAREAMATO (FORMAT DEC NAME) ESTMICPO (VAR SCREENLINE) ESTMDATO NAME 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

1014 Cube Voyager Reference Guide

Cube Avenue Control statements

16

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.
FILEO keywords
Keyword PACKETLOG Subkeyword |F| Description 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 numbersminutes since the start of the model period.

Cube Voyager Reference Guide 1015

16

Cube Avenue Control statements

FILEO keywords (continued)

Keyword PACKETLOG Subkeyword DEPARTTIME |RPV| Description 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 numbersminutes since the start of the model period. List of destination nodes. Packet log only list packets ending at the listed destinations. By default, log includes packets to all destinations. Either BIN or TXT. By default, the PACKETLOG is a text file, which you can display in Cube graphics or postprocess 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. 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.

PACKETLOG

DESTINATION

|IV|

PACKETLOG

FORMAT

|S|

PACKETLOG

MUSTMEETALL

|?|

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

PACKETLOG

SELECTGROUP

|IV|

PACKETLOG

SELECTLINK

|IPV|

1016 Cube Voyager Reference Guide

Cube Avenue Control statements

16

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

TIMESt_1 and TIME_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.
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 Voyager Reference Guide 1017

16

Cube Avenue Control statements

VfSt_1, VfSMP_1, VSt_1 and VSMP_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).
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.
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.

1018 Cube Voyager Reference Guide

Cube Avenue Control statements

16

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.

PARAMETERS
Set general parameters MODELPERIOD SEGMENTS VEHPERDIST COMBINE CAPLINKENTRY PKTPTHSIZ MAXPTHPERSEG 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.
PARAMETERS keywords
Keyword CAPLINKENTRY |?| Description <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 222 for valid subkeywords and descriptions. Combine type EQU is not valid for Avenue. Since the default value of COMBINE is EQU, COMBINE must always be specified explicitly for AVENUE. For most uses of AVENUE, AVE is a good choice of combine value.

Cube Voyager Reference Guide 1019

16

Cube Avenue Control statements

PARAMETERS keywords (continued)

Keyword PACKETS |KS| Description Only applicable for COMBINE=AVE, selects between packet splitting and packet allocation modes. Defaults to PA. PAPacket 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. PSPacket 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 packets 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.

1020 Cube Voyager Reference Guide

Cube Avenue Control statements

16

PARAMETERS keywords (continued)

Keyword ITERLOADINC |KI| Description Defaults to zero. Only applicable for COMBINE=AVE where PACKETS=PA is selected. 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 timesegment packets onto a partially converged network allows a better initial network estimate for later time-segments and hence faster convergence. 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.

Cube Voyager Reference Guide 1021

16

Cube Avenue Control statements

PARAMETERS keywords (continued)

Keyword MAXPTHPERSEG |KI| Description Upper bound on the number of path builds executed for a given time segment, iteration, and origin. Defaults to 5. If the number of distinct packet departure times is less than this value, Cube Avenue builds paths for each packeteach packets node list is based on accurately built paths. Otherwise, Cube Avenue executes this many path builds, distributed evenly through the time segment. Each packets node list is based on the nearest path build, in terms of departure time. Though this value can affect the packets 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. 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.

PKTPTHSIZ

|KI|

1022 Cube Voyager Reference Guide

Cube Avenue Control statements

16

PARAMETERS keywords (continued)

Keyword SEGMENTS |R*| Description 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 warmup 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. 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

VEHPERDIST

|KR|

PATHLOAD
PATHLOAD is the static assignment path builder from the Highway program. See PATHLOAD on page 230 for a description of this command statement and its associated keywords and usage.

Cube Voyager Reference Guide 1023

16

Cube Avenue Control statements

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 1012 if implementing both command statements in the same run.
PATHLOAD keywords not supported if using static PATHLOAD statements in a dynamic assignment process with DYNAMICLOAD

in effect. ESTMO (ALLJ) PATHO (ALLJ INCLUDECOST NAME PATHOGROUP (FULLPATH))

1024 Cube Voyager Reference Guide

Cube Avenue Theory

16

Theory
This section discusses the theory behind Cube Avenue: Cube Avenue algorithm Cube Avenue calculations Functions and built-ins

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 timevarying 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 segments delays and on the estimated time of arrival of the packet at each point on its route.

Cube Voyager Reference Guide 1025

16

Cube Avenue Theory

On the second and subsequent iterations, the routes from previous iterations are not discarded. Instead the packet volumes travel along each route in proportion to the lambda values for the appropriate iteration. 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 networks 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.

1026 Cube Voyager Reference Guide

Cube Avenue Theory

16

Cube Avenue calculations

This section describes Cube Avenue calculations: Volumes Times Speeds

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:

Cube Voyager Reference Guide 1027

16

Cube Avenue Theory

First the packet is examined to determine which of the twenty possible volume fields are present. The values of V1, V2, , V20 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 userdefined 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.

Times
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

1028 Cube Voyager Reference Guide

Cube Avenue Theory

16

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.

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 Voyager Reference Guide 1029

16

Cube Avenue Theory

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, and Vol

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

TimeSegment
This is the time segment number. 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.

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.

1030 Cube Voyager Reference Guide

Cube Avenue Theory

16

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.

Time, Cost, and Vol

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 1017). 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 ELSE LW.TRUCK_COST2=DISTANCE+TIME LW.CAR_COST2=DISTANCE/2+TIME*1.5

Cube Voyager Reference Guide 1031

16

Cube Avenue Theory

The new variables can be used in a DYNAMICLOAD statement. For example:

DYNAMICLOAD PATH=LW.TRUCK_COST__TS__

1032 Cube Voyager Reference Guide

Cube Avenue Examples

16

Examples
This section contains examples of Cube Avenue scripts: Program Parameters LINKREAD Simplifying LINKREAD Centroids ILOOP ADJUST Enhancing ADJUST Packet logs Tuning parameters Reducing segment and volume lists

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 Voyager Reference Guide 1033

16

Cube Avenue Examples

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

1034 Cube Voyager Reference Guide

Cube Avenue Examples

16

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 Voyager Reference Guide 1035

16

Cube Avenue Examples

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

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.

1036 Cube Voyager Reference Guide

Cube Avenue Examples

16

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

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.

Cube Voyager Reference Guide 1037

16

Cube Avenue Examples

The input matrix for this example contains three tables, one for each half hour of the model period. The statement PACKETSIZE=10 groups the input vehicle trips into packets with a target size of ten vehicles. 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=10, VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3 ENDPHASE ENDRUN

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"

1038 Cube Voyager Reference Guide

Cube Avenue Examples

16

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=10, VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3 PHASE=ADJUST ENDPHASE ENDRUN

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"

Cube Voyager Reference Guide 1039

16

Cube Avenue Examples

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=10, 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

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

1040 Cube Voyager Reference Guide

Cube Avenue Examples

16

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=10, 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

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.

Cube Voyager Reference Guide 1041

16

Cube Avenue Examples

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 threeminute 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=10, 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

Reducing segment and volume lists

When using many time segments, segment and volume lists can become long and unwieldy.

1042 Cube Voyager Reference Guide

Cube Avenue Examples

16

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 segments 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=10, 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

Cube Voyager Reference Guide 1043

16

Cube Avenue Examples

ENDPHASE ENDRUN

1044 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 1045

Index Symbols

Index

Symbols %...% 24, 85 * command 88 ** command 88 :label GOTO keyword, Highway 213 GOTO keyword, Pilot 96 GOTO keyword, Public Transport 740 @...@ 24, 85 _BSEARCH, Matrix variable 457 _COMPARE, Network variable 345 _SKIPTOI, Highway variable 140 _ZONES, Network variable 345 A A COMP keyword, Generation 589 Highway array 141 Network variable 345 REPORT keyword, Generation 594 SETPA keyword, Distribution 578 SETPA keyword, Fratar 130 A2P

BALANCE keyword, Generation 588 AAD convergence testing calculation 172 Highway variable 142 PARAMETERS keyword, Highway 220 using in BALANCE variable 173 AADAVE function for BALANCE 175 Highway function 144 AADCHANGE function for BALANCE 174 Highway function 143 AADCHANGEAVE function for BALANCE 175 Highway function 144 AADCHANGEMAX function for BALANCE 175 Highway function 144 AADCHANGEMIN function for BALANCE 175 Highway function 144 AADCUTOFF Highway variable 142 using in BALANCE variable 173 AADMAX function for BALANCE 175 Highway function 144 AADMIN function for BALANCE 175 Highway function 144 ABORT Cube Cluster impact 983 Distribution control statement 452 Fratar control statement 452 Generation control statement 452 Highway control statement 180 Matrix control statement 452 Network control statement 348 Public Transport control statement 654 ABS 35 absolute logit model 422 AC REPORT keyword, Generation 594 ACCESS LINE NODES subkeyword, Public Transport 749 LINE NODES subkeyword, TRNBUILD 919 access legs generating 869 multiple, eliminating 814 report 775

1046 Cube Voyager Reference Guide

Index A

restricting to modes 670 ACCESS_C LINE NODES subkeyword, Public Transport 749 LINE NODES subkeyword, TRNBUILD 919 ACCESSLEGS REREPORT keyword, Public Transport 775 ACCESSLINK GENERATE keyword, Public Transport 732 ACCESSMODES SELECT keyword, TRNBUILD 939 ACCUMULATE FILEO STOP2STOPO subkeyword, Public Transport 725 ACOMP REPORT keyword, Fratar 128 REPORT keywords, Distribution 577 ACTION NT keyword, Public Transport 760 ACTUALGREEN JUNCTION keyword, overview 276 JUNCTION keyword, signals 293 ADDTOGROUP SETGROUP keyword, Highway 253 ADJUST phase Cube Avenue 1006 Highway program 164 stack for, Highway 260 ADJUSTLINK CROWDMODEL keyword, Public Transport 664 ADJUSTWAIT CROWDMODEL keyword, Public Transport 664 AFTERITER FILEO PACKETLOG subkeyword, Cube Avenue 1015 afterpgm NEWPAGE keyword, Pilot 100 aftersys NEWPAGE keyword, Pilot 100 AGF SETPA keyword, Fratar 130 algorithm all-or-nothing path building 763 Cube Avenue 1025 public transport transfers 763 ALIGN PLOTTER FOOTER subkeyword, Network 380 PLOTTER HEADER subkeyword, Network 381 ALL REPORT keyword, Network 390 ALLJ PATHLOAD ESTMO subkeyword, Highway 232

PATHLOAD PATHO subkeyword, Highway 239 ALLSTOPS LINE keyword, Public Transport 746 LINE keyword, TRNBUILD 917 all-way-stop-controlled intersections 313 ALPHA FACTORS keyword, Public Transport 667 ALTERNATIVES CHOICE keyword, cost-based model 462 CHOICE keyword, utility-based model 465 XCHOICE keyword, cost-based model 469 XCHOICE keyword, utility-based model 472 ALTNAME PARAMETERS keyword, TPP2UB 960 ANSWER PROMPT keyword, Pilot 105 AONMAXFERS FACTORS keyword, Public Transport 667 AONMETHOD PARAMETERS keyword, Public Transport 763 APPEND FILEO NETO keyword, Highway 205 FILEO PRINTO keyword, Highway 206 FILEO PRINTO subkeyword, Matrix 525 FILEO PRINTO subkeyword, Network 368 PRINT FILE subkeyword, general 67 APPLY CROWDMODEL keyword, Public Transport 664 APPROACH JUNCTION keyword, common description 280 JUNCTION keyword, overview 276 APPROACH1 JUNCTION keyword, common description 282 JUNCTION keyword, overview 276 APPROACHWIDTH JUNCTION keyword, empirical roundabout 316 JUNCTION keyword, overview 276 ARCCOS 38 ARCSIN 38 ARCTAN 38 ARRAY Cube Cluster impact 983 Distribution control statement 452 Fratar control statement 452 Generation control statement 452 Highway control statement 180 Matrix control statement 452 Network control statement 348 SORT keyword, general 76 arrays

Cube Voyager Reference Guide 1047

Index B

creating and populating 511 Cube Cluster and 983 field names in, Matrix 491 finding keys in, Matrix 457 Highway 141 initializing, Highway 156 internal, reporting in Highway 252 link work, denoting 767 link, Cube Avenue 1031 Matrix, DBI 491 Matrix, RECI 504 populating with LOOKUP, example 64 production and attraction 120 production and attraction, generating 585 production and attraction, number of 592 production and attraction, referencing 570 route-enumeration components 674 setting to same value, Highway 252 sorting 76 sorting, Highway 254 sorting, Network 391 specifying with keywords 28 string valued 508 user, declaring in Highway 180 user, declaring in Network 348 user-defined, sorting in Matrix 553 zonal data, reporting in Matrix 551 ARRAYSUM COMP function, Matrix 481 Matrix built-in function 410 ARRIVALTIME FILEO PACKETLOG subkeyword, Cube Avenue 1015 ASSIGN TRIPS MATRIX subkeyword, TRNBUILD 946 ATTACHMENTS SENDMAIL keyword, Pilot 112 AUTOARRAY FILEI DBI subkeyword, Matrix 491 AUTOCOEF PARAMETERS keyword, TPP2UB 960 AVE FILEI ZDATI subkeyword, Highway 198 FILEI ZDATI subkeyword, Matrix 508 MERGE keyword, Network 372 AVERAGELANEWIDTH JUNCTION keyword, geometric signals 296 JUNCTION keyword, overview 276 AVEX0 FILEI ZDATI subkeyword, Highway 198 FILEI ZDATI subkeyword, Matrix 508

MERGE keyword, Network 372 B B Highway array 141 Network variable 345 print format code, numeric items 70 print format code, string items 72 BALANCE Generation control statement 588 Highway variable 142 BALANCE variable functions for 174 setting, convergence script 172 variables for 173 BANDWIDTH PLOTTER keyword, Network 379 BASE1 PRINTROW keyword, general 73 BASECOSTS CHOICE keyword, cost-based model 462 BASECOSTSMW XCHOICE keyword, cost-based model 469 BASEDATA FILEI TURNPENI subkeyword, Public Transport 705 BASEDEMAND CHOICE keyword, cost-based model 462 CHOICE keyword, utility-based model 465 BASEDEMANDMW XCHOICE keyword, cost-based model 469 XCHOICE keyword, utility-based model 472 BASEGDBNETWORK FILEO LINEO subkeyword, Public Transport 709 FILEO NTLEGO subkeyword, Public Transport 717 BASEMW FREQUENCY keyword, Matrix 532 BASEUTILS CHOICE keyword, utility-based model 465 BASEUTILSMW XCHOICE keyword, utility-based model 473 beforepgm NEWPAGE keyword, Pilot 100 beforesys NEWPAGE keyword, Pilot 100 BEG FILEI LINKI VAR subkeyword, Network 363 BESTJRNY skim function, Public Transport 622 skim function, summary 625 BESTPATHONLY

1048 Cube Voyager Reference Guide

Index C

FACTORS keyword, Public Transport 668 BIN FILEO TURNVOLO file format 208 boarding penalty example 882 mode specific 669 perceived, skim function 621 reducing during transfers 800 boarding point first, default wait curve 784 first, wait curve used 782 transit leg definition 809 wait time at 799 boardings example 882 line output, including in 709 link output, including in 713 number, skim function 623 passenger loading report, including in 773 BOARDPEN FACTOR keyword, TRNBUILD 905 BOARDS TRIPS MATRIX ASSIGN subkeyword, TRNBUILD 946 bottleneck modeling as generalized cost 799 modeling with crowding 861 queuing location, Cube Avenue 1019 trips affected, skim function 624 BRDINGS skim function, Public Transport 623 skim function, summary 625 BRDPEN FACTORS keyword, Public Transport 669 skim function, Public Transport 621 skim function, summary 625 BREAK Distribution control statement 456 Fratar control statement 456 Generation control statement 456 Highway control statement 181 Matrix control statement 456 Network control statement 349 Pilot control statement 88 Public Transport control statement 655 BSEARCH Matrix control statement 457 BUILDPATHS PARAMETERS keyword, TRNBUILD 928 BUSBLOCKAGE JUNCTION keyword, geometric signals 297

JUNCTION keyword, overview 276 BYCLASS FILEO LINKO subkeyword, Public Transport 711 C C DYNAMIC keyword, Cube Avenue 1008 Highway variable 140 Highway variable, example value 147 print format code, numeric items 70 print format code, string items 72 set value, outside LINKREAD phase 221 setting, example in Cube Avenue 1035 value computed, Highway LINKREAD phase 158 variable, Cube Avenue 1003 CALL Distribution control statement 458 Fratar control statement 458 Generation control statement 458 Matrix control statement 458 CANSHARELEFT JUNCTION keyword, overview 276 JUNCTION keyword, saturation-flow priority junctions 336 JUNCTION keyword, signals 291 CANSHARERIGHT JUNCTION keyword, overview 276 JUNCTION keyword, saturation-flow priority junction 337 JUNCTION keyword, signals 292 CAPACITY REPORT keyword, Highway 250 REPORT keyword, Network 390 REPORT keyword, TRNBUILD 935 SPDCAP keyword, Highway 254 SPDCAP keyword, Network 392 CAPACITYFOR COMP function, Network 351 Highway function 142 Network function 346 CAPACITYINTERCEPT JUNCTION keyword, empirical roundabout 317 JUNCTION keyword, overview 277 CAPACITYSLOPE JUNCTION keyword, empirical roundabout 318 JUNCTION keyword, overview 277 CAPFAC applying in Cube Avenue 1003 PARAMETERS keyword, Highway 221 scaling input capacity with, Cube Avenue 1036

Cube Voyager Reference Guide 1049

Index C

CAPLINKENTRY PARAMETERS keyword, Cube Avenue 1019 CC SENDMAIL keyword, Pilot 112 CENTRALBUSINESSDISTRICT JUNCTION keyword, geometric signals 298 JUNCTION keyword, overview 277 CENTRALRESERVATIONWIDTH JUNCTION keyword, geometric priority junctions 331 JUNCTION keyword, overview 277 CFORM FILEO PAO subkeyword, Generation 590 FILEO RECO subkeyword, Matrix 525 PRINT keyword, general 66 REPORT MARGINREC subkeyword, Matrix 549 CHANGEATLASTSTOP PARAMETERS keyword, Public Transport 763 CHECKRETURNCODE WAIT4FILES keyword, Cube Cluster 989 CHOICE Matrix control statement 461 Matrix control statement, replacing 420 XCHOICE, differences with 475 choice modeling absolute logit model 422 alternative alighting, Public Transport 835 destination choice model 443 general considerations 448 incremental logit model 430 introduction 420 mode-and-destination-choice model 445 route decisions, Public Transport 830 transfer points, Public Transport 836 transit choices, Public Transport 833 walk choice, Public Transport 830 CHOICECUT FACTORS keyword, Public Transport 669 CIRCULAR LINE keyword, Public Transport 746 CLEAR LINE GLOBAL subkeyword, TRNBUILD 918 LINK keyword, TRNBUILD 923 PNR keyword, TRNBUILD 932 SUPPORT keyword, TRNBUILD 942 CLEARERROR Pilot control statement 89 CLEARFILEO DOWNLOAD keyword, Pilot 94 Cluster.exe 992 CmpNumRetNum 35

CNT FILEI ZDATI subkeyword, Highway 199 FILEI ZDATI subkeyword, Matrix 508 MERGE keyword, Network 372 CODE CLEARERROR keyword, Pilot 89 example 103 COEFF CHOICE DESTSPLIT subkeyword 463 CHOICE SPLIT subkeyword 464 XCHOICE DESTSPLIT subkeyword 470 XCHOICE SPLIT subkeyword 471 COL CROSSTAB keyword, Network 355 COLOR LINE keyword, TRNBUILD 917 COMBINE FILEI LINKI subkeyword, Network 361 FILEO MATO keyword, Highway 203 PARAMETERS keyword, Cube Avenue 1019 PARAMETERS keyword, Highway 222 TRNBUILD control statement 903 command prompt, starting Cube Voyager from 17 comments 25 COMMPATH DISTRIBUTEINTRASTEP keyword, Cube Cluster 991 DISTRIBUTEMULTISTEP keyword, Cube Cluster 988 COMP control statement, general 47 CROSSTAB keyword, Network 355 Distribution control statement 477 Fratar control statement 477 Generation control statement 588 Highway control statement 182 Matrix control statement 477 Network control statement 350 Pilot control statement 90 Public Transport control statement 657 COMPARE Network control statement 351 COMPCOST skim function, Public Transport 623 skim function, summary 625 composite cost skim function 623 confidence levels matrix estimation 863 output links 722 CONFLICTINGBIKE JUNCTION keyword, geometric signals 297 CONFVAR

1050 Cube Voyager Reference Guide

Index C

FILEO ESTMICPO subkeyword, Highway 202 FILEO SCREENLINEO subkeyword, Public Transport 722 connectors access, restricting modes 670 egress, restricting modes 670 CONSOLE control statement, general 48 CONSOLIDATE PARAMETERS keyword, Highway 225 PATHLOAD keyword, Highway 232 CONTINUE Distribution control statement 486 Fratar control statement 486 Generation control statement 486 Highway control statement 189 Matrix control statement 486 Network control statement 354 Pilot control statement 92 Public Transport control statement 660 CONTROL SETPA keyword, Fratar 130 control blocks 26 control fields 27 control statements comments 25 control blocks 26 Cube Cluster, summary 974 DATAPREP phase, Public Transport 646 Distribution program 573 fields 27 Generation program 587 Highway program 179 Highway program, types 138 keywords 28 LINKREAD phase, Public Transport 645 MATI phase, Public Transport 648 MATO phase, Public Transport 651 Matrix program, list of 451 Matrix program, types 411 Network program 347 NODEREAD phase, Public Transport 644 null blocks 25 overview 45 Public Transport program 653 SELECTIJ phase, Public Transport 650 stacks, Highway program 259 subkeywords 29 tokens 24 CONVERGE phase

Cube Avenue 1007 Highway program 171 not specifying, Highway program 168 stack for, Highway program 260 convergence crowding model, Public Transport 862 Cube Avenue 1028 default testing, Highway 168 Distribution model 566 Fratar distribution 119 Fratar distribution, iteration control 123 intersection modeling and 274 multiple purposes and 568 output matrices and 127 output matrices, writing 575 phase supporting, Highway 171 phases and, Highway 137 target totals, adjusting for 130 COPY Pilot control statement 92 COS 38 COST FUNCTION keyword, Highway 212 GENERATE keyword, Public Transport 733 Highway array 141 NT keyword, Public Transport 760 value set, Highway LINKREAD phase 159 COSTDEC FILEO PATHO keyword, Highway 205 COSTS CHOICE keyword, cost-based model 462 COSTSMW XCHOICE keyword, cost-based model 470 COUNTVAR FILEO ESTMICPO subkeyword, Highway 202 CRITICALGAP JUNCTION keyword, gap-acceptance roundabout 327 JUNCTION keyword, overview 277 JUNCTION keyword, two-way stop 307 CROSSING2ENTRY JUNCTION keyword, empirical roundabout 319 JUNCTION keyword, geometric priority junctions 332 CROSSING2EXIT JUNCTION keyword, empirical roundabout 320 JUNCTION keyword, geometric priority junctions 332 CROSSINGLENGTH GEOMETRIC priority junctions 332 JUNCTION keyword, empirical roundabout 320 CROSSTAB

Cube Voyager Reference Guide 1051

Index D

Network control statement 354 crowd modeling boarding probability, updating 861 control statement defining 664 in-vehicle-time effects 800 link travel times, updating 861 link-travel-time adjustment 857 outputs, setting 711 process, Public Transport 639 report supplements 794 theory 857 wait-time adjustment 860 wait-time effects 799 CROWDCRVDEF Public Transport control statement 662 CROWDCURVE LINE keyword, Public Transport 746 VEHICLETYPE keyword, Public Transport 781 crowding actual wait time, skim function 618 perceived wait time. skim function 618 seat occupancy value 748 theory 857 CROWDMODEL Public Transport control statement 664 CRUSHCAP LINE keyword, Public Transport 747 VEHICLETYPE keyword, Public Transport 781 CSV PATHLOAD TRACE subkeyword, Highway 243 PRINT keyword, general 66 CTLFILE RUN keyword, Pilot 108 Cube Analyst intercept file, producing for 202 MATO file, producing for 522 Public Transport demand matrices 863 Public Transport intercept file, producing for 708 Public Transport screenline file, producing for 722 screenline data file, producing for 202 Cube Avenue algorithm 1025 calculations 1027 control statements 1008 examples 1033 introduction 999 limitation of Cube Cluster 982 phases 1001 script variables 1030 Cube Base

starting Cube Voyager with 12 Cube Cluster control statements 987 control statements, summary 974 executable for local machine 992 file permissions 975 introduction 969 utility functions 994 working with 974 Cube Voyager Distribution program 562 Fratar distribution process 118 general syntax 22 Generation program 584 Highway program 134 intersection modeling 272 Matrix program 406 Network program 342 Pilot program 80 Public Transport program 600 utilities 956 CURVE CROWDCRVDEF keyword, Public Transport 663 WAITCRVDEF keyword, Public Transport 783 CWDCOSTP skim function, Public Transport 620 skim function, summary 625 CWDWAITA skim function, Public Transport 618 skim function, summary 625 CWDWAITP skim function, Public Transport 618 skim function, summary 625 CYCLETIME JUNCTION keyword, overview 277 JUNCTION keyword, signals 292 D D print format code, numeric items 70 print format code, string items 72 DATAPREP Public Transport phase 646 DBF FILEO PAO subkeyword, Generation 590 FILEO TURNVOLO file format 208 DBF files dumping link and node records to 401 fields, writing to with Matrix RECO 526 Generation program output 590

1052 Cube Voyager Reference Guide

Index D

linking to LOOKUPI file 56 matrix data input files, Matrix 498 Matrix program input, DBI 490 Matrix program input, RECI 503 stop-to-stop analysis, Public Transport 724 turning volume file, Highway 208 writing to, Matrix 554 DBI FILEI keyword, Matrix 490 files, processing 510 functions to read records 510 DCOSTS CHOICE keyword, cost-based model 462 DCOSTSMW XCHOICE keyword, cost-based model 470 DEADLINKS REPORT keyword, Network 390 DEC FILEO MATO keyword, Highway 204 FILEO MATO subkeyword, Matrix 519 FILEO MATO subkeyword, Public Transport 715 FILEO NETO keyword 205 FILEO NETO subkeyword, Public Transport 717 FILEO SUBAREAMATO keyword, Highway 206 FILEO TURNVOLO keyword, Highway 207 PATHLOAD PATH subkeyword, Highway 239 REPORT LINES subkeyword, Public Transport 772 REPORT LINEVOLS subkeyword, Public Transport 773 REPORT ZDAT keyword, Highway 252 REPORT ZDAT subkeyword, Matrix 551 DEFAULT FILEI ZDATI subkeyword, Highway 199 FILEI ZDATI subkeyword, Matrix 508 DEFAULTCONF FILEO ESTMICPO subkeyword, Highway 203 DEFCONF FILEO SCREENLINEO subkeyword, Public Transport 722 DELACCESSMODE FACTORS keyword, Public Transport 670 DELAY LINE NODES subkeyword, Public Transport 749 LINE NODES subkeyword, TRNBUILD 919 DELAY_C LINE NODES subkeyword 919 LINE NODES subkeyword, Public Transport 750 DELAYEQUATION JUNCTION keyword, geometric signals 298 DELDISTRIBFILES WAIT4FILES keyword, Cube Cluster 989

DELEGRESSMODE FACTORS keyword, Public Transport 670 DELETE Network control statement 358 DELETESTR 38 DELIMITER FILEI DBI subkeyword, Matrix 494 FILEI RECI subkeyword, Matrix 504 FILEO LINKO subkeyword, Network 365 FILEO MATO subkeyword, Matrix 521 FILEO TURNVOLO keyword, Highway 207 DELMODE FACTORS keyword, Public Transport 670 DEMAND CHOICE keyword, cost-based model 463 CHOICE keyword, utility-based model 465 XCHOICE keyword, cost-based model 470 XCHOICE keyword, utility-based model 473 demand matrices Public Transport, estimating 863 pure mode-choice model, cost-based 470 pure mode-choice, utility-based 473 specifying name, cost-based model 469 specifying name, utility-based model 472 DEMANDMW XCHOICE keyword, cost-based model 470 XCHOICE keyword, utility-based model 473 DEPARTTIME FILEO PACKETLOG subkeyword, Cube Avenue 1016 design concepts 3 DESTINATION FILEO PACKETLOG subkeyword, Cube Avenue 1016 destination zones, Matrix 535 destination-choice model assigning zones, cost-based (CHOICE) 463 assigning zones, cost-based (XCHOICE) 470 assigning zones, utility-based (CHOICE) 465 assigning zones, utility-based (XCHOICE) 473 combined with mode-choice 445 demand, specifying 475 description 443 example code 559 using gravity model 565 DESTSPLIT CHOICE keyword, cost-based model 463 CHOICE keyword, utility-based model 465 XCHOICE keyword, cost-based model 470 XCHOICE keyword, utility-based model 473 DETAILS FILEI LINKI subkeyword, Network 361

Cube Voyager Reference Guide 1053

Index E

DEVICE PLOTTER keyword, Network 379 DIRECTION GENERATE keyword, Public Transport 733 ZONEACCESS GENERATE subkeyword, TRNBUILD 949 DIRECTLINK GENERATE keyword, Public Transport 733 DIST Highway array 141 LINK keyword, TRNBUILD 923 NT keyword, Public Transport 760 skim function, Public Transport 623 skim function, summary 625 SUPPLINK keyword, TRNBUILD 940 SUPPORT keyword, TRNBUILD 942 value, Highway LINKREAD phase 159 ZONEACCESS LINK subkeyword, TRNBUILD 950 DISTANCE Highway variable 140 script variable, Cube Avenue 1002 setting, example in Cube Avenue 1035 value computed, Highway LINKREAD phase 158 DISTRIBUTE Cube Cluster control statement 987 DISTRIBUTEINTRASTEP Cube Cluster control statement 990 DISTRIBUTEMULTISTEP Cube Cluster control statement 987 Distribution program control statements 573 convergence 566 example 580, 580, 581 examples 580 friction factors 571 introduction 563 overview 563 DLL CALL keyword, Matrix 458 DOWNLOAD Pilot control statement 93 DRAWA PLOT keyword, Network 378 DRAWLINK PLOT keyword, Network 378 DUPLICATES REPORT keyword, Network 390 DUPSTR character function 38 DUTILS CHOICE keyword, utility-based model 466 DUTILSMW

XCHOICE keyword, utility-based model 473 DWELL LINE NODES subkeyword, Public Transport 750 DWELL_C LINE NODES subkeyword, Public Transport 750 DYNAMIC Cube Avenue control statement 1008 DYNAMICLOAD Cube Avenue control statement 1009 example, ADJUST phase 1038 using in ILOOP 1037 using with PATHLOAD 1012 using work variables in 1032 E E print format code, numeric items 70 egress legs definition 809 eliminating in multirouting models 815 example report, TRACEI 791 generating 869 report 775 EGRESSLEGS REREPORT keyword, Public Transport 775 ELSE control statement, general 52 Highway control statement 214 Network control statement 369 Pilot control statement 97 ELSEIF control statement, general 52 Highway control statement 214 Network control statement 369 Pilot control statement 97 EMME/2 data bank file MATI, specifying as input with 498 MATO, writing with 518 output matrix names 524 RECO, writing with 525 retrieving matrix data, example 516 retrieving zonal vector matrix, example 517 scalar and vector matrix names 527 specifying matrix written 524 variable names written 526 writing with FILEO MATO, example 528 writing with FILEO RECO, example 529 ZDATI, specifiying with 507 empirical roundabout difference with gap-acceptance roundabout 288

1054 Cube Voyager Reference Guide

Index E

example 325 keywords 316 model overview 315 ENABLE JUNCTION keyword, common description 282 ENDCOPY Pilot control statement 92 ENDDISTRIBUTEMULTISTEP Cube Cluster control statement 988 ENDIF control statement, general 52 Highway control statement 214 Network control statement 369 Pilot control statement 97 Public Transport control statement 740 ENDJLOOP Highway control statement 215 Matrix control statement 535 Public Transport control statement 741 ENDLINKLOOP Highway control statement 217 Public Transport control statement 756 ENDLOOP Highway control statement 218 Network control statement 369 Pilot control statement 98 Public Transport control statement 757 ENDPHASE PROCESS keyword, Generation 593 PROCESS keyword, Highway 249 ENDPROCESS Generation control statement 592 Highway control statement 248 Network control statement 388 ENDRUN Pilot control statement 107 ENTRYANGLE JUNCTION keyword, empirical roundabout 320 JUNCTION keyword, overview 277 ENTRYGATE FILEI TOLLMATI subkeyword, Highway 195 ENTRYRADIUS JUNCTION keyword, empirical roundabout 322 JUNCTION keyword, overview 277 ENTRYWIDTH JUNCTION keyword, empirical roundabout 323 JUNCTION keyword, overview 277 enumerated routes destination zones 719 destination zones reported, output file 720

file containing 719 maximum transfers in 675 origin zones 719 origin zones reported, output file 720 report 787 user-class specific 770 using FACTORS statements for 611 EQUATION 167 EQUITURNCOSTFAC PARAMETERS keyword, Highway 226 errors clearing 89 factor file, maximum number 695 fatal, TRNBUILD 893 listing in run print file, Matrix 505 maximum in data records, Network 375 maximum in RECI records, Matrix 505 responding to 100 transit line 766 ESTIMATEDDELAY JUNCTION keyword, common description 283 JUNCTION keyword, overview 277 ESTMDATO FILEO keyword, Highway 202 impact on Cube Avenue 1014 impact on Cube Cluster 982 ESTMICPO FILEO keyword, Highway 202 impact on Cube Avenue 1014 impact on Cube Cluster 982 ESTMO impact on Cube Avenue 1024 PATHLOAD keyword, Highway 232 setting to true 209 evaluated routes destination zones printed, input file 702 destination zones printed, output file 721 destination zones reported, input file 701 destination zones reported, output file 720 origin zones printed, input file 702 origin zones printed, output file 721 origin zones reported, input file 701 origin zones reported, output file 720 quality issues 871 report 788 EXCESSDEMAND skim function, Public Transport 624 skim function, summary 625 EXCESSPROP skim function, Public Transport 624

Cube Voyager Reference Guide 1055

Index F

skim function, summary 625 EXCLUDE CHOICE DESTSPLIT subkeyword, cost-based model 463 CHOICE DESTSPLIT subkeyword, utility-based model 465 COMP MW subkeyword, Highway 183 COMP MW subkeyword, Matrix 478 COMP MW subkeyword, Public Transport 658 FILEI LINKI subkeyword, Network 361 FILEO LINKO subkeyword, Network 365 FILEO NETO keyword, Highway 205 FILEO NETO subkeyword, Network 367 JLOOP keyword, Highway 216 SETPA keyword, Distribution 578 SETPA keyword, Fratar 130 XCHOICE DESTSPLIT subkeyword, cost-based model 470 XCHOICE DESTSPLIT subkeyword, utility-based model 473 EXCLUDEGROUP PATHLOAD keyword, Highway 232 EXCLUDEJ PATHLOAD keyword, Highway 232 EXCLUDELINK GENERATE keyword, Public Transport 733 EXCLUDERECI FILEO RECO subkeyword, Matrix 525 EXCLUSIVELANES JUNCTION keyword, overview 277 JUNCTION keyword, priority junction 337 JUNCTION keyword, signals 293 EXIT Cube Cluster impact 983 Distribution control statement 487 Fratar control statement 487 Generation control statement 487 Highway control statement 189 Matrix control statement 487 Network control statement 358 Pilot control statement 94 Public Transport control statement 665 EXITGATE FILEI TOLLMATI subkeyword, Highway 196 EXITLANES JUNCTION keyword, geometric signals 298 EXITONLY JUNCTION keyword, common description 283 JUNCTION keyword, overview 277 EXITS

TRIPS MATRIX ASSIGN subkeyword, TRNBUILD 946 EXP 35 EXPDIST numeric function 35 EXPINV numeric function 36 exponential distribution function 35 expressions COMP statements 47 COMP, Matrix program 480 computing values with FUNCTION 211 LOOKUP statement 55 numeric, overview 33 selection, overview 40 variables in 43 EXTENDREPORT PARAMETERS keyword, Public Transport 763 EXTENDRUNTIMES PARAMETERS keyword, Public Transport 764 EXTRACTCOST GENERATE keyword, Public Transport 734 EXTRAXFERS1 FACTORS keyword, Public Transport 670 EXTRAXFERS2 FACTORS keyword, Public Transport 671 F FACTOR TRNBUILD control statement 905 factor file input, names of 695 maximum errors 695 validating fare data in 695 FACTORI FILEI keyword, Public Transport 695 FACTORS network development processing 609 Public Transport control statement 666 route enumeration, controlling with 611 FAIL LOOKUP keyword, general 56 FARE FARELINKS keyword, TRNBUILD 910 PARAMETERS keyword, Public Transport 764 TRNBUILD control statement 907 fare matrices input file containing 696 name, defining 689 report 792 fare model assigning 671

1056 Cube Voyager Reference Guide

Index F

defining 687 input file for, specifying 696 purpose 801 FAREA skim function, Public Transport 621 skim function, summary 625 FAREFROMFS FARESYSTEM keyword, Public Transport 689 FAREI FILEI keyword, Public Transport 696 FARELINKS TRNBUILD control statement 909 FAREMATI FILEI keyword, Public Transport 696 FILEI keyword, TRNBUILD 911 FAREMATRIX FARESYSTEM keyword, Public Transport 689 FAREMSG PARAMETERS keyword, Public Transport 765 FAREP skim function, Public Transport 621 skim function, summary 625 fares boarding and transfer costs 850 determining trip cost from 850 examples 855 generalized cost component 798 input file, control statements 696 input file, matrices 696 input file, missing data 765 line, specifying for 747 matrix reports 792 methods for defining structure 848 modeling in Public Transport 845857 models for, overview 801 multiple systems in network 850 overview 845 route evaluation, including cost in 764 skim functions for 621 system describing 687694 validating in factor file 695 zones for 852 FARESYSTEM FACTORS keyword, Public Transport 671 LINE keyword, Public Transport 747 Public Transport control statement 687 FARETABLE FARESYSTEM keyword, Public Transport 690 FAREZONES FARESYSTEM keyword, Public Transport 692

FFACTORS GRAVITY keyword, Distribution 574 FIELDS FILEI DBI subkeyword, Matrix 495 FILEI MATI subkeyword, Matrix 500 FILEI RECI subkeyword, Matrix 505 FILEO MATO subkeyword, Matrix 522 FILEO RECO subkeyword, Matrix 526 FILE COPY keyword, Pilot 93 LOOKUP keyword, general 56 PLOTTER keyword, network 380 PRINT keyword, general 66 READ keyword, general 75 RENUMBER keyword, Matrix 545 REPORT MARGINREC subkeyword, Matrix 549 REPORT VDTSPD keyword, Highway 251 FILEI control statement, general 48 Distribution control statement 487 Fratar control statement 487 Generation control statement 487 Highway control statement 189 Matrix control statement 487 Network control statement 359 Pilot control statement 94 PROCESS PHASE subkeyword, Network 388 Public Transport control statement 694 REPORT keyword, Network 390 SYNCHIMP control statement 961 TPP2UB control statement 959 TRNBUILD control statement 910 UB2TPP control statement 957 FILEO control statement, general 49 Cube Avenue control statement 1014 Distribution control statement 517 DOWNLOAD keyword, Pilot 94 example, Matrix 527 Fratar control statement 517 Generation control statement 589 Highway control statement 201 Matrix control statement 517 Network control statement 365 Pilot control statement 95 Public Transport control statement 708 REPORT keyword, Network 390 SYNCHIMP control statement 962 TPP2UB control statement 959 TRNBUILD control statement 912

Cube Voyager Reference Guide 1057

Index F

UB2TPP control statement 958 FILES keyword RENUMBER keyword, Matrix 546 WAIT4FILES keyword, Cube Cluster 990 FilesExist function 994 FILET Distribution control statement 530 Fratar control statement 530 Highway control statement 210 Matrix control statement 530 FILL PLOTTER BANDWIDTH subkeyword, Network 379 FILLMW Distribution control statement 531 Fratar control statement 531 Highway control statement 211 Matrix control statement 531 FIRST FILEI ZDATI subkeyword, Highway 199 FILEI ZDATI subkeyword, Matrix 508 MERGE keyword, Network 373 FirstReadyNode function 994 FIRSTZONE Cube Cluster impact 984 Matrix built-in variable 409 FIXED FILEO SUPPORTO subkeyword, TRNBUILD 916 FLARELENGTH JUNCTION keyword, empirical roundabout 324 JUNCTION keyword, overview 277 FLARESTORAGE JUNCTION keyword, two-way stop 307 FMCAPACITY LINE keyword, Public Transport 747 FMOFF LINE NODES subkeyword, Public Transport 750 FMON LINE NODES subkeyword, Public Transport 750 FMVOL LINE NODES subkeyword, Public Transport 750 NT keyword, Public Transport 760 FMVOLS FILEO LINKO subkeyword, Public Transport 711 FMVOLT NT keyword, Public Transport 761 FOLLOWUPTIME JUNCTION keyword, gap-acceptance roundabout 327 JUNCTION keyword, overview 277 JUNCTION keyword, two-way stop 307

FONT PLOTTER FOOTER subkeyword, Network 380 PLOTTER HEADER subkeyword, Network 381 PLOTTER LEGEND subkeyword, Network 382 PLOTTER POSTLINKVAR subkeyword, Network 384 PLOTTER POSTNODEVAR subkeyword, Network 385 FOOTER PLOTTER keyword, Network 380 FORM CROSSTAB COMP subkeyword, Network 355 CROSSTAB VAR subkeyword, Network 356 FILEO LINKO subkeyword, Network 365 FILEO PAO subkeyword, Generation 591 FILEO RECO subkeyword, Matrix 527 PRINT keyword, general 67 PRINTROW keyword, general 73 REPORT MARGINREC subkeyword, Matrix 549 FORMAT character function 38 FILEO LINEVOLO subkeyword, TRNBUILD 913 FILEO LINKO subkeyword, Network 366 FILEO LINKVOLO subkeyword, TRNBUILD 915 FILEO MATO keyword, Highway 204 FILEO MATO subkeyword, Matrix 522 FILEO MATO subkeyword, Public Transport 716 FILEO NETO subkeyword, Network 367 FILEO PACKETLOG subkeyword, Cube Avenue 1016 FILEO SUBAREAMATO keyword, Highway 206 FILEO TURNVOLO keyword, Highway 208 FOURLANEMAJOR JUNCTION keyword, overview 277 JUNCTION keyword, two-way stop 308 FRACTIONS PARAMETERS COMBINE keyword, Highway 225 Fratar distribution control statements 126 controlling target totals 121 convergence 123 examples 132 multiple purposes 124 overview 119 specifying target values 120 FREEFLOWCAP JUNCTION keyword, geometric priority junctions 332 JUNCTION keyword, overview 277 JUNCTION keyword, two-way stop 308 FREQBYMODE FACTORS keyword, Public Transport 672 FREQPERIOD PARAMETERS keyword, TRNBUILD 928

1058 Cube Voyager Reference Guide

Index G

FREQUENCY Distribution control statement 532 Fratar control statement 532 impact on Cube Cluster 983 LINE keyword, TRNBUILD 917 Matrix control statement 532 FREQUENCYR LINE keyword, TRNBUILD 917 friction factors curves in gravity model 564 distribution process, use in 571 example, typical process 62 expression, specifying 574 FROM FACTORS XFERCONST subkeyword, Public Transport 682 FACTORS XFERFACTOR subkeyword, Public Transport 683 FACTORS XFERPEN subkeyword, Public Transport 684 SENDMAIL keyword, Pilot 112 FROMNODE GENERATE keyword, Public Transport 734 FULL REPORT LINKVOL subkeyword, TRNBUILD 936 FULLPATH PATHLOAD PATHO subkeyword, Highway 239 FUNCTION Highway control statement 211 functions built-in, all programs 35 character, general 38 COMP expression 481 convergence, Highway program 143 Cube Avenue 1030 Highway program 141 lookup 40 matrix 185188 Matrix program, built-in 410 numeric, general 35 trig, general 37 utility, supporting Cube Cluster 994 G gamma distribution function 36 inverse function 36 GAMMADIST numeric function 36 GAMMAINV numeric function 36 GAP convergence testing calculation 171

Highway variable 142 PARAMETERS keyword, Highway 226 using in BALANCE variable 173 gap-acceptance roundabout difference with empirical roundabout 288 example 328, 328 keyword placement 286 keywords for 327 overview 315 GAPAVE function for BALANCE 174 Highway function 143 GAPCHANGE function for BALANCE 174 Highway function 143 GAPCHANGEAVE function for BALANCE 174 Highway function 144 GAPCHANGEMAX function for BALANCE 174 Highway function 144 GAPCHANGEMIN function for BALANCE 174 Highway function 143 GAPCUTOFF Highway variable 142 using in BALANCE variable 173 GAPMAX function for BALANCE 174 Highway function 143 GAPMIN function for BALANCE 174 Highway function 143 generalized cost boarding penalty component 800 calculation, route enumeration 801 converting from monetary fares 682 fare component 801 fares, including in 764 in-vehicle time component 799 logit choice models 423 route enumeration and evaluation, specifying 666 route evaluation, using for 826 theory, Public Transport 797 transfer penalty component 800 using to affect choices 448 wait-time component 799 walk-time component 798 GENERATE avoiding poor quality routing 869

Cube Voyager Reference Guide 1059

Index H

DATAPREP phase 646 example preparing public transport network 876 example, two user class 885 keywords to avoid excessive legs 872 network development 609 nontransit network, developing with 868 Public Transport control statement 730 writing to nontransit legs table 738 Generation program control statements 587 examples 595 introduction to 585 GEOMETRIC JUNCTION keyword, priority junction 330 geometric priority junctions example 335 keywords 331 GEOMETRYSOURCE Network variable 345 GLOBAL control statement, general 50 LINE keyword, TRNBUILD 918 LINK keyword, TRNBUILD 923 PNR keyword, TRNBUILD 932 SUPPORT keyword, TRNBUILD 942 GOTO Distribution control statement 533 Fratar control statement 533 Generation control statement 533 Highway control statement 213 Matrix control statement 533, 533 Pilot control statement 96 Public Transport control statement 739 GRADE JUNCTION keyword, geometric signals 299 JUNCTION keyword, overview 277 JUNCTION keyword, two-way stop 309 GRAVITY Distribution control statement 573 gravity model alternative to complete formulation 565 control statement for 573 description 563 example 580, 581 example, singly constrained 558 implementation guidelines 564 GROUPEDMODES FILEO STOP2STOPO subkeyword, Public Transport 725 GROUPS

FILEO STOP2STOPO subkeyword, Public Transport 726 H HDWAYPERIOD PARAMETERS keyword, Public Transport 765 HEADER PLOTTER keyword, Network 381 HEADERONLY PARAMETERS keyword, UB2TPP 958 headway computing wait time from 799 line in reverse direction, specifying 748 line, specifying 747 route enumeration, use for 802 selecting 765 wait curve, default 784 wait curve, rules for 784 wait curve, specifying in 783 HEADWAY. LINE keyword, Public Transport 747 HEADWAY_R LINE keyword, Public Transport 748 hierarchical logit model 436 highway assignment introduction 135 iteration volume combinations 168 iterations, maximum 226 multiple iteration 161 setting up scripts 146 using PATHLOAD statement 160 Highway program ADJUST phase 164 arrays 141 assignment, getting started 146 control statement overview 138 control statements 179 CONVERGE phase 171 convergence functions 143 convergence variables 142 Cube Cluster, invoking 990 examples 261269 functions 141 ILOOP phase 160 intersection modeling 272 introduction 135 linking to Public Transport program 865 LINKREAD phase 156 logic, overview 257 SETUP phase 155

1060 Cube Voyager Reference Guide

Index I

variables 140 zonal loop, select link 162 zonal loop, selected zone loading 163 zonal loop, subarea trip extraction 163 HOV facilities, assigning trips to 150 HWYTIME PHASE1 keyword, TRNBUILD 931 I I FILEI ROUTEI subkeyword, Public Transport 700 FILEO ROUTEO subkeyword, Public Transport 719 Highway variable 140 Matrix built-in variable 409 REPORT VDTSPD keyword, Highway 250 SELECT keyword, TRNBUILD 939 IBOARDFARE FARESYSTEM keyword, Public Transport 692 ID FILEO LINEVOLO subkeyword, TRNBUILD 913 FILEO LINKVOLO subkeyword, TRNBUILD 915 ID, general control statement 50 IDP commands that disable 982 description 976 using when summarizing zonal values 984 IF COMBINE keyword, TRNBUILD 904 control statement, general 52 Cube Cluster impact 983 Distribution control statement 534 Fratar control statement 534 Generation control statement 534 Highway control statement 214 Matrix control statement 534 Network control statement 369 Pilot control statement 97 Public Transport control statement 740 IJ SELECT keyword, TRNBUILD 939 ILOOP phase computing volumes, Cube Avenue 1027 controlling loop processing 217 Cube Avenue 1005 Cube Cluster impacts 983 Generation program 585 Highway program 160 jumping to zone 140 stack for, Highway 260 INCLUDE

CHOICE DESTSPLIT subkeyword, cost-based model 463 CHOICE DESTSPLIT subkeyword, utility-based model 465 COMP MW subkeyword, Highway 183 COMP MW subkeyword, Matrix 479 COMP MW subkeyword, Public Transport 659 FILEO LINKO subkeyword, Network 366 FILEO NETO keyword, Highway 205 FILEO NETO subkeyword, Network 367 JLOOP keyword, Highway 215 SETPA keyword, Fratar 130 SETPA keywords, Distribution 578 XCHOICE DESTSPLIT subkeyword, cost-based model 470 XCHOICE DESTSPLIT subkeyword, utility-based model 473 INCLUDE0 FILEO TURNVOLO keyword, Highway 209 INCLUDECOST PATHLOAD PATHO subkeyword, Highway 239 INCLUDEJ PATHLOAD keyword, Highway 232 INCLUDELINK GENERATE keyword, Public Transport 734 incremental logit model 430 initial wait time actual, skim function 618 perceived, skim function 619 INITIALQUEUE JUNCTION keyword, common description 284 JUNCTION keyword, overview 277 INLIST function example 414 numeric function 36 INPUT REPORT keyword, Network 390 input files See also FILEI phase-based processing, Network 393 Public Transport program, overview 864 specifying 48 INPUT phase Network program 394 variable associations 396 inputs loading process, Public Transport 627 network development, Public Transport 610 route enumeration, Public Transport 612 route evaluation, Public Transport 613

Cube Voyager Reference Guide 1061

Index J

select-link process, Public Transport 628 skimming, Public Transport 615 INSCRIBEDDIAMETER JUNCTION keyword, empirical roundabout 325 JUNCTION keyword, overview 277 INSERTSTR 38 installation 11 INT 36 intercept data modes considered 765 screenline file that produces 702 intercept file configuring link use 864 matrix estimation, requirement for 863 output file name, Highway 202 output file name, Public Transport 708 INTERCEPTO FILEO keyword, Public Transit 708 INTERPOLATE FARESYSTEM FARETABLE subkeyword, Public Transport 691 LOOKUP keyword, general 56 intersection modeling control statements 276 description 274 introduction 273 invoking at nodes 193 keywords 280 limitations 274 nodes invoked at, specifying 194 purpose 273 results file, specifying 203 intersections control statements 276 keywords, common 280 priority junctions 329 roundabouts 314 signal controlled 290 stop, all-way 313 two-way stop-controlled 305 two-way yield-controlled 329 INTRA Matrix keyword 412 intrastep distributed processing. See IDP INTRAZONAL Matrix keyword 412 intrazonal cells 412 in-vehicle time best-path modeling calculation 802 crowding adjustment 857

increasing to reflect crowding 662 theory 799 ITERATION Highway variable 140 Matrix built-in variable 409 iteration control 566 ITERATIONS CROWDMODEL keyword, Public Transport 664 REPORT keyword, Distribution 577 iterations ADJUST phase 165 assignment and capacity restraint 147 combining MATO matrices from 226 CONVERGE phase 171178 converge phase functions, Highway 143 convergence variables 142 convergence, Distribution 566 Cube Avenue parameters 1034 highway assignment, maximum 226 maximum, Distribution 576 maximum, Fratar 127 number, crowd-modeling runs 664 processing, Cube Avenue 1025 processing, Fratar distribution 123 reported, Distribution 577 testing for convergence 169, 171 writing output matrices, Distribution 575 writing packet log, Cube Avenue 1015 writing path output file 206 ITERS FILEO PATHO keyword, Highway 206 IWAITA skim function, Public Transport 618 skim function, summary 625 IWAITCURVE FACTORS keyword, Public Transport 673 IWAITFAC FACTOR keyword, TRNBUILD 905 IWAITMAX FACTOR keyword, TRNBUILD 905 IWAITMIN FACTOR keyword, TRNBUILD 905 IWAITP skim function, Public Transport 619 skim function, summary 625 J J FILEI ROUTEI subkeyword, Public Transport 701 FILEO ROUTEO subkeyword, Public Transport 719

1062 Cube Voyager Reference Guide

Index K

Highway variable 140 JLOOP keyword, Highway 215 JLOOP keyword, Matrix 537 JLOOP keyword, Public Transport 742 Matrix built-in variable 409 PRINTROW keyword, general 74 REPORT VDTSPD keyword, Highway 250 SELECT keyword, TRNBUILD 939 JLOOP Distribution control statement 535 Fratar control statement 535 Generation control statement 535 Highway control statement 215 Matrix control statement 535 Public Transport control statement 741 JOINTODBI FILEI DBI subkeyword, Matrix 495 JOINTOFIELDS FILEI DBI subkeyword, Matrix 496 JUNCDATAO FILEO keyword, SYNCHIMP utility 962 JUNCTION junction file control statement 276 junction file control statements 276 input, specifying 194 output, specifying 203 JUNCTIONI FILEI keyword, Highway 194 JUNCTIONO FILEO keyword, Highway 203 K keywords See also individual keyword names description 28 documentation descriptions 31 intersection modeling 280 subkeywords 29 values 31 KFACTORS GRAVITY keyword, Distribution 574 L L FARELINKS keyword, TRNBUILD 910 print format code, numeric items 71 print format code, string items 72 LAMBDA, Highway variable 140 LAMBDAA

FACTORS keyword, Public Transport 673 LAMBDASEARCH PARAMETERS COMBINE keyword, Highway 225 LAMBDAW FACTORS keyword, Public Transit 674 LANEADJUST JUNCTION keyword, overview 277 JUNCTION keyword, signals 293 LANES LINK keyword, TRNBUILD 923 SPDCAP keyword, Highway 254 SPDCAP keyword, Network 392 LANESI FILEI keyword, SYNCHIMP utility 961 LAST FILEI ZDATI subkeyword, Highway 199 FILEI ZDATI subkeyword, Matrix 508 MERGE keyword, Network 373 LASTITERATION, Highway variable 140 LASTZONE Cube Cluster impact 984 Matrix built-in variable 409 LAYOUTI FILEI keyword, SYNCHIMP utility 961 LEFTDRIVE FILEO NETO subkeyword, Network 368 PARAMETERS keyword, Network 375 LEFTSTR 39 LEG NT keyword, Public Transport 760 LEGEND PLOTTER keyword, Network 381 LEN FILEI LINKI VAR subkeyword, Network 363 Level-of-Service extraction 893 LI.CAPCLASS input field, Cube Avenue 1002 LI.LANES input field, Cube Avenue 1003 LI.name Highway array 141 LI.SPDCLASS input field, Cube Avenue 1002 LINE PLOTTER LEGEND subkeyword, Network 382 Public Transport control statement 745 REREPORT keyword, Public Transport 775 TRNBUILD control statement 917 Line combining 893 LINEI

Cube Voyager Reference Guide 1063

Index L

FILEI keyword, Public Transport 697 LINELINELEG REREPORT keyword, Public Transport 776 LINEO FILEO keyword, Public Transport 708 LINES FILEO LINKO subkeyword, Public Transport 711 REPORT keyword, Public Transport 772 REPORT keyword, TRNBUILD 935 report produced, example 793 REREPORT keyword, Public Transport 776 lines. See transit lines LINESORT REPORT LINEVOL subkeyword, TRNBUILD 936 LINESTRING REPORT keyword, TRNBUILD 935 LINEVOL REPORT keyword, TRNBUILD 935 LINEVOLO FILEO keyword, TRNBUILD 913 LINEVOLS REPORT keyword, Public Transport 773 LINEZONLEG1 REREPORT keyword, Public Transport 776 LINEZONLEG2 REREPORT keyword, Public Transport 777 LINK TRNBUILD control statement 922 ZONEACCESS keyword, TRNBUILD 950 LINKCLASS Highway variable 140 setting, example in Cube Avenue 1035 value computed, Highway LINKREAD phase 158 variable, Cube Avenue 1002 LINKDUMP PHASE1 keyword, TRNBUILD 931 LINKI FILEI keyword, Network 360 LINKID#MW PATHLOAD LINKIDARRAY subkeyword, Highway 233 LINKIDARRAY PATHLOAD keyword, Highway 233 LINKIDCNTMW PATHLOAD LINKIDARRAY subkeyword, Highway 233 LINKIDLASTUSE PATHLOAD LINKIDARRAY subkeyword, Highway 233 LINKIDMW PATHLOAD LINKIDARRAY subkeyword, Highway 233 LINKLOOP Highway control statement 217

Public Transport control statement 756 LINKMERGE phase controlling plotting 377 Network program 395 plotting 398 PROCESS block rules 389 records merging data 372 variable referencing 396 LINKNO, Highway variable 140 LINKNUM, Highway function 142 LINKO FILEO keyword, Network 365 FILEO keyword, Public Transport 710 FILEO keyword, SYNCHIMP utility 962 FILEO keyword, TRNBUILD 914 LINKOFFSET PLOTTER keyword, Network 382 LINKPOST PLOT keyword, Network 378 LINKREAD phase Cube Avenue 1001 Highway program 156 Public Transport program 645 stack for, Highway 260 links arrays supporting 141 centroid connectors 1036 computing walk and transit times 878 confidence level value 722 Cube Avenue packets, specifying 1016 demand using, selecting 630 drawing, Network 377 drawn, characteristics of 379 dumping to DBF files, example 401 duplicate, eliminating 371 group codes for, setting 253 listing in print file, example 401 loops for processing, Public Transport 756 merging records from multiple files, example 401 nontransit leg, maximum 733 one-way, nontransit legs 735 output file, specifying in Public Transport 710 path, loading 230 restricted use by mode 723 speed on, non-input network 755 transit line time. base 767 travel demand on, identifying 628 travel time computation, Public Transport 755 variables supporting 140 walk 798

1064 Cube Voyager Reference Guide

Index L

links file defining output 710 lines data, including in 711 summing output by user class 711 LINKVOL REPORT keyword, TRNBUILD 936 LINKVOLO FILEO keyword, TRNBUILD 914 LIST COMPARE keyword, Network 352 FILEI FACTORI subkeyword, Public Transport 695 FILEI FAREI subkeyword, Public Transport 696 FILEI LINEI subkeyword, Public Transport 697 FILEI SYSTEMI subkeyword, Public Transport 703 FILEI TURNPENI subkeyword, Highway 197 FILEI TURNPENI subkeyword, Public Transport 705 FILEO PAO subkeyword, Generation 591 FILEO STOP2STOPO subkeyword, Public Transport 726 GENERATE keyword, details about 738 GENERATE keyword, Public Transport 734 LOOKUP keyword, general 56 PRINT keyword, general 68 REPORT MARGINREC subkeyword, Matrix 550 ZONEACCESS GENERATE subkeyword 949 LIST_ERRS PARAMETERS keyword, Network 375 LISTERRS FILEI RECI subkeyword, Matrix 505 LISTINPUT PARAMETERS keyword, TRNBUILD 928 LISTLINK SUPPORT keyword, TRNBUILD 942 LN 36 LOADDISTFAC LINE keyword, Public Transport 748 VEHICLETYPE keyword, Public Transport 781 loading analyses mode transfers 639 operator transfers 639 overview 638 stop-to-stop movements 639 loading process overview, Public Transport 626 theory, Public Transport 842 trip matrix into public transport network 883 LOG control statement, standard 53 impact on Cube Cluster 983 numeric function, general syntax 36

logit choice model 423 logit models absolute 422 applying to parts of matrices 449 choices 448 destination choice 443 hierarchical 436 incremental 430 incremental, practical considerations 450 mode and destination choice 445 scale parameters 450 lognormal distribution function 36 inverse function 36, 36 LOGNORMDIST numeric function 36 LOGNORMINV numeric function 36 LONGNAME FARESYSTEM keyword, Public Transport 692 LINE keyword, Public Transport 748 MODE keyword, Public Transport 759 OPERATOR keyword, Public Transport 762 VEHICLETYPE keyword, Public Transport 781 WAITCRVDEF keyword, Public Transport 782 LONGNAMECROSDCRVDEF keyword, Public Transport 663 LOOKUP control statement, general 55 LOOKUP NAME subkeyword, general 57 LOOKUPI FILEI keyword, Highway 194 FILEI keyword, Matrix 497 FILEI keyword, Network 364 FILEI keyword, Pilot 95 LOOKUP keyword, general 57 LOOP Distribution control statement 538 Fratar control statement 538 Generation control statement 538 Highway control statement 218 Matrix control statement 538 Network control statement 369 Pilot control statement 98 Public Transport control statement 757 loops general variable, Matrix 538 general variable, Public Transport 757 general, Highway 218 input zones, Cube Avenue 1037 jumping to end 354 link records, Highway 217

Cube Voyager Reference Guide 1065

Index M

link records, Public Transport 756 matrices, Matrix 535 matrix column cells, Public Transport 741 matrix columns, Highway 215 terminating, Public Transport 665 using to control run order 81 LOS GRAVITY keyword, Distribution 574 LOSRANGE GRAVITY keyword, Distribution 574 LOTMODE PNR keyword, TRNBUILD 932 LOWCNT COMP function, Matrix 481 Highway function 142 Highway variable 140 Matrix built-in variable 409 matrix function, Highway 186 LOWEST COMP function, Matrix 482 Highway function 142 Matrix built-in function 410 matrix function, Highway 186 LTRIM, character function 39 LW.name, Highway array 141 M MAJORROADWIDTH JUNCTION keyword, geometric priority junctions 333 JUNCTION keyword, overview 278 MAPSCALE PARAMETERS keyword, Public Transport 765 PLOTTER keyword, Network 382 MAPWINDOW PLOTTER keyword, Network 383 MARGINREC impact on Cube Cluster 983 REPORT keyword, Matrix 549 MARGINS impact on Cube Cluster 983 PLOTTER keyword, Network 383 REPORT keyword, Matrix 550 MATI FILEI keyword, Highway 194 FILEI keyword, Matrix 498 FILEI keyword, Public Transport 698 FILEI keyword, TPP2UB 959 FILEI keyword, TRNBUILD 911 FILEI keyword, UB2TPP 957 Public Transport phase 647

MATO FILEO keyword, Highway 203 FILEO keyword, Matrix 518 FILEO keyword, Public Transport 714 FILEO keyword, TPP2UB 959 FILEO keyword, TRNBUILD 915 FILEO keyword, UB2TPP 958 Public Transport phase 651 MATOADJUST PARAMETERS keyword, Highway 226 MATOEVERY PARAMETERS keyword, Distribution 575 PARAMETERS keyword, Fratar 127 MATRICES TRNBUILD control statement 924 matrices applying part to logit model 449 functions, Highway 185188 intrazonal cells, working with 412 value limitations 521 variables, Highway 184 MATRIX TRIPS keyword, TRNBUILD 945 Matrix program control statements, list of 451 control statements, types 411 Cube Cluster, invoking 990 examples 555 functions, built-in 410 functions, COMP statement 481 introduction 407 variables, built-in 409 MATSTAT REPORT keyword, Matrix 550 MATVAL COMP function, matrix 482 Matrix built-in function 410 MATVALCACHE PARAMETERS keyword, Matrix 540 MAX FILEI ZDATI subkeyword, Highway 199 FILEI ZDATI subkeyword, Matrix 508 MERGE keyword, Network 373 numeric function 36 MAX_IP_ERRS PARAMETERS keyword, Network 375 MAXCOMPD FACTORS keyword, Public Transport 674 MAXCOST GENERATE keyword, Public Transport 735

1066 Cube Voyager Reference Guide

Index M

MAXDIFF COMBINE keyword, TRNBUILD 904 MAXDIST SEGLIMITS keyword, TRNBUILD 938 XFERGEN keyword, TRNBUILD 947 ZONEACESS GENERATE subkeyword, TRNBUILD 949 MAXERRS FILEI FACTORI subkeyword, Public Transport 695 FILEI LINEI subkeyword, Public Transport 697 FILEI RECI subkeyword, Matrix 505 MAXFERS FACTORS keyword, Public Transport 675 MAXFIELDS FILEO MATO subkeyword, Matrix 523 MAXITERS convergence testing calculation 172 PARAMETERS keyword, Distribution 576 PARAMETERS keyword, Fratar 127 PARAMETERS keyword, Highway 226 MAXLINKDELAY FILEI TURNPENI subkeyword, Public Transport 706 MAXLINKS ZONEACESS GENERATE subkeyword, TRNBUILD 949 MAXMSG PATHLOAD SUBAREAMAT subkeyword, Highway 242 MAXMW PARAMETERS keyword, Highway 226 PARAMETERS keyword, Matrix 540 PARAMETERS keyword, Public Transport 765 MAXNODE PHASE1 keyword, TRNBUILD 931 MAXNTLEGS GENERATE keyword, Public Transport 735 MAXPATHTIME PARAMETERS keyword, TRNBUILD 928 MAXPCTDIFF MULTIACCESS keyword, TRNBUILD 927 MAXPERLINE PRINTROW keyword, general 74 MAXPTHPERSEG PARAMETERS keyword, Cube Avenue 1022 MAXPURPS PARAMETERS keyword, Fratar 128 MAXRECS FILEI DBI subkeyword, Matrix 496 FILEI RECI subkeyword, Matrix 505 MAXRMSE PARAMETERS keyword, Distribution 576 PARAMETERS keyword, Fratar 128

MAXRUNTIME PARAMETERS keyword, TRNBUILD 928 MAXSCAN FILEI RECI subkeyword, Matrix 506 MAXSTOPS ZONEACESS GENERATE subkeyword, TRNBUILD 950 MAXSTRING PARAMETERS keyword, Highway 226 PARAMETERS keyword, Matrix 540 PARAMETERS keyword, Pilot 104 MAXTIME PNR keyword, TRNBUILD 932 SEGLIMITS keyword, TRNBUILD 938 MAXTIMEDIFF MULTIACCESS keyword, TRNBUILD 927 MAXWAITTIME FACTOR keyword, TRNBUILD 906 MDP 978 MERGE Network control statement 371 REPORT keyword, Network 390 MESSAGE CONSOLE subkeyword 48 SENDMAIL keyword, Pilot 112 message 770 765 messages displaying 48 excessive travel time 763 zonal timing, Highway 229 zonal timing, Matrix 541 zonal timing, Public Transport 769 zone pairs without valid routes 766 MEUSESNT FILEO SCREENLINEO subkeyword, Public Transport 723 PARAMETERS keyword, Public Transport 765 MIN FILEI LINKI VAR subkeyword, Network 363 FILEI ZDATI subkeyword, Highway 199 FILEI ZDATI subkeyword, Matrix 508 MERGE keyword, Network 373 numeric function 36 MINCOST GENERATE keyword, Public Transport 735 MINGROUPSIZE DISTRIBUTEINTRASTEP keyword, Cube Cluster 991 minimum system requirements 7 MINIMUMCAPACITY JUNCTION keyword, common description 284

Cube Voyager Reference Guide 1067

Index M

JUNCTION keyword, overview 278 minimum-cost routes finding, theory on 821 generation process 686 maximum transfers permitted 667 MINUTP 953 MISSINGLINK FILEI TURNPENI subkeyword, Highway 197 FILEI TURNPENI subkeyword, Public Transport 706 MISSINGZI RENUMBER keyword, Matrix 546 MISSINGZO RENUMBER keyword, Matrix 546 MO FILEO MATO keyword, Highway 204 FILEO MATO subkeyword, Matrix 524 FILEO MATO subkeyword, Public Transport 715 MODE FACTORS FARESYSTEM subkeyword, Public Transport 672 LINE keyword, Public Transport 748 LINE keyword, TRNBUILD 918 NT keyword, Public Transport 761 PNR keyword, TRNBUILD 933 Public Transport control statement 758 SUPPLINK keyword, TRNBUILD 940 XFERGEN keyword, TRNBUILD 947 ZONEACCESS LINK subkeyword, TRNBUILD 950 ZONEACESS GENERATE subkeyword, TRNBUILD 950 mode-and-destination-choice model 445 MODEFAC FACTOR keyword, TRNBUILD 905 MODEFARE FARE keyword, TRNBUILD 908 model period crowd model, Public Transport 664 Cube Avenue 1022 duration, junction file 194 Highway program 227 modeling approaches, Public Transport 803 MODELPERIOD PARAMETERS keyword, Cube Avenue 1022 PARAMETERS keyword, Highway 227 MODES FARELINKS keyword, TRNBUILD 910 FILEO NETO subkeyword, TRNBUILD 915 FILEO SUPPORTO subkeyword, TRNBUILD 916 LINK keyword, TRNBUILD 923 REPORT LINEVOL subkeyword, TRNBUILD 936 REPORT LINKVOL subkeyword, TRNBUILD 936

REPORT NODEVOL subkeyword, TRNBUILD 937 SEGLIMITS keyword, TRNBUILD 938 SUPPORT keyword, TRNBUILD 942 modes access connectors, prohibiting 670 banning transfers between 684 choosing between 421 choosing with destination 445 data file 703 defining 758 deleting for user class 670 demand using, selecting 633 egress connectors, prohibiting 670 fare model 672 intercept data and 765 limiting selected routes to 807 link use restricted 723 logit choice model 422 must-use, enumerating routes with 825 required in transit route 676 required, extra cost allowed 676 stop-to-stop movement data collected 727 transfer penalty 800 transfers between, report 795 turn-penalty free 706 MODES subkeyword FILEO STOP2STOPO, Public Transport 727 MOVEMENT JUNCTION keyword, common description 285 JUNCTION keyword, overview 278 MSG ABORT keyword, Highway 180 ABORT keyword, Matrix 452 ABORT keyword, Network 348 ABORT keyword, Public Transport 654 MULTIACCESS TRNBUILD control statement 927 MULTISTEP DISTRIBUTE keyword, Cube Cluster 987 multistep distributed processing. See MDP MUMEXTRACOST FACTORS keyword, Public Transport 676 MUSTMEETALL FILEO PACKETLOG subkeyword, Cube Avenue 1016 must-use mode enumerating routes with, theory 825 evaluating routes with 827 specifying 676 MUSTUSEMODE FACTORS keyword, Public Transport 676

1068 Cube Voyager Reference Guide

Index N

MW COMP keyword, Highway 182 COMP keyword, Matrix 478 COMP keyword, Public Transport 658 FILLMW keyword, Matrix 531 function description 34 Highway array 141 Matrices keyword, TRNBUILD 926 Matrix built-in variable 409 PATHLOAD keyword, Highway 234 PRINTROW keyword, general 74 SETPA keyword, Fratar 131 N N FILEI JUNCTIONI subkeyword, Highway 194 Network variable 345 REREPORT keyword, Public Transport 777 substituting for NODES, TRNBUILD 919 SUPPLINK keyword, TRNBUILD 940 TURNS keyword, Highway 256 NAME CROWDCRVDEF keyword, Public Transport 663 FARESYSTEM keyword, Public Transport 692 FILEI DBI subkeyword, Matrix 497 FILEI RECI subkeyword, Matrix 506 FILEI ZDATI subkeyword, Highway 199 FILEO ESTMDATO keyword, Highway 202 FILEO MATO keyword, Highway 204 FILEO MATO subkeyword, Matrix 524 FILEO MATO subkeyword, Public Transport 715 FILEO RECO subkeyword, Matrix 527 FILEO SUBAREAMATO keyword, Highway 206 LINE keyword, Public Transport 746 LINE keyword, TRNBUILD 918 LOOKUP keyword, general 57 MATRICES keyword, 925 MODE keyword, Public Transport 759 OPERATOR keyword, Public Transport 762 PATHLOAD PATHO subkeyword, Highway 240 VEHICLETYPE keyword, Public Transport 781 WAITCRVDEF keyword, Public Transport 782 NAMES FILEO PAO subkeyword, Generation 591 FILEO TURNVOLO keyword, Highway 209 naming conventions string variables, Network 351 variables, general 43 NEAREST LOOKUP keyword, general 57

NET FILEO LINEO subkeyword, Public Transport 709 FILEO NTLEGO subkeyword, Public Transport 718 NETI FILEI keyword, Highway 194 FILEI keyword, Public Transport 699 FILEI keyword, TRNBUILD 911 NETIENTRY FILEI TOLLMATI subkeyword, Highway 196 NETIEXIT FILEI TOLLMATI subkeyword, Highway 196 NETITOLLROAD FILEI TOLLMATI subkeyword, Highway 196 NETO FILEO keyword, Highway 205 FILEO keyword, Network 366 FILEO keyword, Public Transport 716 FILEO keyword, TRNBUILD 915 NETWORK Example 1 401 NETWORK Introduction 343 Network program control statements 347 examples 401 INPUT phase 394 LINKMERGE phase 395 NODEMERGE phase 394 output variables 397 phases 393 plotting 398 referencing variables 395 SUMMARY phase 395 theory 393 networks building from inline data records 402 comparing records in 351 deleting data records 358 development example, Public Transport 876 development process overview, Public Transport 609 highest node number 376 highway, input file 194 highway, introduction 135 Highway, output file name 205 highway, processing 343 highway, revising speed and capacity 254 input data files 359 output file 365 plotting 398, 398 public transport, developing 646 public transport, generating nontransit legs 730 public transport, input file 699

Cube Voyager Reference Guide 1069

Index N

Public Transport, output file 716 public transport, preparing 603 simplification of, Public Transport 808 speeds, Public Transport 866 times, Public Transport 866 zones, number in 376 NEWPAGE Pilot control statement 100 NHB BALANCE keyword, Distribution 588 NNTIME LINE NODES subkeyword, Public Transport 751 NOACCESS PATHLOAD MW subkeyword, Highway 236 NODE JUNCTION keyword, common description 286 JUNCTION keyword, overview 278 PNR keyword, TRNBUILD 933 XY keyword, TRNBUILD 948 NODEI FILEI keyword, Network 364 NODEMERGE phase description 394 variable referencing 396 NODEO FILEO keyword, Network 368 FILEO keyword, SYNCHIMP utility 962 FILEO keyword, TRNBUILD 915 NODEPOST PLOT keyword, Network 378 NODEREAD Public Transport phase 644 NODES FACTOR MAXWAITTIME subkeyword, TRNBUILD 906 LINE keyword, TRNBUILD 919 LINK keyword, TRNBUILD 923 SUPPLINK keyword, TRNBUILD 940 SUPPORT keyword, TRNBUILD 943 nodes alighting, portion allocated to 673 approaches at 280 Cube Cluster processing, starting 993 destination, Cube Avenue 1016 destination, nontransit legs 737 drawing, Network 377 fare zones 852 highest number in network 376 intersection modeling invoked at 194 maximum in RAM, Cube Avenue 1022 nontransit leg, intermediate 761

nontransit legs, start and finish 760 origin, Cube Avenue 1016 origin, nontransit legs 734 output, including in Public Transport 718 Public Transport report, including in 777 stop, including in report 774 stop, transit line flag 746 stop-to-stop movements collected for 727 transit line 749753 travel demand on, identifying 628 travel demand on, selecting 632 turning volumes accumulated 256 wait curve associated 673 wait curve associated, transfer points 685 wait-time weighting factor for 682 NODES. FACTORS IWAITCURVE subkeyword, Public Transport 673 FACTORS WAITFACTOR subkeyword, Public Transport 682 FACTORS XWAITCURVE subkeyword, Public Transport 685 FILEO STOP2STOPO subkeyword, Public Transport 727 Highway variable 140 LINE keyword, Public Transport 749 PARAMETERS keyword, Network 376 NODEVOL REPORT keyword, TRNBUILD 936 nontransit legs direction 733 excessive, avoiding 872 generating 730 generating, theory 869 link cost 733 links included 734 listing 734 maximum cost per mode 735 maximum network links 733 maximum per mode 735 minimum cost per mode 735 mode assigned 735 network links excluded 733 nodes from 734 nontransit legs file naming 717 source 718 nontransit-only routes 872 normal distribution function 37

1070 Cube Voyager Reference Guide

Index O

inverse function 37 NORMDIST, numeric function 37 NORMINV, numeric function 37 NOROUTEERRS PARAMETERS keyword, Public Transport 766 NOROUTEMSGS PARAMETERS keyword, Public Transport 766 NOTMODES FILEI TURNPENI subkeyword, Public Transport 706 NOX FACTOR keyword, TRNBUILD 905 NT Public Transport control statement 759 NTBYLINK FILEO LINKO subkeyword, Public Transport 711 NTLEGI FILEI keyword, Public Transport 700 NTLEGMODE GENERATE keyword, Public Transport 735 NTLEGO FILEO keyword, Public Transport 717 NTLEGS FILEO LINKO subkeyword, Public Transport 712 null blocks 25 NUMBER CROWDCRVDEF keyword, Public Transport 663 FARESYSTEM keyword, Public Transport 692 MODE keyword, Public Transport 759 OPERATOR keyword, Public Transport 762 VEHICLETYPE keyword, Public Transport 781 WAITCRVDEF keyword, Public Transport 782 NUMBEROFLANES JUNCTION keyword, all-way stop 313 JUNCTION keyword, overview 278 numbers print format 67 print format, working matrix 73 size limits 521 NUMLINKS, Highway variable 140 NumReadyNodes function 994 NUMRECS SORT keyword, general 76 O OCOMPCOST CHOICE keyword, cost-based model 463 OCOMPUTIL CHOICE keyword, utility-based model 466 ODEMAND CHOICE keyword, cost-based model 463

CHOICE keyword, utility-based model 466 ODEMANDMW XCHOICE keyword, cost-based model 470 XCHOICE keyword, utility-based model 473 OFF LINE NODES subkeyword, Public Transport 752 OLINKS TRIPS MATRIX ASSIGN subkeyword, TRNBUILD 946 OMITFARES FILEI FACTORI subkeyword, Public Transport 695 ON LINE NODES subkeyword, Public Transport 752 ONELINKREC FILEO LINKO subkeyword, Public Transport 712 ONEWAY FARELINKS keyword, TRNBUILD 910 FILEO SUPPORTO subkeyword, TRNBUILD 916 GENERATE keyword, Public Transport 735 LINE keyword, Public Transport 753 LINE keyword, TRNBUILD 920 LINK keywords, TRNBUILD 923 NT keyword, Public Transport 761 PNR keyword, TRNBUILD 933 SUPPLINK keyword, TRNBUILD 940 SUPPORT keyword, TRNBUILD 943 ZONEACCESS LINK subkeyword, TRNBUILD 950 ONLINE CONSOLE subkeyword 48 PARAMETERS keyword, TRNBUILD 929 ONOFFS FILEO LINKO subkeyword, Public Transport 713 ONRUNERRORGOTO Pilot control statement 100 OPERATOR FACTORS FARESYSTEM subkeyword, Public Transit 672 LINE keyword, Public Transport 753 Public Transport control statement 762 operators defining 762 demand using, selecting 633 fare model 672 transit line 753 ORIGIN FILEO PACKETLOG subkeyword, Cube Avenue 1016 output files See also FILEO naming 49 Pilot program 81

Cube Voyager Reference Guide 1071

Index P

Public Transport program 864 waiting for subprocess, Cube Cluster 988 outputs loading process, Public Transport 627 network development, Public Transport 610 route enumeration, Public Transport 612 route evaluation, Public Transport 613 skimming, Public Transport 615 P P COMP keyword, Generation 589 REPORT keyword, Generation 594 SETPA keyword, Distribution 579 SETPA keyword, Fratar 131 P2A BALANCE keyword, Generation 588 PACKETLOG FILEO keyword, Cube Avenue 1015 PAGEHEIGHT GLOBAL keyword, general 50 PAGEWIDTH GLOBAL keyword, general 50 PAO FILEO keyword, Generation 590 PARAMETERS Cube Avenue control statement 1019 Distribution control statement 575 Fratar control statement 126 Generation control statement 592 Highway control statement 220 Matrix control statement 539 Network control statement 374 Pilot control statement 103 Public Transport control statement 763 RUN keyword, Pilot 108 SYNCHIMP control statement 962 TPP2UB control statement 960 TRNBUILD control statement 928 UB2TPP control statement 958 PARKINGMANEUVERS JUNCTION keyword, geometric signals 299 JUNCTION keyword, overview 278 passenger loadings analyses 638 assigning 626 example report 884 report example 794 passengers assigning to trips 626

denied boarding 799 distance, example report 793 distance, generating report 772 flow-metered volume 760 hours, example report 793 hours, generating report of 772 statistics, skimming 841 utility, improving with new service 828 volume, specifying for nontransit legs 761 PASSWORD SENDMAIL keyword, Pilot 112 PATH FILET keyword, Highway 211 FILET keyword, Matrix 530 PATHLOAD keyword, Highway 239 Path building 893 path file creating from Saturn output 964 PATHLOAD Cube Avenue control statement 1023 Highway control statement 230 using with DYNAMICLOAD 1012 PATHO FILEO keyword, Highway 205 impact on Cube Avenue 1024 impact on Cube Cluster 983 PATHLOAD keyword, Highway 239 PATHOGROUP PATHLOAD PATHO subkeyword, Highway 240 PATHSTYLE PARAMETERS keyword, TRNBUILD 929 PATHTRACE Highway function 142 PATTERN FILEI MATI subkeyword, Matrix 501 FILEO MATO subkeyword, Matrix 525 PC REPORT keyword, Generation 594 PCOMP REPORT keyword, Fratar 128 PDIFF convergence testing calculation 172 Highway variable 142 PARAMETERS keyword, Highway 227 using in BALANCE variable 173 PDIFFAVE function for BALANCE 176 Highway function 145 PDIFFCHANGE function for BALANCE 174

1072 Cube Voyager Reference Guide

Index P

Highway function 143 PDIFFCHANGEAVE function for BALANCE 176 Highway function 145 PDIFFCHANGEMAX function for BALANCE 176 Highway function 145 PDIFFCHANGEMIN function for BALANCE 176 Highway function 145 PDIFFCUTOFF Highway variable 143 using in BALANCE variable 173 PDIFFMAX function for BALANCE 176 Highway function 145 PDIFFMIN function for BALANCE 176 Highway function 145 PDIFFVALUE PARAMETERS keyword, Highway 227 PEDESTRIANFLOW JUNCTION keyword, geometric signals 299 JUNCTION keyword, two-way stop 309 PEDESTRIANPHASE JUNCTION keyword, geometric signals 299 PEDESTRIANSPEED JUNCTION keyword, two-way stop 309 penalty boarding, perceived, skim function 621 boarding, Public Transport 669 transfer, actual, skim function 621 transfer, perceived, skim function 621 PENI PATHLOAD keywords, Highway 240 REPORT keyword, Highway 250 PENIFACTOR PATHLOAD keyword, Highway 241 PERCENT select-link expression keyword, Public Transport 637 PERIOD CROWDMODEL keyword, Public Transport 664 FILEI JUNCTIONI subkeyword, Highway 194 PGF SETPA keyword, Fratar 131 PGM RUN keyword, Pilot 109 PHASE JUNCTION keyword, overview 278

JUNCTION keyword, signals 293 PROCESS keyword, Generation 593 PROCESS keyword, Highway 249 PROCESS keyword, Network 388 PHASE1 TRNBUILD control statement 930 phases defining in scripts 248 INPUT, Network program 394 LINKMERGE, Network program 395 Network program 393 NODEMERGE, Network program 394 NODEREAD, Public Transport 644 Public Transport program 641 SUMMARY, Network program 395 PHASES. JUNCTION keyword, geometric signals 300 JUNCTION keyword, overview 278 JUNCTION keyword, signals 294 PHASINGI FILEI keyword, SYNCHIMP utility 962 PILOT example, typical application template 115 Pilot program control statements 87 example in loop 115 example with logic 116 introduction 81 process 82 project file 81 tokens in 85 PKTPTHSIZ PARAMETERS keyword, Cube Avenue 1022 PLANID PARAMETERS keyword, SYNCHIMP 963 PLATESIZE PLOTTER keyword, Network 384 PLOT Network control statement 377 PLOTTER BANDWIDTH 378 Network control statement 378 plotting networks complex example 403 simple link example 403 theory 398 PNR TRNBUILD control statement 932 Poisson distribution function 37

Cube Voyager Reference Guide 1073

Index P

inverse function 37 POISSONDIST numeric function 37 POISSONINV numeric function 37 PORT SENDMAIL keyword, Pilot 112 POST PLOTTER POSTLINKVAR subkeyword, Network 385 POSTLINKVAR PLOTTER keyword, Network 384 POSTNODEVAR PLOTTER keyword, Network 385 POW 37 PREFIX LOG keyword, general 55 PRINT control statement, general 66 Distribution control statement 542 FILEO PAO subkeyword, Generation 592 Fratar control statement 542 Generation control statement 542 Highway control statement 247 Matrix control statement 542 Network control statement 387 Pilot control statement 104 PRINT FILE subkeyword, general 67 PRINT PRINTO subkeyword, general 69 Public Transport control statement 771 REPORT MARGINREC subkeyword, Matrix 550 PRINTFILES WAIT4FILES keyword, Cube Cluster 990 printing defining character formats 71 defining numeric formats 70 example listing links in 401 PRINTO FILEO keyword, Highway 206 FILEO keyword, Matrix 525 FILEO keyword, Network 368 FILEO keyword, Pilot 95 FILEO keyword, Public Transport 718 PRINT keyword, general 69 PRINTROW control statement, general 73 Distribution control statement 542 Fratar control statement 542 Highway control statement 248 Matrix control statement 542 Public Transport control statement 771 priority junctions 329

geometric, example 335 geometric, keywords 331 keywords 330 overview 329 saturation-flow, example 338 saturation-flow, keywords 336 PRNFILE RUN keyword, Pilot 109 PROBABILITY select-link expression keyword, Public Transport 637 PROCESS Generation control statement 592 Highway control statement 248 Network control statement 388 PROCESSID DISTRIBUTEINTRASTEP keyword, Cube Cluster 991 DISTRIBUTEMULTISTEP keyword, Cube Cluster 988 PROCESSLIST DISTRIBUTEINTRASTEP keyword, Cube Cluster 991 PROCESSNUM DISTRIBUTEMULTISTEP keyword, Cube Cluster 988 program features 5 PROJECTLINK, Highway variable 140 PROMPT Pilot control statement 105 public transport network developing, example 876 loading trip matrix, example 883 nontransit legs 730 Public Transport program data preparation 603 demand loading 604 input files 864 linking to Highway program 865 modeling 603 output files 864 overview 601 phases 641 processes 607 reports, details 786 reports, overview 605 routes, finding 603 skimming 604 system data input file 703 terminology 605 PURPOSE GRAVITY keyword, Distribution 574 PARAMETERS keyword, TPP2UB 960

1074 Cube Voyager Reference Guide

Index Q

Q QUESTION PROMPT keyword, Pilot 105 R R LOOKUP keyword, general 58 print format code, numeric items 71 print format code, string items 72 RAAD convergence testing calculation 172 Highway variable 142 PARAMETERS keyword, Highway 227 using in BALANCE variable 173 RAADAVE function for BALANCE 176 Highway function 144 RAADCHANGE function for BALANCE 174 Highway function 143 RAADCHANGEAVE function for BALANCE 176 Highway function 145 RAADCHANGEMAX function for BALANCE 176 Highway function 145 RAADCHANGEMIN function for BALANCE 176 Highway function 144 RAADCUTOFF Highway variable 143 using in BALANCE variable 173 RAADMAX function for BALANCE 176 Highway function 144 RAADMIN function for BALANCE 176 Highway function 144 RAND 37 RANDOM 37 RANDOMNESS JUNCTION keyword, common description 286 JUNCTION keyword, overview 278 RANDSEED 37 RANGE CROSSTAB COL subkeyword, Network 355 CROSSTAB ROW subkeyword, Network 356 FREQUENCY keyword, Matrix 533 REPORT VDTSPD keyword, Highway 251 READ

control statement, general 75 READNTLEGI GENERATE keyword, Public Transport 736 REBESTPATHCOST FACTORS keyword, Public Transport 676 RECI FILEI keyword, Matrix 503 impact on Cube Cluster 983 RECI processing Matrix program 417 RECI.NUMFIELD Matrix built-in variable 409 RECI.NUMRECORDS Matrix built-in variable 409 RECI.RECERR Matrix built-in variable 409 RECI.RECNO Matrix built-in variable 409 RECO FILEO keyword, Matrix 525 WRITE keyword, Matrix 554 RECO processing Matrix program 417 RECORD COMPARE keyword, Network 352 MERGE keyword, Network 372 RECOSTMAX FACTORS keyword, Public Transport 677 REDIRECTIN RUN keyword, Pilot 109 REDIRECTOUT RUN keyword, Pilot 109 RELATIVEGAP PARAMETERS keyword, Highway 227 REMOVEFROMGROUP SETGROUP keyword, Highway 253 RENAME FILEI LINKI subkeyword, Network 361 RENUMBER Fratar control statement 543, 543 impact on Cube Cluster 983 REPL_DUP PARAMETERS keyword, Network 376 REPLACESTR 39 REPLACESTRIC 39 REPORT Distribution control statement 576 FILEO RECO subkeyword, Matrix 527 Fratar control statement 128 FREQUENCY keyword, Matrix 533

Cube Voyager Reference Guide 1075

Index R

Generation control statement 594 Highway control statement 249 Matrix control statement 548 Network control statement 390 Pilot control statement 107 Public Transport control statement 772 TRNBUILD control statement 934 REPORTI FILEI ROUTEI subkeyword, Public Transport 701 FILEO ROUTEO subkeyword, Public Transport 720 produced report, example 789 REPORTJ FILEI ROUTEI subkeyword, Public Transport 701 FILEO ROUTEO subkeyword, Public Transport 720 REPORTO FILEO keyword, Public Transport 718 reports enumerated routes 787 evaluated routes 788 fare matrices 792 public transport network 774 Public Transport, overview 786 transfers between modes 795 transfers between operators 796 transit line summary 793 transit-line loadings 794 REREPORT Public Transport control statement 774 RESULT LOOKUP NAME subkeyword, general 57 RESUME CLEARERROR keyword 89 REV FILEI LINKI subkeyword, Network 362 REVERSESTR 39 REWAITMAX FACTORS keyword, Public Transport 678 REWAITMIN FACTORS keyword, Public Transport 678 REWIND PRINT FILE subkeyword, general 67 PRINT PRINTO subkeyword, general 69 RGAP convergence testing calculation 172 Highway variable 142 using in BALANCE variable 173 RGAPAVE function for BALANCE 175

Highway function 144 RGAPCHANGE function for BALANCE 174 Highway function 143 RGAPCHANGEAVE function for BALANCE 175 Highway function 144 RGAPCHANGEMAX function for BALANCE 175 Highway function 144 RGAPCHANGEMIN function for BALANCE 175 Highway function 144 RGAPCUTOFF Highway variable 142 using in BALANCE variable 173 RGAPMAX function for BALANCE 175 Highway function 144 RGAPMIN function for BALANCE 175 Highway function 144 RIGHTSTR 39 RMSE convergence testing calculation 172 Highway variable 142 PARAMETERS keyword, Highway 227 using in BALANCE variable 173 RMSEAVE function for BALANCE 177 Highway function 145 RMSECHANGE function for BALANCE 174 Highway function 143 RMSECHANGEAVE function for BALANCE 177 Highway function 145 RMSECHANGEMAX function for BALANCE 177 Highway function 145 RMSECHANGEMIN function for BALANCE 177 Highway function 145 RMSECUTOFF Highway variable 143 using in BALANCE variable 173 RMSEMAX function for BALANCE 177 Highway function 145 RMSEMIN

1076 Cube Voyager Reference Guide

Index R

function for BALANCE 177 Highway function 145 ROUND, numeric function 37 roundabouts empirical, keywords 316 example, empirical 325 example, gap-acceptance 328 keywords, gap-acceptance 327 overview 314 route enumeration components generated 674 determining routes, theory 824 maximum transfers in route 670 minimum-cost routes, finding 821 modes, not using 670 must-use mode, theory 825 overview 603 process overview, Public Transport 611 required transit modes 676 theory 820 transit connectors, finding 822 route evaluation fares, including in cost 764 initial wait time 673 overview 603 process overview, Public Transport 612 required transit modes 676 theory 826 route file format 768 ROUTEI FILEI keyword, Public Transport 700 ROUTEO FILEO subkeyword, Public Transport 719 ROW CROSSTAB keyword, Network 355 ROWADD COMP function, Matrix 483 Highway function 141 Matrix built-in function 410 matrix function, Highway 187 ROWAVE COMP function, Matrix 483, 483 Highway function 141 Matrix built-in function 410 matrix function, Highway 187 ROWCNT COMP function, Matrix 483, 483 Highway function 141 Matrix built-in function 410 matrix function, Highway 187

ROWDIV COMP function, Matrix 483 Highway function 142 Matrix built-in function 410 matrix function, Highway 187 ROWFAC COMP function, Matrix 483 Highway function 141 Matrix built-in function 410 matrix function, Highway 187 ROWFIX COMP function, Matrix 483 Highway function 141 Matrix built-in function 410 matrix function, Highway 187 ROWMAX COMP function, Matrix 484 Highway function 141 Matrix built-in function 410 matrix function, Highway 188 ROWMIN COMP function, Matrix 484 Highway function 141 Matrix built-in function 410 matrix function, Highway 188 ROWMPY COMP function, Matrix 484 Highway function 141 Matrix built-in function 410 matrix function, Highway 188 ROWREAD COMP function, Matrix 485 ROWSUM COMP function, Matrix 485 Highway function 141 Matrix built-in function 410 matrix function, Highway 188 RT LINE NODES subkeyword, Public Transport 752 LINE NODES subkeyword, TRNBUILD 920 RUN Pilot control statement 107 RUNFACTOR FACTORS keyword, Public Transport 679 RUNTIME LINE keyword, TRNBUILD 921 LINE NODES subkeyword, Public Transport 754 relation to RT, TRNBUILD 920 RUNTIMEADJ REPORT keyword, TRNBUILD 937

Cube Voyager Reference Guide 1077

Index S

S S print format code, numeric items 71 SAME FARESYSTEM STRUCTURE subkeyword, Public Transport 693 SATFLOWPERLANE JUNCTION keyword, overview 278 JUNCTION keyword, saturation-flow priority junctions 338 JUNCTION keyword, signals 294 saturation flow 302, 338 Saturn, converting output to Cube Voyager format 964 SAVEPRN DISTRIBUTEINTRASTEP keyword, Cube Cluster 991 scientific format 70 SCREENLINE FILEO ESTMICPO subkeyword, Highway 203 screenline file creating 863 SCREENLINEI FILEI keyword, Public Transport 702 SCREENLINEO FILEO keyword, Public Transport 722 SCREENVAR FILEO SCREENLINEO subkeyword, Public Transport 723 SEATCAP LINE keyword, Public Transport 754 VEHICLETYPE keyword, Public Transport 781 SEGLIMITS TRNBUILD control statement 937 SEGMENTS PARAMETERS keyword, Cube Avenue 1023 SELECT FILEI LINKI subkeyword, Network 362 FILEI ZDATI subkeyword, Highway 200 FILEI ZDATI subkeyword, Matrix 509 PNR keyword, TRNBUILD 934 TRNBUILD control statement 938 select link process, Public Transport program 628 SELECTBYMAT FILEI ROUTEI subkeyword, Public Transport 702 FILEO ROUTEO subkeyword, Public Transport 720 SELECTGROUP FILEO PACKETLOG subkeyword, Cube Avenue 1016 PATHLOAD MW subkeyword, Highway 236

SELECTIJ Public Transport phase 649 SELECTLINK FILEO PACKETLOG subkeyword, Cube Avenue 1016 PATHLOAD MW subkeyword, Highway 237 select-link function applying criteria simultaneously 635 combining criteria 633 demand criteria 637 description 628 links 630 loading partial demand 638 mode 633 movement types 636 nodes 632 not conditions 635 transit line 631 transit operator 633 SELECTLINKGROUP PATHLOAD MW subkeyword, Highway 238 SENDMAIL Pilot control statement 111 SEQSIZE PARAMETERS keyword, TRNBUILD 929 service-frequency mode example 836 SERVICEMODEL FACTORS keyword, Public Transport 679 SET Distribution control statement 552 FILEI JUNCTIONI subkeyword, Highway 194 Fratar control statement 552 Generation control statement 552 Highway control statement 252 Matrix control statement 552 SETGROUP Highway control statement 253 SETPA Distribution control statement 577 Fratar control statement 129 SETS FILEI TURNPENI subkeyword, Public Transport 707 SETUP phase Cube Avenue 1001 Highway program 155 SETUPPER LOOKUP keyword, general 58 signals fixed-time, example 302

1078 Cube Voyager Reference Guide

Index S

geometric, example 300 keywords, generic 291 keywords, geometric 296 overview 290 saturation flow, example 302 SIN 38 SINGLELANE JUNCTION keyword, overview 278 JUNCTION keyword, priority junctions 330 JUNCTION keyword, signals 295 JUNCTION keyword, two-way stop 309 SIZE LOOKUP keyword, general 58 skim functions best actual trip time 622 boardings 623 composite cost 623 distance 623 excess demand 624 fare 621 overview 615 penalties 620 summary 625 travel time 619 value of choice 624 wait time 617 SKIMIJ Public Transport phase 650 skimming example 881 overview 604 process, Public Transport 614 quick reference 625 theory 839 SKIP0 FILEO LINKO subkeyword, Public Transport 714 REPORT LINES subkeyword, Public Transport 773 REPORT LINEVOLS subkeyword, Public Transport 773 SKIPBADLINES FILEI LINEI subkeyword, Public Transport 697 PARAMETERS keyword, Public Transport 766 SKIPMODES SELECT keyword, TRNBUILD 939 SLACK GENERATE keyword, Public Transport 736 SMTPSERVER SENDMAIL keyword, Pilot 112 SORT control statement, general 76 Cube Cluster impact 983

Distribution control statement 553 FILEI DBI subkeyword, Matrix 497 FILEI RECI subkeyword, Matrix 506 Fratar control statement 553 Generation control statement 553 Highway control statement 254 Matrix control statement 553 Network control statement 391 REPORT LINES subkeyword, Public Transport 773 SPDCAP Highway control statement 254 Network control statement 392 SPDCODE LINK keyword, TRNBUILD 924 SPEED Highway variable 140 LINE NODES subkeyword, Public Transport 752 LINE NODES subkeyword, TRNBUILD 920 LINK keyword, TRNBUILD 924 NT keyword, Public Transport 761 REPORT keyword, Highway 250 REPORT keyword, Network 390 REPORT keyword, TRNBUILD 937 setting, example in Cube Avenue 1035 SPDCAP keyword, Highway 254 SPDCAP keyword, Network 392 SUPPLINK keyword, TRNBUILD 940 SUPPORT keyword, TRNBUILD 943 value computed, Highway LINKREAD phase 158 variable, Cube Avenue 1003 SPEEDFOR COMP function, Network 351 Highway function 142 Network function 346 SPLIT CHOICE keyword, cost-based model 464 CHOICE keyword, utility-based model 467 XCHOICE keyword, cost-based model 471 XCHOICE keyword, utility-based model 474 SPLITCOMP XCHOICE SPLIT subkeyword, cost-based model 471 SPLITINTO CHOICE DESTSPLIT subkeyword, cost-based model 463 CHOICE SPLIT subkeyword, cost-based model 464 XCHOICE DESTSPLIT subkeyword, cost-based model 470 XCHOICE SPLIT subkeyword, cost-based model 471 SPREAD definition 681

Cube Voyager Reference Guide 1079

Index T

SPREADCONST FACTORS keyword, Public Transport 680 SPREADFACT FACTORS keyword, Public Transport 680 SPREADFUNC FACTORS keyword, Public Transport 681 SQRT 37 STACK REPORT keyword, Pilot 107 standing 748 START FILEI LINKI subkeyword, Network 362 starting Cube Voyager 12 STARTMW CHOICE keyword, cost-based model 464 CHOICE keyword, utility-based model 468 XCHOICE keyword, cost-based model 472 XCHOICE keyword, utility-based model 475 statement tokens 24 STOP FILEI LINKI subkeyword, Network 362 STOP2STOPO FILEO keyword, Public Transport 724 STOPGROUP FILEO STOP2STOPO subkeyword, Public Transport 727 STOPNODES REREPORT keyword, Public Transport 777 stops. See two-way stops, all-way stops STOPSONLY FILEO NETO subkeyword, TRNBUILD 915 REPORT LINEVOL subkeyword, TRNBUILD 936 REPORT LINEVOLS subkeyword, Public Transport 774 REPORT LINKVOL subkeyword, TRNBUILD 936 STORAGE script variable, Cube Avenue 1030 setting, example in Cube Avenue 1035 variable, Cube Avenue 1004 STORAGESPACE JUNCTION keyword, overview 278 JUNCTION keyword, two-way stop 310 STR 39 strings maximum length 226 print format 66 STRLEN 39 STRLOWER 39 STRPOS 39 STRPOSEX 39 STRUCTURE

FARESYSTEM keyword, Public Transport 693 STRUPPER 39 SUBAREAMAT PATHLOAD keyword, Highway 241 SUBAREAMATO FILEO keyword, Highway 206 impact on Cube Avenue 1014 impact on Cube Cluster 982 SUBAREANETI FILEI keyword, Highway 195 SUBJECT SENDMAIL keyword, Pilot 113 subkeywords 29 SUBSTR 39 SUM FILEI ZDATI subkeyword, Highway 200 FILEI ZDATI subkeyword, Matrix 509 MERGE keyword, Network 373 SUMMARY phase Network program 395 variable referencing 396 SUPPLINK TRNBUILD control statement 940 SUPPORT TRNBUILD control statement 941 SUPPORTO FILEO keyword, TRNBUILD 915 SYMBOL PLOTTER LEGEND subkeyword, Network 382 SYNCHIMP 961 SYNCHIMP utility 961 SYSTEMI FILEI keyword, Public Transport 703 T T print format code, numeric items 71 print format code, string items 72 TURNS keyword, Highway 256 T0 Highway variable 140 setting, example in Cube Avenue 1035 value computed, Highway LINKREAD phase 159 variable, Cube Avenue 1004 T1 Highway variable 140 value set, Highway LINKREAD phase 159 variable, Cube Avenue 1004 TAN 38 TAPER

1080 Cube Voyager Reference Guide

Index T

PLOTTER BANDWIDTH subkeyword 379 TC FUNCTION keyword, Highway 212 TCCOEFF PARAMETERS keyword, Highway 228 TCEXP PARAMETERS keyword, Highway 229 terminology, Public Transport program 605 TF LINE NODES subkeyword, Public Transport 752 LINE NODES subkeyword, TRNBUILD 920 theory Cube Avenue 1025 Network program 393 THISPROCESS Cube Cluster impact 984 Matrix built-in variable 410 THRUNODE PATHLOAD keyword, Highway 242 TIME Highway array 141 LINE NODES subkeyword, Public Transport 753 LINE NODES subkeyword, TRNBUILD 920 LINK keyword, TRNBUILD 924 PNR keyword, TRNBUILD 934 SUPPLINK keyword, TRNBUILD 941 value set, Highway LINKREAD phase 159 TIMEA skim function, Public Transport 619 skim function, summary 626 TIMEFAC LINE keyword, Public Transport 754 LINE keyword, TRNBUILD 921 TIMEP skim function, Public Transport 620 skim function, summary 626 TIMINGI FILEI keyword, SYNCHIMP utility 962 TITLE COMPARE keyword, Network 352 FREQUENCY keyword, Matrix 533 PRINTROW keyword, general 74 TO FACTORS XFERCONST subkeyword, Public Transport 682 FACTORS XFERFACTOR subkeyword, Public Transport 683 FACTORS XFERPEN subkeyword, Public Transport 684 SENDMAIL keyword, Pilot 113 TOD

PARAMETERS keyword, TPP2UB 960 TOLERANCE LOOKUP keyword, general 58 TOLLFACTOR FILEI TOLLMATI subkeyword, Highway 196 PATHLOAD keyword, Highway 242 TOLLMATI FILEI keyword, Highway 195 path-based toll function 151 PATHLOAD keyword, Highway 242 TOLLROUND FILEI TOLLMATI subkeyword, Highway 197 TOLLS FILEI TOLLMATI subkeyword, Highway 197 TONODE GENERATE keyword, Public Transport 737 TPP2UB 959 TPP2UB utility 959 TRACE PATHLOAD keyword, Highway 243 REPORT keyword, Generation 594 REPORT keyword, Highway 250 REPORT keyword, Matrix 551 REPORT keyword, Pilot 107 SELECT keyword, TRNBUILD 939 TRACEI FILEI ROUTEI subkeyword, Public Transport 702 FILEO ROUTEO subkeyword, Public Transport 721 report produced, example 790 TRACEJ FILEI ROUTEI subkeyword, Public Transport 702 FILEO ROUTEO subkeyword, Public Transport 721 TRAM PARAMETERS keyword, Matrix 541 transfers actual penalty, skim function 621 actual wait time, skim function 618 banning between modes 684 between modes, report 795 between operators, report 796 maximum in route 670 method 763 penalty between modes 684 penalty weighting factor 683 penalty, constant to add 682 perceived penalty, skim function 621 perceived wait time, skim function 619 report by line 776 transit lines attribute report 776

Cube Voyager Reference Guide 1081

Index U

demand using, selecting 631 errors in data, ignoring 766 excessive travel time, message 763 links file, including data in 711 loadings, report 794 passenger boardings, generating report 773 report summarizing 793 reports, including in 775 summary report, generating 772 travel demand on, identifying 628 travel time, computation of 755 travel time, extending control value 764 travel time, link 767 transit network maximum node number, TRNBUILD 931 transposed matrix 410 TRANTIME PARAMETERS keyword, Public Transport 767 travel time actual, skim function 619 crowded link, perceived, skim function 620 perceived, skim function 620 transit line 767 transit line, exceeding control value, report 763 transit line, extending control values 764 TRIM 39 Trip Matrix processing 893 trip purposes 568 trip time best, skim function 622 TRIPS TRNBUILD control statement 945 trips. number computed 768 unsuccessful proportion, skim function 624 unsuccessful, skim function 624 TRIPSIJ PARAMETERS keyword, Public Transport 768 TRIPSXY FILEI LINKI subkeyword, Network 362 TRNBUILD converting from TRNPTH 953 TRNBUILD Control Statement Overview 902 TRNBUILD Control Statement Summary 902 TRNBUILD Examples 952 TRNBUILD Important Notice 891 TRNBUILD Introduction 893 TRNCOEF PARAMETERS keyword, TPP2UB 960 TRNLEGS1

REREPORT keyword, Public Transport 778 TRNLEGS2 REREPORT keyword, Public Transport 778 TRNLEGS3 REREPORT keyword, Public Transport 779 TRNLEGS4 REREPORT keyword, Public Transport 779 TRNPTH 953 turn penalty files input, name of 704 turn times converting to costs 229 TURNCHANNELIZED JUNCTION keyword, overview 278 JUNCTION keyword, two-way stop 311 TURNCOSTFAC PARAMETERS keyword, Highway 229 TURNGAPWT PARAMETERS keyword, Highway 229 TURNPENI FILEI keyword, Highway 197 FILEI keyword, Public Transport 704 TURNPENO FILEO keyword, Highway 207 TURNS Highway control statement 255 TURNVOLO FILEO keyword, Highway 207 two-way stop-controlled intersections 305 two-way stops example 312 keywords 306 overview 305 TXT FILEO TURNVOLO file format 209 TYP FILEI LINKI VAR subkeyword, Network 363 TYPE FILEO MATO subkeyword, Public Transport 716 JUNCTION keyword, common description 287 JUNCTION keyword, overview 278 select-link expression keyword, Public Transport 636 U UB2TPP utility 957 UNCONNECTED REPORT keyword, Network 390 UNITEXTENSION JUNCTION keyword, geometric signals 300 UNITFARE

1082 Cube Voyager Reference Guide

Index V

FARESYSTEM keyword, Public Transport 694 UNITS junction file control statement 278 PARAMETERS keyword, SYNCHIMP 963 UPDATEVARS WAIT4FILES keyword, Cube Cluster 990 URL DOWNLOAD keyword, Pilot 94 user class example 884 list of 768 overview 769 passenger loading report by 774 trips loaded 768 user stacks, Highway program 259 USERCLASS REREPORT keyword, Public Transport 779 USERCLASSES PARAMETERS keyword, Public Transport 768 REPORT LINEVOLS subkeyword, Public Transport 774 USERNAME SENDMAIL keyword, Pilot 113 USERUNTIME PARAMETERS keyword, TRNBUILD 929 UTILITIES CHOICE keyword, utility-based model 468 UTILITIESMW XCHOICE keyword, utility-based model 475 V V FUNCTION keyword, Highway 213 V, Highway variable 140 V4ROUTEFORMAT PARAMETERS keyword, Public Transport 768 VAL 39 SET keyword, Highway 252 SET keyword, Matrix 552 ValOfChoice skim function, Public Transport 624 skim function, summary 626 value of choice skim function 624 VALUEMW FREQUENCY keyword, Matrix 533 VALUEOFTIME FACTORS keyword, Public Transport 682 VAR ARRAY keyword, Highway 181 ARRAY keyword, Matrix 453 ARRAY keyword, Network 349

COMP keyword, Highway 184 COMP keyword, Matrix 479 COMP keyword, Public Transport 659 CROSSTAB keyword, Network 356 FILEI LINKI subkeyword, Network 363 FILEO ESTMICPO subkeyword, Highway 203 LOG keyword, general 55 VARFORM FILEO LINKO subkeyword, Network 366 VARI FILEI keyword, Pilot 95 FILEI keyword, TPP2UB 959 variables COMP expression, Matrix 480 convergence, Highway program 142 DATAPREP phase, Public Transport 647 Highway 140 LINKREAD phase, Public Transport 646 MATI phase, Public Transport 649 MATO phase, Public Transport 652 matrix 184 Matrix program, built-in 409 naming convention 43 Network program, referencing in 395 NODEREAD phase, Public Transport 645 output, Network program 397 SELECTIJ phase, Public Transport 650 VARO FILEO keyword, UB2TPP 958 VARS FILEO TURNVOLO keyword, Highway 209 REPORT keyword, Pilot 107 SET keyword, Highway 252 SET keyword, Matrix 552 VDTSPD impact on Cube Cluster 983 REPORT keyword, Highway 250 VEHICLETYPE LINE keyword, Public Transport 754 Public Transport control statement 780 VEHPERDIST PARAMETERS keyword, Cube Avenue 1023 VISIBILITY JUNCTION keyword, geometric priority junctions 334 JUNCTION keyword, overview 278 VOL FILEO LINEO subkeyword, Public Transport 709 FILEO NTLEGO subkeyword, Public Transport 718 Highway array 141 LINE NODES subkeyword, Public Transport 753

Cube Voyager Reference Guide 1083

Index W

NT keyword, Public Transport 761 PATHLOAD keyword, Highway 244 REPORT VDTSPD keyword, Highway 252 VOLDATE PARAMETERS keyword, SYNCHIMP 963 VOLFIELDS FILEO LINKO subkeyword, Public Transport 714 VOLT NT keyword, Public Transport 761 VOLTIME PARAMETERS keyword, SYNCHIMP 963 VOLUMEI FILEI keyword, SYNCHIMP utility 962 VOLUMES TRIPS MATRIX ASSIGN subkeyword, TRNBUILD 946 W WAIT PROMPT keyword, Pilot 106 wait curves defining 782 description 783 wait time converting to perceived 905 crowding, actual, skim function 618 crowding, perceived, skim function 618 initial, actual, skim function 618 initial, perceived, skim function 619 theory 799 transfer, actual, skim function 618 transfer, perceived, skim function 619 wait curve 783 WAIT4FILES Cube Cluster control statement 988 WAITCRVDEF Public Transport control statement 782 WAITFACTOR FACTORS keyword, Public Transport 682 walk choice portion of trips allocated to 674 walk time, theory 798 WALKSPEED PARAMETERS keyword, TRNBUILD 930 WEIGHTS. PARAMETERS COMBINE keyword, Highway 225 WIDTH JUNCTION keyword, geometric priority junctions 335 JUNCTION keyword, overview 278 Windows

starting Cube Voyager from 13 work matrices maximum index, Highway 226 maximum index, Matrix 540 maximum index, Public Transport 765 WORKRAM PHASE1 keyword, TRNBUILD 931 WRITE Distribution control statement 553 Fratar control statement 553 Generation control statement 553 Matrix control statement 553 X X Network variable 345 XY NODE subkeyword, TRNBUILD 948 XCHOICE CHOICE, differences with 475 Matrix control statement 468 XFARE FARE keyword, TRNBUILD 908 XFERCONST FACTORS keyword, Public Transport 682 XFERFACTOR FACTORS keyword, Public Transport 683 XFERGEN TRNBUILD control statement 947 XFERLEGS REREPORT keyword, Public Transport 780 XFERMETHOD GENERATE keyword, Public Transport 737 XFERPEN FACTORS keyword, Public Transport 684 XFERPENA skim function, Public Transport 621 skim function, summary 626 XFERPENP skim function, Public Transport 621 skim function, summary 626 XN FILEO NTLEGO subkeyword, Public Transport 718 NT keyword, Public Transport 761 XPEN FACTOR keyword, TRNBUILD 905 XPENFAC FACTOR keyword, TRNBUILD 906 XWAITA skim function, Public Transport 618 skim function, summary 626

1084 Cube Voyager Reference Guide

Index Y

XWAITCURVE FACTORS keyword, Public Transport 685 XWAITFAC FACTOR keyword, TRNBUILD 906 XWAITMAX FACTOR keyword, TRNBUILD 906 XWAITMIN FACTOR keyword, TRNBUILD 906 XWAITP skim function, Public Transport 619 skim function, summary 626 XY TRNBUILD control statement 948 XY keyword, TRNBUILD 948 XYALL SUPPLINK keyword, TRNBUILD 941 SUPPORT keyword, TRNBUILD 944 XYFAC SUPPLINK keyword, TRNBUILD 941 SUPPORT keyword, TRNBUILD 944 XYFACTOR PARAMETERS keyword, TRNBUILD 930 XYSPD LINE NODES subkeyword, Public Transport 753 LINE NODES subkeyword, TRNBUILD 920 XYSPEED LINE keyword, Public Transport 755 LINE keyword, TRNBUILD 921 Y Y Network variable 345 XY NODE subkeyword, TRNBUILD 948 yield-controlled intersections geometric, example 335 geometric, keywords 331 keywords 330 overview 329 saturation flow, keywords 336

Z Z FILEI ZDATI subkeyword, Highway 200 FILEI ZDATI subkeyword, Matrix 510 FILEO RECO subkeyword, Matrix 527 Matrix built-in variable 410 ZDAT Report keyword, Highway 252 REPORT keyword, Matrix 551 ZDATI FILEI keyword, Highway 198 FILEI keyword, Matrix 506 zonal timing messages Highway 229 Matrix 541 Public Transport 769 zone lacking valid routes 766 lists, working with 413 substituting 415 ZONEACCESS TRNBUILD control statement 949 ZONEMSG PARAMETERS keyword, Highway 229 PARAMETERS keyword, Matrix 541 PARAMETERS keyword, Public Transport 769 PARAMETERS keyword, TRNBUILD 930 ZONEO RENUMBER keyword, Matrix 546 ZONES Highway variable 140 Matrix built-in variable 410 PARAMETERS keyword, Distribution 576 PARAMETERS keyword, Fratar 128 PARAMETERS keyword, Highway 230 PARAMETERS keyword, Matrix 541 PARAMETERS keyword, Network 376 PNR keyword, TRNBUILD 934 RENUMBER keyword, Matrix 546

Cube Voyager Reference Guide 1085

Index Z

1086 Cube Voyager Reference Guide