RG_CubeVoyager

Cube Voyager Reference Guide Cube Voyager Reference GuideCube 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 1 Introduction 1 Introduction This chapter introduces you to Cube Voyager. Topics include: • • • Design concepts Program features Minimum system requirements 2 Cube Voyager Reference Guide and operate most efficiently with large amounts of RAM. and consume a considerably large amount of computer resources. Some programs could execute for hours. A typical application could involve Cube Voyager Reference Guide 3 . 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. and Public Transport. The individual programs are activated according to the instructions in the script. Matrix. In addition. These supplementary programs provide an easy-to-use interface to the basic four programs. but only as specified by the user. Users may implement any model formulation desired in the scripting language. such as the Generate program for trip generation and the Distribution program for trip distribution. the system offers supplementary programs for common transportation planning tasks. any one of which could require a relatively large amount of input control data. Typically. 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.Introduction Design concepts 1 Design concepts Cube Voyager is designed to be an integrated modeling system for transportation planning applications. This provides a flexible environment and grants control over all aspects of the modeling process. transportation planning software is run as a series of independent programs. users are free to change and modify runs as they progress. Each program is designed to perform certain operations. Cube Voyager is an excellent choice for model applications which require congestion feedback mechanisms. The script is stored in a file and then read when the system is executed. Highway. At the heart of the Cube Voyager system is a flexible control language referred to as a scripting language. Cube Voyager has no hard coded mechanisms. The Cube Voyager system has four main assignment programs: Network. but they can be translated to other formats by the user. 4 Cube Voyager Reference Guide . It is the user’s responsibility to design the process that is to be run. or can be as simple as computing and/or printing a number from a file. 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.1 Introduction Design concepts a very complicated set of instructions. 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.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).999. TP+ and others. MINUTP. TRIPS.Introduction Program features 1 Program features Advanced features of the Cube Voyager software include: • Integration with ESRI’s 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. 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 . maximum nodes=999.000. maximum links=999. 1 Introduction Program features • Capability to link with user-generated native code 6 Cube Voyager Reference Guide . Zonal data files are not very large. Cube Voyager Reference Guide 7 . Cube Voyager is designed to run in a multitasking environment. networks. Each cell value can be from 0 to 9 bytes in size. and network sizes will depend upon the number of alternatives and variables that the user wishes to employ. About 75 MB of disk space is required to install Cube Base and Cube Voyager. A matrix will contain zones × zones cells of information. A typical application will require zonal data files. This could possibly cause problems if one application is trying to update a file while other applications are accessing it. The largest storage requirements will be associated with matrices. In such an environment. It is fairly safe to state that if a computer can run Windows. there is a possibility that several simultaneous applications could try to access the same data files simultaneously. The exact amount of RAM required can not be determined until an application actually runs and the combination of user options is diagnosed. The largest networks will be only a few MB.Introduction Minimum system requirements 1 Minimum system requirements Cube Voyager requires a Windows 95/98/NT/2000/XP environment in which to function. most applications will not require any special RAM considerations. it has enough RAM to run Cube Voyager. The user can control the matrix sizing. Additional disk space is required for the various files. but Cube Voyager uses a proprietary data compression technique that helps to reduce the sizes. The system utilizes RAM as needed. and matrices. 1 Introduction Minimum system requirements 8 Cube Voyager Reference Guide . Cube Voyager Reference Guide Cube Voyager Reference Guide 9 . 2 Getting Started 2 Getting Started This chapter describes how to get started using Cube Voyager. Topics include: • • Installation Starting Cube Voyager 10 Cube Voyager Reference Guide . follow the steps outlined below: • • Install the Citilabs license CD first Once the license files are installed.Getting Started Installation 2 Installation To install Cube Voyager. Cube Voyager should automatically be selected during the installation of Cube Cube Voyager Reference Guide 11 . go to the Program menu. “Application Manager.” in the Cube Base Reference Guide for general information on setting up an application in Application Manager. “Task Monitor. then VOYAGER to access Cube Voyager programs from the menus. point to Passenger Forecasting. After creating a new Cube Voyager application or opening an existing one. When running a Cube Voyager application or program in Cube from Application Manager. See Chapter 14. See “Running application in Application Manager” on page 655 of the Cube Base Reference Guide and “Running a Cube Voyager. 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. Task Monitor sends the Cube Voyager 12 Cube Voyager Reference Guide . TP+. See Chapter 16. 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.2 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.” in the Cube Base Reference Guide for a detailed description of this program. 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 . Starting Cube Voyager from Windows If Cube Voyager has been properly installed. Cube Voyager can be started from: Start Menu. then type or browse for VOYAGER.EXE (the default directory is C:\Program Files\Citilabs\CubeVoyager).Getting Started Starting Cube Voyager 2 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. Run. 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. 14 Cube Voyager Reference Guide . See “Starting a model run” on page 577 of the Cube Base Reference Guide. The Edit Input File button can be used to open the current job script file in Cube for editing or running directly from Cube. while the Favorite button points to the Windows Favorite directory. The only difference is that the Browse button points to the current directory. with the Favorite button. Both buttons invoke an Open File dialog box.2 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. after the execution is completed. respectively. The Pause button can be used to pause the execution. The window can be minimized or left open as Cube Voyager is executing. During execution. Cube Voyager begins execution and the Start and the Cancel buttons become the Pause and the Abort buttons. periodic messages will be written to the window.Getting Started Starting Cube Voyager 2 The Work Directory is defaulted to the directory where the job script file resides when a new job script file is selected. Cube Voyager Reference Guide 15 . while the Abort button allows for pre-mature termination of the execution. The Notify When Done check box can be used to bring the Cube Voyager window back on top when it’s done. When this data is completed and the Start button is pressed. The default behavior is to have the Cube Voyager window maintain its current status. if it has been minimized during execution. minimized or maximized. When the application is finished. the View Print File button can be pushed to view the resulting run print file. 16 Cube Voyager Reference Guide . 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. “Cube Cluster.2 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. See Chapter 15. 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.” for a detailed description of this process. 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 2 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. The following statement will initiate a Cube Voyager run from a command line with the appropriate parameters and options: Voyager.EXE should be added to the PATH system variable. The path to VOYAGER. so that. it can be run from any working directories. Starting Cube Voyager from the command prompt You can run Cube Voyager completely from a command prompt (if this capability is available). it may be necessary to provide a fully qualified file name (path\filename).PRJ file in the working subdirectory: the prefix will be set to the last prefix in the file. it will generate a file by that name. and are not a Cube Voyager operator ('". pagewdth. Most individual programs will allow the prefix to be substituted directly for the ? character in their file names. the program will assign one based upon the following criteria: If there is a pppp.PRJ. The maximum value is 32767. In some operating environments (such as Windows). nor greater than 255.PRJ file that Cube Voyager reads is a valid Cube Voyager PRJ file. If it is not specified. It may not be less than 72. This will default to 58. The characters must be those that are acceptable as part of filenames to the operating system. If there is no pppp. The program automatically associates a unique sequence number with the prefix. • pppp is a prefix (or project) that is pertinent to this application. • pagewdth is the maximum length a printed line can have. their effect may be valid for only that program. and a width can not be found from the Cube Voyager 18 Cube Voyager Reference Guide . This file may be in a different subdirectory than the -Spath argument. When set within the individual programs.2 Getting Started Starting Cube Voyager • scriptfile is the name of the file that contains the Cube Voyager script control statements. If the prefix is not designated. • pageht is the height (number of print lines) for a printed page of output.+-*/&|). The pageht. The program will generate a print file and a var file with this prefix as its first characters. Warning: Be sure that any pppp. if the program can not find a height from the Cube Voyager PRJ file. Some files will always contain these characters (maximum 4 characters) as part of their name. and runid parameters can be reset dynamically by Cube Voyager control statements within individual Cube Voyager programs. The name may have a complete path in the typical operating system format. Note that pagewdth will not cause longer length lines to be truncated or folded. it will try to obtain a starting ID from the Cube Voyager PRJ file with matching prefix. 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 . Normally. • workdir is the subdirectory that the application is to be run from. and if so. (Windows may cause some problems in this area. it checks if workdir is specified. in some operating environments. • runid can be used to specify a starting ID for the application. it will default to 132. they will be written with the appropriate length. changes to that subdirectory before it processes the other arguments (excluding filename).Getting Started Starting Cube Voyager 2 PRJ file. But. the user will log onto the desired subdirectory. If ID is not specified. Command line options: • • • • • • • • • /Startfor example to auto start the run.) When the program starts. it may not be possible to log on to a subdirectory before starting the program. and workdir will not need to be specified. The primary use of pagewdth is to assist in formatting messages and reports. 2 Getting Started Starting Cube Voyager • /WinHeight:xx As the Cube Voyager job is executing. 20 Cube Voyager Reference Guide . the Abort button on the Cube Voyager run dialog can be used. control will return to the windows command line interpreter. Otherwise. Pressing Ctrl-Break can be normally used to prematurely terminate the run if the run dialog has been hidden. periodic messages will be written to the Cube Voyager run dialog if /Hide is not on. When the Cube Voyager job is completed. Cube Voyager Reference Guide Cube Voyager Reference Guide 21 . 3 General Syntax 3 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 3 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: & doesn’t fit here mfdus= 61-65 Cube Voyager Reference Guide 23 3 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 3 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 3 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 3 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 3 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 13–5 -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 doesn’t 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 3 square brackets []. When a keyword is subscripted, there may be no special characters prior to the right bracket (]); the subscript must fill the space between the []. Most keywords that are subscripted are specific to the program, and the subscript must be an integer constant. Some programs allow certain vectored keywords to have a variable as the subscript; this is usually only when the keyword is on a COMP (or similar type of statement). Some keywords allow double subscripts to indicate a matrix of rows and columns. In such cases, there are two sets of brackets [row][column]. For example: capacity stratified by lanes (row) and spdclass (column). The row index sets the row where the data is to load and the column index sets where in the row the data loading is to begin. If there is no column designation, it is assumed to be one. One is the minimum value for rows and columns. If there is more input data than is allowed in a row, the data spills into the next row (beginning at that row’s column 1), but it will not fill beyond the end of the array. In certain cases, three-dimensional arrays are allowed, but they are rare, and will be more fully defined in the specific program documentation. 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 3 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 3 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 doesn’t know if the dash is an exponent sign or a field separator. With such values, the entire field must be enclosed within '...' (for example, '1.23E-2'). This same restriction does not apply to constants within an expression because ranges are not allowed. Real numbers are entered as single precision values: precision is restricted to the 6-7 most significant digits (system dependant). Boolean Response -- true/false character. Programs may accept various responses depending upon the native language of the user. In English, for example, a true response could possibly be any of (Yes,1, True), and the negative response could be (No, 0, False); only the first character will be processed. I R ? Cube Voyager Reference Guide 31 3 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 "...". S 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 3 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 3 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 user’s responsibility to ensure that the computed subscripts are within the correct ranges. Unpredictable results could be obtained, or the program could fatally terminate, if the subscripts are incorrect. 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 (user’s responsibility). Most programs will detect an invalid index, and terminate with a fatal condition. 34 Cube Voyager Reference Guide General Syntax Control statement syntax 3 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 3 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 distribution—that 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 distribution—that 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 3 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 3 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 3 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 3 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 3 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 3 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 3 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 3 General Syntax Control statement syntax The possible filename variables formats (illustrated by example) are: Filename format MI. the reference to a zonal value would also include a subscript.3. If varname is a number.2.varname LI.varname ZI.varname NOTE: LI. ZI.5.varname Description refers to the matrix named varname found on the file designated by MATI[3]= on the FILEI control statement. for example.name are used when there is only one NETI allowed in the program (currently applies to only the Highway program).POP[I].3.5. 44 Cube Voyager Reference Guide . refers to the array named varname generated by the file designated by ZDATI[5]= 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. Zonal data are read into zonal arrays. Usually.name and NI. NI. each variable is an array with zones cells. 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. Cube Voyager Reference Guide 45 ... the data entered on them may vary between programs.. ENDIF LOG LOOKUP PRINT PRINTROW READ SORT Control statement introduction (general syntax) Many programs will share the same type of control statements. ELSE . Usually. ELSEIF . All statements follow the format that the statement type is identified by the first word that appears on it.General Syntax Standard control statements 3 Standard control statements This section discusses details about specific control statements. 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. However. however. Topics include: • • • • • • • • • • • • • • Control statement introduction (general syntax) COMP CONSOLE FILEI FILEO GLOBAL ID IF .... This section briefly describes the common format of statements that are used in many of the Cube Voyager programs. the first word is the ControlWord. |. unless the statement contains “trigger” keys. A keyword that is valid only if it follows the values for its Key1. an equal level Key3. and FFF are all valid keywords. They must be followed directly by an equals sign and the associated values.. JJJ. 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). an equal level Key2. The general format for describing Control Statements in this document is: ControlWord Key1 Key1 Key1 (Key2 Key2 (Key3 Key3) ) Key1 (Key2) .. 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. A keyword that is valid only if it follows the values for its Key2. CCC and DDD are valid level 2 keywords. The parenthesis () are used only to indicate the key level. GGG.. or DDD.3 General Syntax Standard control statements Those keywords (termed “trigger” keywords) are identified in their respective program detailed descriptions. and the first keyword is a trigger keyword followed by an equals sign. GGG may follow the values for FFF. HHH and III are level 3 46 Cube Voyager Reference Guide . CCC. or any key3 or key4 (for the same Key1). and KKK. III. A keyword must always be followed by an equals sign and appropriate value(s). EEE. ControlWord is the statement type and must be the first keyword on each statement. BBB. HHH. or a key4 (for the same Key2). and may appear only following the values for either BBB. and may appear any place a keyword is allowed. they are not coded on the statement. or if the first term is a character function or literal character string (beginning with a quote). If the first term is a number. HHH. Often a variable is defined by its presence as a keyword in another COMP statement. namx=substr(name. or numeric variable.General Syntax Standard control statements 3 keywords. it is a character expression.1) . K = j + 2 . its mode is usually determined by the first term in the expression. it is a numeric expression. Invalid: DDD must follow BBB or CCC Invalid: KKK must follow JJJ. or III. Some programs (mostly those involving zonal matrices) may allow the use of INCLUDE and EXCLUDE keywords on the COMP statement. Invalid: HHH must follow GGG Valid. or more. Each expression results in a number or a character string. it means that the statement will be subjected to a zonal Cube Voyager Reference Guide 47 . If there are multiple expressions on a COMP statement. or both. they are solved in left to right order. and may appear only following the values for GGG. declares name as a variable that is 4 characters long.1. of these keywords. declares namx as a character variable that is 12 characters long. COMP COMP statements are used to dynamically assign values to variables and/or matrices. Every term within the expression must be known to the expression at the time the COMP statement is to be compiled.4. KKK is also a level 3 keyword and may appear only after the values for JJJ or KKK. COMP statements contains one. Keyword values AAA=3 BBB=5 DDD=2 EEE=25.3)+'abcde'+str(k. keywords with associated numerical and/or character expressions. All numeric variables that are declared by the user in this manner are internally treated as double precision floating point variables.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. defines K as a numeric variable. When the statement contains either. name=' ' . 48 Cube Voyager Reference Guide . the zone is checked with the EXCLUDE list.mat NETI=??. the statement is bypassed. such as MATI in various programs. the keyword may contain [i].mat MATI[1]=?01. If an INCLUDE is present. the zone number will be checked against the zones in the INCLUDE list.mat. Turns off the ONLINE=Y switch Causes text to be written to the console. MATI[3]=?03. Then. thus eliminating the need to code FILEI. In most cases.mat . Typical keywords on a FILEI statement are NETI.mat. CONSOLE A CONSOLE statement is used to set certain switches relative to dynamic display of messages in the message area of the window.3 General Syntax Standard control statements filter before being processed.mat. MATI[2]=?02. The zonal filter will refer to either I (origin zone) or J (destination zone). NETI=??.mat.mat. 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. MATI. if there is an EXCLUDE. this would be the same as the above FILEI statement. or simulate certain required defaults. the program definition will clarify which. Most times the statement may begin with the keyword itself. if there is no FILEI statement. If [i] is not specified. If it fails the INCLUDE list specifications. all FILEI statements must be in the beginning of the control stream. When the program accepts FILEI vectored keywords. FILEI FILEI tells the program which input files to process. [1] is assumed. ?02. If it meets the EXCLUDE list specifications. ?03. FILEI MATI=?01. The exact format of the FILEI statement will vary between programs. In some programs. and ZDATI. Some FILEI keywords may allow sublevel keywords that are associated with the file keyword. the program will assume a default statement. the statement is bypassed. ” in the Cube Base Reference Guide. do not manually edit the file path or file name elements of the FILEI statements. “Application Manager.app file stores this information. Generally. If you use Application Manager. 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. as both the script file and the application’s .) FILEO FILEO is the counterpart to FILEI. If you use Application Manager. programs delay opening FILEI files until absolutely necessary. Abc=def . The exact format of the FILEO statement varies between programs. 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 . . as both the script file and the application’s . do not manually edit the file path or file name elements of the FILEO statements.General Syntax Standard control statements 3 because later control statements may reference variables that are to come directly from the files. . Hint: It is relatively easy to miscode FILEI statements by either omitting or including line delimiters. The documentation for each program will indicate where the FILEI statements are valid. some programs will generate an appropriate statement. .app file stores this information. 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. For example: FILEI MATI[1]=… MATI[2]=… MATI[5]=…. but it is wise to form the habit of placing all FILEI statements first in the control stream. (See Chapter 14. If there is no FILEO statement. it names the output files that the program writes. NOTE: Application Manager automatically writes all FILEO statements to the script file when you define content for output file boxes. you need not specify “GLOBAL.3 General Syntax Standard control statements Manager opens when you double-click an output file box. Usually this value is either 80 or 132 to accommodate most character printers. The value must be in the range 1032767. The value must be in the range 50-250. and (in some programs) 50 Cube Voyager Reference Guide . It only comes into play when certain reporting processes need to know the width of a print line. Resets the maximum number of characters to be printed on a single line. The keywords are trigger keywords. preclude insertion of page headers ID An ID statement is used to revise the page headings for each printed page. (See Chapter 14. PAGEWIDTH |KI| If these parameters are specified. 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 ID is specified as: ID=newid string. they remain in effect through subsequent programs until revised. The PAGExxxx values can also be set when Cube Voyager is initially launched from its menu. The ID is revised in one of two ways: with the ID statement.” in the Cube Base Reference Guide. so that the system knows when to start a new page with appropriate headers. “Application Manager.” GLOBAL keywords Keyword PAGEHEIGHT |KI| Description Resets the maximum number of lines on a page. The length of the ID text will be truncated to 60 characters. so it can form the report properly. Example PAGEHEIGHT=32767 .) GLOBAL Alters the size of a page on the standard print media. 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.5 COMP ID=’This is Pass’+str(PASS. 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.General Syntax Standard control statements 3 by a COMP ID=text expression. Because of this situation. This would most likely be used in a Cube Voyager loop situation: Example of Computing the ID LOOP PASS=1.0) RUN PGM= … ENDRUN ENDLOOP Example ID=This is the new Page Header Cube Voyager Reference Guide 51 . but the first page of the Highway section would contain it. That way. they cause the ID to be revised when the statement is processed in the Cube Voyager operations stack. In the COMP statement.2. the sign-on page for the application program will contain the desired ID. ID statements in Cube Voyager Pilot program are dynamic. it is suggested that ID statements be used before a RUN statement. the first page (sign-on) for the Matrix application will not contain the “this is the MATRIX ID” as its header. parts of 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). the sign-on IDs would be correct. When ID is specified as the destination in a COMP statement. If the RUN and ID statements were reversed. the ID can be computed. .... optionally. ELSEIF ( I>=0 & I<5 ) s2.. and the ELSE statement.. ELSE . For each IF statement. ELSE.. ELSE.. ENDIF For varying values of I. Example IF (I<0) s1. or ENDIF statement. ELSEIF (I==8) s3. The next statement executed is the one following the associated ENDIF statement..3 General Syntax Standard control statements IF . there must be a matching ENDIF later in the input stream. the statements would be executed as: Value of I -1 3 9 >9 Statements executed S1 S2 S3 S4 52 Cube Voyager Reference Guide ..). Between the IF and its matching ENDIF. 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.. ENDIF IF statements control the flow of user defined operations for those programs that provide for them.. Flow is outlined as: • IF/ELSEIF expression is true — The statements following the statement are executed until an ELSEIF. there may be any number of ELSEIF statements.. ELSEIF . and one ELSE statement. • IF/ELSEIF expression is false — The next statement to be executed is the next associated ELSEIF.. or ENDIF is encountered. ELSE s4. IF is followed by a selection expression enclosed within (.. The expression is evaluated and will result in a true or false condition.. Generated the ENDIF here ENDIF . This statement will be OK.VAR file with Cube Voyager Reference Guide 53 . Note: if a short IF is used and the statement appended to the statement is not acceptable in that context or is mis-structured.. . Cube Voyager updates the values in the . This is because the system can not always fully ascertain exactly what the problem is. cnter = cnter + 1 . then any time I is greater than 8. It is diagnosing an IF statement. in the example. This will fail.VAR.. ENDIF generated. 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. no statements between the IF and the ENDIF statement would be executed. This shortcut statement is provided to help reduce the amount of coding required. LOG Writes values to the log file PREFIX VAR Cube Voyager maintains a file called the log file. IF (j==3 & k==5) k=3. This statement will be OK cnter = cnter + 1 . the error diagnostic stated about the line may be somewhat confusing. So. there were no ELSE statement. Whenever a RUN statement is encountered. 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. because there is no associated IF. and this is OK ENDIF . IF ( i == 1) counter=0 IF ( i == zones) print . and this will continue it . the program automatically generates the required ENDIF. this will be an error.General Syntax Standard control statements 3 If. it has a filename with an extension of . but the appended statement has errors. so it doesn’t know exactly where to place the blame because it is diagnosing the IF statement at the time. IF (j==3 & k==5) k=3 . In such cases. VAR file can be accessed in two different ways: 1.TOTMW1@ .3 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. (HIGHWAY obtains a value from MATRIX): . The variables in the .VAR file can be retrieved by other Cube Voyager programs (including the Pilot program) in the same job. the value from the .) in other programs.TOTMW1 == 0) ABORT MSG=’Nothing in MW1’ RUN PGM=HIGHWAY . Examples may help to clarify this process.) in Cube Voyager. The values in the . X = @MATRIX. ENDRUN 54 Cube Voyager Reference Guide . (Cube Voyager tests the value from MATRIX): ZONES=5 MW[1] = 1 TOTMW1 = TOTMW1 + ROWSUM(1) LOG VAR=TOTMW1 ENDRUN IF (MATRIX.VAR file. the values can be retrieved by the use of the @…@ token process. 2. the variable can be accessed directly.VAR file. the program appends values to the .VAR is substituted directly into the control statement as it is read. and Cube Voyager retrieves the values when the program terminates. In the latter case. If a program is requested to LOG any values. RUN PGM=MATRIX . A LOG statement is used to have a program write values to the . The function returns a single value to the expression solver. the function will be Cube Voyager Reference Guide 55 .VAR=value. the correct number of arguments enclosed within parenthesis must follow it. This is scheduled for revision in a subsequent release of the system. LOG PREFIX=MATRIX1. will be written as MATRIX1.General Syntax Standard control statements 3 The records that are written to the file are written as PREFIX.VAR file. VAR |S| Example RUN PGM=MATRIX .VAR string values with embedded or trailing spaces at the first space when it reads the values. The statements are not dynamic. the program name will be used. but if a LOOKUP subkeyword follows the NAME. This string is added to the start of the names of all variables that follow PREFIX. In most cases. LOG keywords Keyword PREFIX |S| Description Sets the prefix of the logged variable(s). they are processed at the appropriate time by the program. The current version of Cube Voyager truncates . a lookup statement will define a single set of lookup data. If PREFIX is not specified. VAR=TOTMW1. Indicates which variables will have their values written to the . Lookup functions are referenced from within numerical expressions. When the function is referenced in an expression. AVEMW LOG VAR=GRANDTOTAL . This could be confusing if different applications of the same program log the same values. A lookup array is allocated and initialized with the data referenced by the LOOKUPI.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. FILE or R keywords. prior to their actual use. Indicates if the returned function value is to be the result of interpolating between rows in the lookup table. If a call to the function has more arguments than is required. This keyword must be specified. if the value is less than the lowest value in the table. meaning that there must be a direct match in the table. respectively. the result for the highest value in the table is returned. By default. the argument following the required arguments is the value that will be returned if the lookup fails for any reason.” in the Cube Base Reference Guide for information about this wizard. Data referenced by LOOKUPI or FILE keywords can be either in DBF. Note that versions prior to 1.5 did not return the extreme results of the data for low and high failure. FAIL[3] (default value is 0) is returned. they returned FAIL[1] and FAIL[2]. If FAIL[1-2] were not specified. Indicates if the program is to format and list the lookup table. the result for the lowest value in the table is returned. The default value is false. 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. FILE |F| Name of the file that contains the data to be associated with the function. they were set to 0. or delimited ASCII format. unless FAIL[1] is explicitly specified.3 General Syntax Standard control statements defined as one that requires at least two arguments (curve number and the value to be searched for). unless FAIL[2] is specified. See Chapter 12. R. 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. If the value is not found within the data. unless R or LOOKUPI is specified.5. INTERPOLATE |?| LIST |?| 56 Cube Voyager Reference Guide . MDB. This latter format is useful for entering friction factors for use in the Distribution program. If the value is greater than the highest value in the table. “Job Script Editor Window. and LOOKUPI are mutually exclusive. FILE. 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. LOOKUP[1]=1 RESULT=2. Note that FILE. The data formats supported for LOOKUPI= and FILE= when referencing data from an external file are ASCII and DBF. DBF. For example on the LOOKUP statement with NAME=FUNC1. 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. Used when data for one. a call to this function like X=FUNC1(1. ASCII data MUST be delimited with either spaces or commas. The returned value from the function would be placed in the variable X.General Syntax Standard control statements 3 LOOKUP keywords (continued) Keyword LOOKUPI Subkeyword Type |I| Description The # of the FILEI LOOKUPI[#] file where this LOOKUP statement is to obtain values. curves is to be obtained from a single data record. LOOKUPI and R are mutually exclusive.5) implies for curve 1 (first argument in the function call). and its value must be followed by RESULT=value. Name of the lookup function that the statement defines. 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. or more. NAME NAME LOOKUP |S| |S| NAME RESULT |S| NEAREST |?| Cube Voyager Reference Guide 57 . The values provided for the LOOKUP and RESULT keywords are either the field numbers in the input data (ASCII. Field number or name of the field from the data record that contains the result to be returned when the function is called. or MDB data) or the field names when the input data is in DBF or MDB format. and a value to be searched for). The use of the LOOKUP keyword implies that the call to the lookup function must contain at least two arguments (a curve number. The LOOKUP keyword must be indexed [1-n]. 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). if SETUPPER were true.3 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.. Optional variable that specifies the total number of entries in a LOOKUP array.. For example. 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. otherwise the return would be error. A single R= may specify the entire file. If R is specified. and it is to return a value based upon the lower of two ranges. a curve is entered with single values that begin at 1 and increment through 10 by 1. FILE. If INTERPOLATE were true.5 would fail. This option is useful when the data is input with single values. SETUPPER |?| SIZE |I| TOLERANCE |R| 58 Cube Voyager Reference Guide . 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.1 of Cube Voyager and TP+ systems. it is maintained to insure backward compatibility with previous versions of the software. and only comes into play for rows without both limits explicitly provided. SETUPPER takes precedence over INTERPOLATE. The value should be the number of resulting values to be searched for multiplied by the number of records. and the function can not find an exact match. As of v4. However. or multiple R= records may be entered. LOOKUPI and R are mutually exclusive. the result for 1 would be returned. the return value would be computed. A lookup for 1. The string values following R represent data records that are in the same format as the FILE records would be. Specifies that the function is to simulate an upper limit for a lookup row when only a single value is entered for the row. 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. In such cases. FILE or LOOKUPI may not be specified. Any number of R records can be entered. Each R value must be enclosed within single quote marks '.'. Specifies a tolerance to be applied to the lookup value. For either a single or double value function (functional call with 1 or 2 arguments) and additional argument value can be provided. Otherwise. If the LOOKUP subkeyword is in effect. Numbers not separated by dashes are entered as both the low and high limits of a row. FAIL[3] is returned. the call to the function requires at least two arguments: the lookup curve number and the lookup argument. The returned value is obtained by searching the lookup function data table for the lookup argument. the return value is set to FAIL[2]. The table is composed of rows of data. it is supplied a lookup argument within parenthesis. the return value is set to FAIL[3] unless INTERPOLATE is set to true. If two numbers are separated by a dash. If the function can not find a match for the lookup curve number. the return value is the result of interpolating between the high limit of the lower row and the low limit of the upper row. If the value is not found in any range. 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. 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. they form the low and high limits of a row. If the argument is less than the lowest value for the lookup number the return value is set to FAIL[1]. or commas or may be separate fields on a DBF file. and the function returns a value for the argument. but the upper limit of a Cube Voyager Reference Guide 59 .General Syntax Standard control statements 3 Lookup functions are referenced in numerical and selection expressions. Ranges may not overlap. If interpolation is used. the function requires only one argument: the lookup argument. If the argument is higher than the highest value. regardless of the value of INTERPOLATE. The first field on a record is the lookup result. This in effect gives you the ability to override the default FAIL values for specific situations. and the fields following it are the lookup values. When a function is referenced. 204 . 201. 301 102. . there is no row generated for that curve. The first field is the lookup result and the second field is the lookup value. but indicate there is no data point.) • 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 result for 2 would be obtained from the second row. 2. assume the following records: T. If either field number exceeds the number of fields on the record. If the argument matches a high limit of a row and the low limit of the next row. 202. The first two fields should be numeric fields but character fields are ok as long as the content can be converted to numerics. The data for each LOOKUP is obtained from the record according to the field numbers or names specified for the LOOKUP and RESULT keywords. 305 60 Cube Voyager Reference Guide . 1. If both fields exist. 303 104. or commas or may be separate fields on a DBF or MDB file. Blank fields are not treated as zeroes. When the lookup format designates multiple curves. 5. the result is obtained from the upper row. second row limits =2-3. special consideration is given to blank fields. otherwise the program will report a lookup input error. . v3 101. • Data records when LOOKUP subkeyword is used: Each data record may have any number of fields delimited by white space. v2. 302 103. v1. For example. 4. first row limits=1-2. 3.3 General Syntax Standard control statements row may be equal to the lower limit of the next row. (For example. they form a row with the low and high limits equal to the value from the LOOKUP field. V2. Example: Single value function COPY FILE=C:\LOOK1. or none). With space delimited records. The result for a lookup of T=3 in V2. Be aware that this situation exists only for comma delimited and dbf data. will depend upon the options of the LOOKUP statement (SETUPPER.V1.General Syntax Standard control statements 3 There will be no data points for T=3. Cube Voyager Reference Guide 61 . V3 would be blank. INTERPOLATE.DAT . space delimited records don’t have any way to designate null fields. the V2 curve will have points for T=1-2. and V3 will have points for T=1-3.V3. The V1 curve will have points for T=1-4. this is the data for the function 1 2 3 4-8 23 15 50 2 1 3 9-10 ENDCOPY LOOKUP NAME=DISTRICTS. T=5. and no more points appear on the record. FILE=C:\LOOK1. T=4.V2. the first empty field indicates the end of the record. and T=5.4.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. 5. DISTRICTS(50) results in 15. DISTRICTS(9) results in 3. the T=3 record would appear as “3 103 303”. which would be interpreted as points for V1 and V2. this may not be what was wanted.3 General Syntax Standard control statements Example: Single value function using LOOKUPI FILEI LOOKUP[1]=C:\LOOK1. To circumvent these potential problems. The limits of the curve would control this operation. . The lookup values can be set so that only trips within a certain item range can be distributed. .DAT LOOKUP NAME=DISTRICTS.01). or possibly zero. and the subsequent fields are the factors for the various purposes that are being distributed. for zone-to-zone movements for which there is no path (inaccessible). and the factors for the last records should also be the same. it is possible to have times that are below the minimum time and greater than the highest time. users may wish to have values for times that extend beyond the limits of the values entered. The time matrix might also have very large values. RESULT=3. The normal (default) process would return a 0 for those values (from the FAIL values). LOOKUP[1]=1. but there are zone-to-zone times that are greater than 100 minutes. Thus. Because the Cube Voyager distribution process is generic. . The factors of the two first records should be the same. . LOOKUP[2]=1. A similar situation would occur if the time were less than 1. 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. In most situations. For example: a table might have factors for times from 1 through 100. . if a time of 110 is encountered. and a record for the highest time value that you feel is reasonable. RESULT=2. a friction value of 0 will preclude distribution between the zones. This example illustrates that typical process. be sure to include a record for a very low time value (say 0. 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 . but greater than 0. LOOKUP NAME=FF. the friction factor obtained from the lookup would be the FAIL[2] value. but that may not be what is expected. R= '0. '1 1200 1000 800'.General Syntax Standard control statements 3 LOOKUP[3]=1.01 1 3 4 120 0.0. '4 100 100 100'. . . RESULT = 888 since 150 > highest value in field 1 FFX = FF(2.150.01 1200 1000 800'.01 1 3 4 5 120 0. RESULT=4. '3 300 500'. '5 50'.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 .1. '120 50 100 100' FFX = FF(1. RESULT = 750 /* to find 2 in field 1. FAIL=2000.888) . Curve 3 lookup value is in field 1 Result (FF) for curve 3 is in field 4 return 2000 if any lookup < 0. . .01 1 4 120 Upper Limit 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. you must interpolate between 1 and 3 then interpolate on same basis between 1000 and 500 in field 3 */ . INTERPOLATE=Y. RESULT = 300 FFX = FF(3.2) .01 1 3 4 120 0.01 1 3 4 5 120 0.3) . RESULT=2.a the value from ACRES LOOKUP[2]=TAZ.6389 0.4137 3.2) c2[cc]=CFAC(cc.3) ENDLOOP /* .name for this function LOOKUP[1]=TAZ. dimension user arrays to 5 array c0=5 cv=5 c2=5 . lookup county correction factors O&D Survey LOOKUP LOOKUPI=2 LIST=Y NAME=CFAC. RESULT=4. LOOKUP[3]=TAZ.5778 0. LOOKUP[2]=1. RESULT=ENROL_HS. . RESULT=SERV_JOBS. RESULT=3.2=OR. RESULT=POPULATION.cc . LOOKUP[1]=1. LOOKUP[9]=TAZ.cc = county code (1=LA. LOOKUP[6]=TAZ. RESULT=OTH_JOBS. LOOKUP[8]=TAZ.DBF" LOOKUP LOOKUPI=1. RESULT=ACRES. LOOKUP[3]=1.6767 0. LOOKUP[5]=1. LOOKUP[4]=TAZ. fill arrays for factors by county LOOP cc=1. RESULT=AGE_5_14.references the input DBF file NAME=TAZ.4108 3.5=VN) . example of use: v=TAZ(10. RESULT=ENROL_ELEM.DAT" cc=zi.6088 0.6759 3 0. RESULT=TOTAL_JOBS.2278 2 0.3 General Syntax Standard control statements Example: Double value function — LOOKUP with DBF LOOKUPI file FILEI LOOKUPI[1] = "C:\CUBETOWN\TAZ\TAZ.25) . RESULT=AGE_15_17. RESULT=6.4=SB. INTERPOLATE=F . INTERPOLATE =N .1. LOOKUP[5]=TAZ.external LOOKUPI file in this example 1 3.5665 0. .6505 0. 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.3=RV. LOOKUP[10]=TAZ.5 c0[cc]=CFAC(cc. LOOKUP[7]=TAZ. RESULT=RET_JOBS.DBF" FILEI LOOKUPI[1] = "C:\MTA_GEN\CFACS.6518 0.1) cv[cc]=CFAC(cc. RESULT=5. LOOKUP[4]=1.4132 3. .lookup a value in TAZ return .7070 3.5757 0.6642 64 Cube Voyager Reference Guide . Link the input production and attraction values to internal variables SETPA P[1]=ZI. LOOKUP[4]=TRVLTIME.PRN" FILEI ZDATI[1] = "TRIP ENDS.1.A2. FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=3. FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=4. Distribute trips using a standard gravity model formulation GRAVITY PURPOSE=1. FFACTORS=FRICTIONFACTORS ENDRUN Where the FRICTIONFACTOR.1. FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=2. LOS=MW[20]. RESULT=SCHOOL. A[2]=ZI. MAXRMSE=5 . Set a maximum number of iterations and convergence criterion PARAMETERS MAXITERS=99.DBF" FILEO MATO[1] = "PERSON TRIP TABLE. LOS=MW[20].1.P4.DBF file contains: Cube Voyager Reference Guide 65 . MO=1-4.P1.1.’EI_Trips’ .1.1.A4 . LOOKUP[2]=TRVLTIME.1.'NonHome_Based'.MAT" FILEI LOOKUPI[1] = "FRICTIONFACTORS. Put the friction factors into a LOOKUP for distribution LOOKUP LOOKUPI=1. NAME='Home_Based'.MAT". NAME=FRICTIONFACTORS. P[4]=ZI. LOS=MW[20].'School'.P2. Put the travel time matrix into a working matrix for distribution MW[20]=MI.A3. LOS=MW[20].General Syntax Standard control statements 3 */ Example: Double value function — Using LOOKUP with DBF data in a trip Distribution application RUN PGM=DISTRIBUTION PRNFILE="DISTRIBUTION. RESULT=NONHOME. A[3]=ZI. RESULT=HOMEBASED.TIME . LOOKUP[1]=TRVLTIME.DBF" FILEI MATI[1] = "TRAVEL TIMES.1.P3.1.A1. A[4]=ZI. P[2]=ZI. INTERPOLATE=T . RESULT=EXT_INT. LOOKUP[3]=TRVLTIME. A[1]=ZI. P[3]=ZI. You might need to add a “\n” to the end of the file if you concatenate the file with another file. This default format is effective until the program reads the next CFORM value. The program writes each formatted list to one record. If not specified.3 General Syntax Standard control statements PRINT Formats data items and writes them as a single line to the standard printed output. 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. Flag indicating whether to print the output file in CSV format (with commas between the LIST items). the program writes only to the specified file unless subkeyword PRINT is set to T. CSV |?| Optional. Default value is 0. File where the program writes the formatted list. or both. Optional. See “Defining a character print format” on page 71. If specified. The program prints one line for each PRINT statement. specified with the LIST keyword. Default format for subsequently appearing character strings. a file. 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. the program writes the standard printed output file. 66 Cube Voyager Reference Guide . Explicit formats defined for particular items take precedence. Thus. except for literal values. the endof-file character is at the end of the last record. REWIND is dynamic. F — Write to the current position in the file. you can control the rewinding on each PRINT statement. 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. Flag indicating whether to overwrite or append to the specified file. Explicit formats defined for particular items take precedence. Default format for subsequently appearing numbers specified with the LIST keyword. FILE PRINT |?| Optional. Default value is 10. FORM |S| Optional. Program overwrites previous contents. Default value is F.2.General Syntax Standard control statements 3 PRINT keywords (continued) Keyword FILE Subkeyword APPEND |?| Description Optional. Cube Voyager Reference Guide 67 . This default format is effective until the program reads the next FORM value. Flag indicating whether the program repositions to the start of the file before writing contents. Optional. Default value is F. even if other statements set APPEND to F. F — Overwrite the existing file when writing the formatted list. Possible values: • • T — Append the formatted list to the specified file. then all PRINT statements executed at that step will append to that file. NOTE: If set to T for a file at least once in a step. Flag indicating whether to write record to standard printed output in addition to specified file. therefore. See “Defining a numeric print format” on page 70. Possible values: • • T — Reposition to start of file before writing formatted list. For example: I. a literal string may contain the newline character string ("\n" . I(L). strings. Subscripts may be constants. the program will supply one. ITEM1(6). See “Defining a numeric print format” on page 70 and “Defining a character print format” on page 71. As long as a PRINT statement has at least one LIST item. 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. 'i='(8R). (sqrt(4))(8C). depending on the variable. For example. If you do not specify a subscript. To assign an explicit format to a particular item in the list. place the format in parentheses next to the item. Append appropriate subscripts to any array and matrix variables in the list. List of items (variables. Because the special control is case sensitive and directory folder names are not. You can override the automatic newline character by making the first LIST item a literal string that begins with the “\\” characters. where J is the current value of J. NOTE: Because special characters are treated as these special controls. to generate a new line at that location (the \n will not be printed). the program automatically inserts a newline character prior to the first item. For example: P[i*3-1]. and expressions) to format and write to a printed line. NOTE: MW[n] normally implies MW[n][J]. lowercase). program. and the printing will continue from the current line position. variables. The \\ will not be printed. Specify no more than 500 items. problems can arise when printing strings for a system path due to the "\" character. J. you can avoid this issue by using LIST="C:\N2020\output". or valid expressions. The format only applies to that item. 'abcde'.3 General Syntax Standard control statements PRINT keywords (continued) Keyword LIST Subkeyword |KS| Description Optional. 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. and phase. Enclose expressions in parentheses. 68 Cube Voyager Reference Guide . JLOOP_J. J. REWIND=T • Interpret sqrt(6) as a variable “sqrt” with form=6 Cube Voyager Reference Guide 69 .0CDLRS LIST=I.002. you might prefer to form character variables using the string functions of a COMP character expression and include those variables in the list. TOTAL2. J. Flag indicating whether the program repositions to the start of the file before writing contents. Examples • Report a mixture of numeric and character variables. TOTAL1. Flag that indicates whether to write record to standard printed output in addition to specified PRINTO file. REWIND is dynamic. TOTAL3 FILE=PRINTFIL.3). TOTAL2 FILE=PRINTFIL. therefore.2CS) FORM=LRCD. LIST=N. TOTAL(6. PRINT FORM=0 LIST=I.001. 'ABCDE'(6. |I| PRINT |?| Optional. • Use LIST keyword without the control statement name. F — Write to the current position in the 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. Program overwrites previous contents. Optional. Default value is F. Possible values: • • T — Reposition to start of file before writing formatted list. The string functions might provide some flexibility that is better suited to the specific task. LIST= I(6) J(6) TOTAL1.General Syntax Standard control statements 3 PRINT keywords (continued) Keyword LIST (continued) Subkeyword Description In some cases. PRINT FORM=6. Optional. Index number of the FILEO PRINTO file where the program writes this output. APPEND=T • Output to file and rewind file at the end. you can control the rewinding on each PRINT statement. MW[1][1]. If there are more post-decimal digits than this • • • • 70 Cube Voyager Reference Guide . I. For either keyword. ' J='.’DISTANCE’ PRINTO=1 PRINT CSV=T LIST=I(6. D — Display zero-value numbers as a pair of right-justified dashes.1E. d — Number of digits printed after the decimal point.2).dBCDELRST where: • • w — Total field width. Field width must be at least 9. which prints as +1.’TIME’. if both are coded.2E+123.0L). The smallest format is 9. If you specify a value greater than 30. B overrides D.’J’. J. The program sets d to 0 if the format begins with w and you do not specify d. E — Display numbers in scientific format. (sqrt(6)) ' • Output directly to CSV format FILEO PRINTO[1]=c:\data\mydata. you code numeric print formats as: w. MW[1][3].2L) PRINTO=1 Defining a numeric print format You can specify numeric print formats with the FORM keyword or the LIST keyword. the program uses 15 digits after the decimal point. B — Display zero-value numbers as blanks. MW[1]='. the program uses a width of 30. Maximum value is 30.MW[1](8. time+dist/sqrt(xyz). MW[1][2].MW[3](5. the program uses the maximum decimal (w-8).MW[2](8. C — Insert commas into numbers. Maximum value is 15.J(6. If you set d to 0. otherwise the program resets the format to the default value (10.’COST’.0L). If you specify a value greater than 15.4L).3 General Syntax Standard control statements PRINT FORM=LRS LIST= 'I ='.4L).csv If (I=1) PRINT CSV=T LIST=’I’. the program reformats with scientific notation (1E+ppp). Normally. the program ignores other format codes when you specify E. Citilabs recommends that you use a varying length format unless you must align reported values. The BCDELRST characters (case insensitive) may be in any order. • • • All characters are optional. • L — Trim numbers on the left and print the result beginning with the left-most digit.General Syntax Standard control statements 3 maximum value. finally. Defining a character print format You can specify character print formats with the CFORM keyword or the LIST keyword. T — Truncate numbers on the left if they cannot fit the field width. the program formats such numbers with all asterisks. the program drops commas. you code character print formats as: w. FORM=16. The result will be left justified and only as long as required. The program attempts to accommodate fixed formats: When values do not fit the specified field width. then the program reduces the post-decimal digits to w-8. otherwise the program truncates. If printing an unknown range of values. specify a width adequate to accommodate all possible ranges. S — Insert a space before the digits of any numbers formatted with L. The program ignores characters other than B and D specified with E. if w and d are specified.d. For either keyword. do not specify L.dCDBTLR Cube Voyager Reference Guide 71 .4LRS is probably adequate. For delimited output. The program replaces zeros after normal formatting and removes decimal point if there is no trailing 0. but must follow w. When printing fixed fields. You may specify B or D along with E. and then reduces the number of decimal places. R — Replace a number’s trailing 0s (right side of decimal point) with spaces. if possible. R. and S. the program truncates. • • • • • • All characters are optional. Citilabs recommends using a varying length format unless you must align reported values. Specify d anywhere in the format string. the program uses the last value. If a format string specifies multiple w values. D — Print dashes (-) in the d characters preceding the field. C — Center-justify text item. delete trailing spaces. If L is specified. any number not preceded by a period specifies w. C overrides L or R. The CDBTLR characters (case insensitive) may be in any order. If a format string specifies multiple d values. T — Trim leading or trailing spaces from text item. any digit preceded by a period specifies d. If R is specified. B — Replace blanks with underscore characters (_). R — Right-justify text item (truncating beginning characters if length exceeds field width).3 General Syntax Standard control statements where: • w — Total field width. When text does not fit the specified field width. The default value is 0. w must be wide enough to accommodate the string. the program uses the last value. • d — Number of leading spaces printed (or dashes. The program attempts to accommodate fixed formats. NOTE: If the format specifies L. Valid values range from 0 through 15. if D specified). 72 Cube Voyager Reference Guide . If both L and R are specified. Set to 0 to indicate that the field width depends on the string length. delete leading spaces. Program applies T first. L — Left-justify text item. Specify w anywhere in the format string. delete leading and trailing spaces and center-justify text item. (The L in the format value triggers varying-formatted numbers separated by a single space.5LRD) provides efficient reporting while maintaining precision.General Syntax Standard control statements 3 PRINTROW Formats and prints all cells or selected cells of a matrix row to the main print file. Default format for row values. Possible values: • • T — Begin every printed line with a zone number ending in 1. 8 FORM=LRD TITLE='form=LRD' PRINTROW MW=1-21 FORM=8 BASE1=Y MAXPERLINE=10 FORM |S| Optional. You must code all on a PRINTROW statement. set FORM to 7D.5LRD The default value (20. See “Defining a numeric print format” on page 70. BASE1 has no effect. MAXPERLINE takes precedence over BASE1: if MAXPERLINE is specified and is not modular ten. Cube Voyager Reference Guide 73 . For printing traditional integer boxes. use this statement judiciously. providing zone distinction. Flag indicating row format when using non-varying print format (that is. For example: PRINTROW MW=1-2. See also “PRINT” on page 66.) Three spaces precede zone values ending in 1. None of the PRINTROW keywords are “trigger” keys. Default value is 20. Row formatting can be quite voluminous. PRINTROW keywords Keyword BASE1 |?| Description Optional. F — Begin each printed line with appropriate zone number based on FORM and page width. FORM does not contain L). even if printing multiple MWs. By default. Default value is no work matrices. By default..3 through 5. List of work matrices to print. Example PRINTROW mw=1-2. regardless of specified order. Delimit each number or pair with a comma. and setting MAXPERLINE to some integral of 10. the program prints no title. setting BASE1 to true. Title printed at the beginning of each MW. program allows any number of values to be printed on a line. 10.3 General Syntax Standard control statements PRINTROW keywords (continued) Keyword J |IP| Description Optional.").8 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10 74 Cube Voyager Reference Guide .12-20 selects zones 1. For example J=1. program ignores page width. MAXPERLINE |I| Optional.') or literal marks (". TITLE |S| Optional. 3-10. and 12 through 20 for printing. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. The program truncates titles longer than fourteen characters. 13 selects work matrices 1. Default value is all zones.10. Valid values range from 1 to the number of zones. Delimit each number or pair with a comma. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range.3-5. and 13 for printing. List of zone numbers formatted for printing..3 through 10. Citilabs suggests specifying FORM without the LD. Maximum number of columns printed on a line. MW |IP| Optional. If MAXPERLINE is specified. Program sets excluded zones (those not listed) to zero. For example MW=1. provided line length does not exceed the standard page width.. Program prints matrices in ascending order.. You may specify only one title per PRINTROW statement. Enclose the value within quotes ('. For neat-appearing reports. Replacements are done in the left to right order as specified in the READ statement. The replacement process is designed to not allow a replacement string to replace an earlier replacement. When the end of file is encountered on that file. There is no specific limit to the length and number of replacement strings.. If either oldstring or newstring contains any special characters it must be enclosed with '. the string is replaced with newstring. . and the scan is continued.. Character string that will replace oldstring in the records in FILE that contain oldstring.'. oldstring=newstring. it will be replaced directly. The format is: READ FILE=filename.General Syntax Standard control statements 3 READ Switches reading of control statements to a different file. A nested READ may not point to a file that is already in the nest. Example READ FILE=BUSLINES. It is suggested that strings always be enclosed within '. ‘MODE=5’ = ‘MODE=3’ Cube Voyager Reference Guide 75 . Character string (not case sensitive) that is to be replaced by newstring.... As each record is read from the file. oldstring=newstring. If it does. newstring oldstring READ statements can be nested up to five levels. but it is not mandatory.. it is scanned to see if oldstring exists in it.. Newstring is case sensitive. READ keywords Keyword FILE Description File to be read. reading of control statements will continue with the statement following this READ statement.'. If a leading + sign is used. Unsigned arrays are carried along in parallel with the sorted records. NUMRECS |S| Specifies the number of records to sort. All names must be declared in an ARRAY statement or as a DBI AUTOARRAY name. same as above.3 General Syntax Standard control statements SORT Sorts an array. Example 1 SORT ARRAY=A. or an integer number. and a “–” means descending.-C. The SORT statement would be SORT ARRAY=-HH. carry B & C along with A SORT ARRAY=-A. sort on descending on A.B. For example. descending C SORT ARRAY=-A. A “+” means ascending. the sign and name must be enclosed within quotes (for example. Signs need not be specified. '+myarray').C . but if they are.ZONENO. It may not exceed the length of the arrays. two arrays would be required: ZONENO and HH. a signed array may not follow an array without a sign.C .'+B'. it may be either the name of a variable. 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). Sort on ascending values in A. If there is no sign for the first name. All the arrays in a SORT statement must be declared with the same size. ascending B. ascending is assumed.… NUMRECS=x SORT keywords Keyword ARRAY |S| Description Names of the arrays to be sorted.'+C' . The format is: SORT ARRAY=name. *** ERROR *** signed name (+C) follows unsigned (B) 76 Cube Voyager Reference Guide . This would sort the HH array in a descending order and keep the ZONENO array records parallel to it. but sort order for A is descending SORT ARRAY=-A. or series of arrays. name.D. if one wanted to see a sorted listing of the number of households per zone.E .B.B. INCOME[I] . BN=LINKS. */ PHASE=SUMMARY SORT ARRAY=-VMT. ZONENO[I] = I HH[I] = ZI. Generation) ARRAY ZONENO=ZONES. Fratar. .BN.HH[I] INCOME[I] = ZI.2c) ENDLOOP ENDPHASE Cube Voyager Reference Guide 77 .1. AN.VMT[_K](10.General Syntax Standard control statements 3 Example 2 (Matrix. INCOME=ZONES . INCOME[J]. NUMRECS=_L LOOP _K=1. 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. Distribution. HH=ZONES. .-HH. VMT=LINKS .30 .BN[_K](6). the number of entries will be less than the original number of links. HH[J] ENDJLOOP Example 3 (Network) ARRAY AN=LINKS. LIST=ZONENO[J]. SORT ARRAY=-INCOME.ZONENO LIST=’ Zone Income HHs’ JLOOP PRINT FORM=8. only want to see the highest 30 LIST=AN[_K](6).1. 3 General Syntax Standard control statements 78 Cube Voyager Reference Guide . Cube Voyager Reference Guide Cube Voyager Reference Guide 79 . Topics include: • • • Using Pilot program Control statements Examples 80 Cube Voyager Reference Guide . the basic driver for Cube Voyager application programs.4 Pilot Program 4 Pilot Program This chapter describes the Pilot program. PRJ. or indicates strange filenames or default parameters. Pilot can check the return codes of the individual programs. and even perform complex mathematical computations.. Through the use of loops and conditional branching. this file will be deleted.Pilot Program Using Pilot program 4 Using Pilot program The Pilot program is the basic driver for Cube Voyager application programs.@) Output files A project file. the remedy is to Cube Voyager Reference Guide 81 . is maintained (generated. pppp. if necessary) in the working sub-directory. The variable file will contain a list of all the variables and their values that are in the Vars array when the program terminates. the VAR file is renamed to pppp. invoke system commands.VAR. and those that might be run simultaneously in a separate thread in a multitasking environment. Otherwise.% and @. most likely the pppp. there will be only one VAR file for each prefix.. Most users will use Pilot only to invoke the individual programs in the order desired.PRJ file has been corrupted. but it is also a calculator by itself.. This section discusses: • • • Output files Process Statement tokens (%. If there are no specific Vars to be written. The nnnn is a sequential number assigned in conjunction with data obtained from the project file. respectively. In such cases. It contains certain values that help the program to establish unique project identifications between applications that are run at separate times. The file names are ppppnnnn with extensions of PRN and VAR. The pppp portion of the name is the project prefix obtained from the P argument on the command line. NOTE: If Cube Voyager does not seem to sign on correctly.. Consequently. Each application run generates a print and a variable file. either for its own use or to pass on to the application programs. application programs can be run in any order desired. Typically.PRJ. the process may be repeated with some adjustments in the input data. In the simple case. If the results of the analysis are not satisfactory. Build paths. and add distribution parameters (terminal and intrazonal times). There will need to be “recursive” applications that are driven by intermediate results. or just selected portions of it. After the application of a series of programs to accomplish this has been completed.4 Pilot Program Using Pilot program delete the pppp. the process could be looped until speeds come into a reasonable 82 Cube Voyager Reference Guide . or parameters. But there are disadvantages to that approach (not discussed in this document). this process could be written into a large program. and auto occupancy. Ideally. and decide if the process needs to be rerun with adjustments. and it is possible for the user to confuse the two and store Viper configuration information into a Cube Voyager . Adjust person trip matrices to account for non-model characteristics. Distribute trip ends according to the paths and user functions.PRJ files. 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. you would have to verify the results. Cube also uses . Assign trips to the network. and the process is resubmitted. if the final speeds are not acceptable. and handled as such.PRJ file and restart the process. 4. and vice versa. Process Recent changes in recommended planning analysis dictate that the simple serial processing may become inadequate. The decision process usually will include some type of numerical analysis. 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. 3. 2. the repeat process is just that: the input data and/or parameters are modified. or if the results are satisfactory. peak period factors. or until it is decided that a proper balance can not be achieved. The program begins by reading and editing the Cube Voyager specific statements. Typical flow control statements are: GOTO :LABEL ONRUNERRORGOTO CLEARERROR LOOP BREAK CONTINUE ENDLOOP IF ELSEIF ELSE ENDIF EXIT Cube Voyager Reference Guide 83 . When all Cube Voyager statements have been edited for basic syntax.Pilot Program Using Pilot program 4 balance. program. Typical control statements are: COMP (often invoked by simply: var = ) • Flow control statements — Help to determine which statement is to be performed next. and system statements. Stack statements fall into several categories: • Computational statements — Cause variable values to be updated. and have been stored in the control stack. Each stack statement is executed. flow control. When the end of the stack or an EXIT statement is reached. It then begins processing the control stack at the beginning. The non-Cube Voyager statements (system statements. As the user learns more of its capabilities. The list is stored in the Vars array. the program terminates. he/she will find that he/she can control the process in many innovative ways. The input is comprised of computational. 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. and flow branches to the next appropriate stack statement. and the statements that follow a RUN statement until its terminating statement) are not edited by Cube Voyager. That is only a simple portion of the capabilities of Cube Voyager. To continue. and is at least two characters long. it can not be cleared by setting RETURNCODE=. if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate label statement in the script. they will function within Windows applications. The CLEARERROR statement is used to reset the internal return code. When a “RUN PGM=program” statement is executed. If RETURNCODE is greater than 1. the user will issue a message. 2 (Fatal messages). 1 (Warning messages). Example *COPY *. However. 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. Typically. or 3 (program aborted). or subsequent tests of the run status may cause termination. system statements are used only in pure DOS applications. this value is stored in a variable named RETURNCODE.DAT d: 84 Cube Voyager Reference Guide . but their use is not recommended.4 Pilot Program Using Pilot program The program provides the user with the capability to react to fatal returns from Citilabs’ programs. A program statement always begins with: RUN PGM= • System statements — Program initiates an operating-system command. the run is automatically terminated. At the labeled statement. Typically. A system statement is one in which the first field begins with a *. • Program statements — Execute a Cube Voyager program. and possibly continue the run. the user will have to clear the internal RETURNCODE variable. the run will continue at the labeled statement if the return code is 2. the program sets a return code that indicates what type of messages it issued. the user can further control what is to happen with the run. The return code is either 0 (No messages). . the token is unchanged (the variable name is case insensitive). or different input files.@ token. The program can update the file when it terminates. (NOTE: the Cube Voyager Reference Guide 85 .Pilot Program Using Pilot program 4 Warning: Do NOT use a system statement to initiate another Cube Voyager application.@. it is provided access to the .. but there might be times where it can be quite helpful..%...VAR file with the current values from the Cube Voyager Vars array. The @.% and @.. It should be noted that the environment is a copy of the environment prior to the execution of Cube Voyager.. the series should be repeated. 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.. the user can cause the stack to be processed in almost any order desired. There are two types of tokens: %. If the program reads a control statements that contains a @. (NOTE: Any *SET statements will NOT alter the environment. Another example could be the repeated application of a program with a slightly different set of parameters. but the Vars array is not updated until Cube Voyager is back in control. If a Cube Voyager control statement contains a %..@ tokens are processed only when the statement is being processed by a program called via the RUN PGM= statement.. When a program is called.% and @. If the adjusted speeds from the assignment program differ too much from the speeds that were used in the distribution process. the token is replaced by the value of the operating system (OS) environment variable between the % signs. it is suggested that *SET statements not be used. With the capabilities of these statements.% token. the token is replaced by the value of the file variable named between the @ signs...... If there is no matching variable name in the environment. It is up to the user to control the flow. Statement tokens (%.) There is not much use for %.@) Any statement may contain tokens for substitution. %MAXLOOP% RUN PGM=program ID = This is the @loop_cnt@ out of %MAXLOOP% ENDRUN ENDLOOP The READ statement (see Chapter 3. READ statements are recognized in all Cube Voyager applications. then the sample could be coded as: LOOP loop_cnt=1. To keep it entirely generic.) If the named variable does not exist in the Vars file. “General Syntax”) also has capabilities for setting replacement strings in control statements. a subsequent change to that variable will not alter the value as read. MAXLOOP could be set into the environment (SET MAXLOOP=20) prior to launching Cube Voyager. Example MAX_LOOP = 20 LOOP loop_cnt=1. the token is unchanged.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. 86 Cube Voyager Reference Guide .4 Pilot Program Using Pilot program token is replaced literally at the time the program reads the statement. ..Pilot Program Control statements 4 Control statements This section describes the control statements available in the Cube Voyager Pilot program.. ELSEIF ... 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 ...... ENDLOOP NEWPAGE ONRUNERRORGOTO PARAMETERS PRINT PROMPT REPORT RUN .. ENDIF LOOP . ENDCOPY DOWNLOAD EXIT FILEI FILEO GOTO IF . ELSE .. Control statement *command BREAK CLEARERROR COMP CONTINUE COPY . flow immediately branches to the statement following the appropriate ENDLOOP statement. even if they are unsuccessful. The '**' approach will be appropriate if the command requires some interaction with the user.4 Pilot Program Control statements *command A statement whose first field begins with a *. is considered as a command for the operating system.TMP **IF EXIST OLD. even if one of the filenames is illegitimate. It must be within a LOOP block. Cube Voyager will invoke the COMSPEC processor to execute the command. for example. This prevents disruption of the display. If it is required that the command window appear on the display. It is the user’s responsibility to test ReturnCode.NET Or: **DEL ABCD*.NET DEL OLD. use the alternate **command rather than *command. NOTE: The *command will be executed in a minimized command window. and is more than 2 characters long. The contents of the LOOP variable are not altered. The command will return a code that will be stored in the ReturnCode variable. 88 Cube Voyager Reference Guide . allowing other tasks to be performed more comfortably while the script is running. It should be noted that some system commands return 0.NET BREAK BREAK can be used to break out of a LOOP ENDLOOP block. since Cube Voyager does not know the meaning of the return codes. Example *DEL ABCD*.TMP *IF EXIST OLD. or perhaps if it displays some progress which the user always wants to be able to view. When BREAK is encountered.NET DEL OLD. For example: “COPY source dest” will return a 0. '**pause' rather than '*pause'. Example ONRUNERRORGOTO = 'MYERROR' :STEP1 RUN PGM=MATRIX ENDRUN .At this point control will transfer to :MYERROR :STEP2 RUN PGM=…. When the statement is encountered.1. It is then the user’s responsibility to set those values with the keywords.Pilot Program Control statements 4 Example LOOP i=1. and the program detects that it is in an error recovery process set by ONRUNERRORGOTO. If the value is True (1). it automatically resets the internal error code value to 1 and the resume switch to false. get out of loop ENDIF ENDLOOP CLEARERROR CODE RESUME The CLEARERROR statement is used primarily in conjunction with the variable ONRUNERRORGOTO. control will switch to the statement following the RUN statement that caused control to switch to the recovery process.3 IF (condition) statements ELSE BREAK . ENDRUN Cube Voyager Reference Guide 89 . Can be a value of 0. CLEARERROR keywords Keyword CODE RESUME |I| |?| Description Internal error code is reset to this value. in the middle of a complicated loop.") within its name as numeric. To avoid this problem.' or text functions are in the expression). It is not permissible to change the mode of a variable during an application. Results can be either numeric or character strings (obtained when literal text '. 90 Cube Voyager Reference Guide . Cube Voyager does not know the mode of the variable and can not edit it prior to actual application. to ensure that an edit can be made prior to beginning processing. it must have appeared as a var= in a statement prior to the expression. the program had to abort because it couldn’t find a variable at that time. The program is designed with this check. Cube Voyager automatically assumes any variable that contains a dot (". if.. etc. It could be a big waste of time.4 Pilot Program Control statements :STEP3 RUN PGM= ENDRUN :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 RESUME=T . control will return to :Step2 COMP var=expression ID=expression Lambda=expression. • Var is the variable that is to have a new value computed for it.. At this point. A variable must be defined before it can be used within an expression. However. this causes a problem with using variables returned from a Cube Voyager program invoked by the RUN PGM= statement. COMP statements compute numeric values and store the value into the var on the left side of the equals sign. If it does not exist in the Vars array. If the variable matches a name in the Vars array. it is added as a new variable that can be referenced in subsequent control statements. the result will be updated after the COMP is completed. then the resulting character string is copied to the system ID area. a Lambda between 0 and 1 will be found.0) Divide the difference between min and max into equal intervals.000001. When the interval size is within tolerance. This is not a perfect solution. If the result of the expression is not numeric.0 in hopes of determining a Lambda that will result in a value of 0. • Lambda is a special case variable. and it is an error.Pilot Program Control statements 4 • ID is a special case variable that allows the user to compute a new ID. repeat steps 2-5. but if the expression is appropriate (does not contain any transverse slopes. the program solves the expression for various values of Lambda between 0 and 1. For obvious reasons. the solution is ambiguous. If the interval size is not within the accepted tolerance. Solve for all the interval points between min and max. and crosses zero one time). ID then becomes a working variable. When this form is specified. Store the results into Lambda. perform a straight line interpolation to zero. will always result in Lambda = 0. Find the interval that surrounds 0. it is an error. The current process works on a bisecting principal for developing the test ranges and uses an tolerance interval of 0. In any event. If more than one interval surrounds 0. ID may not be the first keyword on a COMP statement. an expression that contains Lambda as an expression multiplier without any other terms. Reset the min and max Lambdas to the interval points that contain 0. if none do. Because of the potential conflict with the Cube Voyager system ID control statement. A division by Lambda will cause program failure when Lambda is tested for 0. Cube Voyager Reference Guide 91 . The logic for searching is as follows: Set a min and max Lambda (0 and 1. and Lambda must also be a variable within the expression. Example COMP i=matrix. If there is no matching ENDCOPY.3. but not including. COMP ID='This is a new ID for loop' + str(loop_cntr. its matching ENDCOPY statement are copied. When CONTINUE is processed flow immediately branches to the ENDLOOP statement in a LOOP ENDLOOP block. jump to ENDLOOP ENDIF ENDLOOP COPY .time_to_cbd/100 + sqrt(loop) i=3...lambda * . It must be within a LOOP block. ijk=1*100+j*10 + k Lambda = 1. it may begin directly with var=. bypassing all intermediate statements. Example LOOP i=1.2 . k=9..4 Pilot Program Control statements The statement need not have COMP. All the records following the COPY statement. The actual COPY takes place when the COPY statement is processed (it can be bypassed or repeated). the end of file is considered as the ENDCOPY. j=6. If there are any COPY or ENDCOPY statements between this COPY statement and its 92 Cube Voyager Reference Guide .3 IF (condition) statements ELSE CONTINUE .. ENDCOPY FILE=filename Copies records from the input file to a specified file. The copied records and the ENDCOPY are not processed by Cube Voyager. up to.0) CONTINUE Jumps to the end of a loop. For that reason..).*/ %. they are copied as a data records to the designated file.. will be copied to temp2 COPY FILE=temp3 . copy lookup file for HIGHWAY . it may be better to place most COPY statements near the beginning of the input file. FILE=filename Example COPY FILE=temp1.. " " " " " . an IF statement can be used to test the results. " " " " " ENDCOPY " " " " " ENDCOPY signals that the prior record was last IF (ReturnCode==255) . The primary use of COPY is to allow the user to include small data files within the input file. If the COPY fails.. Must be an acceptable name for the operating system. the error is not diagnosed until the COPY statement is actually processed.. DOWNLOAD URL FILEO CLEARFILEO Cube Voyager Reference Guide 93 . The copy process does not scan the records for special features (/*. If there is no filename. COPY and ENDCOPY keyword Keyword Description |F| Name of the file onto which the records are to be copied. ENDCOPY COPY FILE=temp2 ..% etc.. ReturnCode is set to 255. so that they can be always be associated directly with the control statements.copy with imbedded COPY .Pilot Program Control statements 4 ENDCOPY.. or the filename is invalid. ... no matter where it is specified in the script.dat' URL |S| URL for the target file to download. Example: URL= 'ftp://www. Example IF (expression) EXIT FILEI NOTE: See “FILEI” on page 48 for general information about FILEI and for important limitations when using Application Manager.dat' The site address component (ftp://www.com) is not case sensitive but the path and filename component is (/outgoing/yourfile.dat).citilabs. This statement is executed before any step is run. DOWNLOAD keywords Keyword CLEARFILEO |?| Description <1> is a switch to indicate if the local file should be cleared prior to beginning the download.4 Pilot Program Control statements Downloads a file from the internet from the specified URL. EXIT Terminates the program.com/outgoing/yourfile. Specifies an input file for Pilot variable initialization. 94 Cube Voyager Reference Guide . 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.citilabs. Example: 'C:\CITIDOWNLOADS\myfile. If not specified. VARI |KF| Specifies the name of the file which is to be read to initialize variables. A var output file will always be written at the termination of the application. The data extracted from the file are stored in the Vars array. You must index LOOKUPI. Each record from the file contains two fields: a variable name. VARI is not used. with. and its value.Pilot Program Control statements 4 VARI=filename FILEI keywords Keyword LOOKUPI |FKV999| Description Name of file containing records for a lookup function implemented with the LOOKUP control statement. Normally.VAR FILEO Specifies an output file for the PRINT PRINTO capability when printing from Pilot. it is used only if there are many variables to be initialized. 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 . If duplicate variables are encountered. an = sign. or without. The names may be any reasonable variable names. it may begin directly with VARI. Equivalent to the FILE keyword of the LOOKUP control statement. The fields may be separated by any number of space(s). Example VARI=XXXX. no file is read. This could be the case if the application is the continuation of a previous application. the latest one read prevails. The statement need not contain the FILEI control word. Example FILEO PRINTO[1] = "C:\Data\My File.DIFF(8.MAT/Y GOTO Jumps immediately to a named statement.4 Pilot Program Control statements The statement need not contain the FILEO control word. all PRINTO index numbers must be unique throughout the script.CSV" IF (L1=1) PRINT CSV=T LIST='ITER'.” Each GOTO statement must have an associated :label statement.2L). FORM=L. PRINTO=1 ELSE PRINT CSV=T. NOTE: When processing the first step. LIST=L1. you must ensure that the index numbers used do not overlap with prior PRINTO indices from prior Pilot steps. it may begin directly with PRINTO. Example 1 GOTO hwybuild GOTO :hwybuild 96 Cube Voyager Reference Guide . the Pilot program opens all the PRINTO files specified in any script.'P_DIFF'.mat LAST. GOTO label When GOTO is processed. flow immediately branches to the target statement.'DIFF'. Use care when the :label statement is within a different IF or LOOP block. PRINTO=1 ENDIF IF (ABS(CONV. statements intended to create files in folders that do not already exist will fail. Note.05 & L1>1) BREAK *COPY Trips_by_Mode. The target statement must begin with a semicolon (:).P_DIFF(6. When adding a Pilot box in Application Manager and linking a file to the PRINTO file box. Therefore.0L).P_DIFF)<0. named “:label.CONV.CONV. ... ENDLOOP blocks.. You may append the following control statements to a single IF statement: • • • • • BREAK COMP CONTINUE EXIT GOTO Example . ELSE .) in their name as numeric variables. ELSEIF . Single IF examples: Cube Voyager Reference Guide 97 .. IF .It is permissible to go backwards. ELSEIF ...... but with a dot (. ELSE . (The program automatically defines any variables not predefined.. 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.Pilot Program Control statements 4 Example 2 GOTO hwybuild :hwybuild IF (expression) GOTO :hwybuild . ENDIF Performs certain operations based on conditions. ENDIF blocks... They may not overlap LOOP .) You may nest but not overlap IF .. compares the variable to a constant. The module does not protect the value of Var during the loop.56) ) statements ELSEIF (loop_cntr > 10) statements ELSEIF (loop_cntr > 5 && diff. but they may not overlap other LOOP blocks or IF blocks. You must specify a value. Begin is the constant value to which the module initializes Var. computation. • • • 98 Cube Voyager Reference Guide .57 & k=(2*j-4) ) || ((J*k) = 14-20.. Incr Statement set ENDLOOP where: • Var is the required user-specified name of the loop-control variable.time_to_bcd < 200000) simple statement IF (expression) EXIT . LOOP blocks may be nested.. ENDLOOP Initializes a variable. End. End is the constant value that the module compares Var to when processing the ENDLOOP statement.4 Pilot Program Control statements IF (matrix. Typical IF block: IF ( ( j=3-5. and branches to the statement following the LOOP block if the comparison fails. program. and other LOOP statements may alter the value of Var. You must specify a value.time < 32) statements ELSE statements ENDIF LOOP .6-30. Incr is the constant the module adds to Var before processing the ENDLOOP statement. LOOP Var = Begin. 10 .2.2 . ENDLOOP Example 2 A nested loop. with the innermost loop executing twice for each value of variable xyz: 10.-2 LOOP abc=1. the module goes to the statement following LOOP otherwise the module goes to the statement following ENDLOOP. Processing of the ENDLOOP statement depends on the value of Incr: • If Incr is positive. ENDLOOP ENDLOOP Cube Voyager Reference Guide 99 . when the value of Var is greater than or equal to End. If the test fails. LOOP xyz=10. otherwise the module goes to the statement following ENDLOOP. the module goes to the statement following LOOP. when the value of Var is less than or equal to End. control is passed to the statement following ENDLOOP. If Incr is negative.1.4. If it is false. the module does not perform any statements within the LOOP block. • The module tests the ENDLOOP condition (without incrementing the variable value) when initializing the loop-control variable. . LOOP iter=1. Example 1 Executes the code within the LOOP block 10 times.6.Pilot Program Control statements 4 If the result of the comparison is true. . the program branches back to the statement following the LOOP statement.8. .sys variables can help provide cleaner output when a system command is performed.4 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. When a “RUN PGM=program” 100 Cube Voyager Reference Guide . The page counter will not be adjusted for the system output.. Sets the line counter so that the invoked PGM will start on a new page. The . Starts a new page before performing the system command. Use this feature to react to fatal returns from Citilabs’ programs. 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. The . it remains in force. until a new value is encountered.. NEWPAGE keywords Keyword afterpgm aftersys beforepgm beforesys |?| |?| |?| |?| Description Starts a new page after a PGM returns.. Once a variable is set. Starts a new page after a system command.sys variables are ignored if the system command contains a redirection ”>” symbol. it can not be cleared by setting RETURNCODE=. If the RETURNCODE value is greater than 1. the user can provide additional statements to further control what is to happen with the run. The job was aborted by user conditions with the ABORT statement. See “GOTO” on page 96 for a description of defining a LABEL. or subsequent tests of the run status may cause termination. The job failed to run to completion and generated on or more fatal error messages. 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. To continue the run. the program sets a return code that indicates what type of message the program returned on closing. However. The CLEARERROR statement is used to reset the internal return code. Typically. 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. The job ran to completion but generated one or more warning messages. the run is automatically terminated. At the labeled statement. Cube Voyager Reference Guide 101 . 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. the run will continue at the labeled statement if the return code is 2. The codes returned are: Code 0 = No messages 1 = Warning messages 2 = Fatal messages 3 = Program aborted Description The job ran to completion successfully.Pilot Program Control statements 4 statement is executed. if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate LABEL statement in the script. the user will have to clear the internal RETURNCODE variable. See “SENDMAIL” on page 111 for an example of using these statements together. This code value is stored in a variable named RETURNCODE. At this point control will transfer to :MYERROR if the MATRIX step fails :STEP2 RUN PGM=…. 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. Note that an EXIT statement should be used just prior to the :label referenced by the ONRUNERRORGOTO.4 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. ENDRUN :STEP3 RUN PGM= ENDRUN 102 Cube Voyager Reference Guide . no errors were encountered :MYERROR PRINT LIST='Special Message' . 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). if program gets to this point then exit. Run will terminate from here with a final completion code of 2 Example 3 ONRUNERRORGOTO = 'MYERROR :STEP1 RUN PGM=MATRIX ENDRUN . ENDRUN EXIT . Example 2 ONRUNERRORGOTO = 'MYERROR' RUN PGM=MATRIX ENDRUN .At this point control will transfer to :MYERROR if the MATRIX step fails RUN PGM=…. if program gets to this point then exit. if program gets to this point then exit. no errors were encountered . MAXSTRING Cube Voyager Reference Guide 103 . ENDRUN :STEP3 RUN PGM= ENDRUN 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 . or all errors cleared :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 RESUME=T .Pilot Program Control statements 4 EXIT . At this point. control will return to :Step2 PARAMETERS Specifies basic parameter values for the Pilot run.At this point control will transfer to :MYERROR if the MATRIX step fails :STEP2 RUN PGM=…. If one has many string variables. TOTAL3 FILE=PRINTFIL. TOTAL1. and lower.002 Example 2 PRINT PRINTO=1 FORM=6. a large value could cause excessive RAM to be allocated. Default value is 255. If a variable is computed to exceed this length. This proved to be too short for some users who were developing strings with considerably longer path names in them. Versions 3. and if a string really needs to be longer than 250. TOTAL2. Now the user can specify what the longest string variable is to be. Example 1 LIST= ITER(6) TIMEPERIOD(6) TOTAL1.4 Pilot Program Control statements <…> is the program default value. a fatal error message will be issued.0CDLR LIST= ITER. PARAMETERS keyword Keyword MAXSTRING |KI| Description Specifies the maximum length to use for all string variables. this parameter must be specified.0CDLR LIST=ITER. 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). TIMEPERIOD.TOTAL1.) Specifying a reasonable length will help to preserve RAM. TOTAL2 104 Cube Voyager Reference Guide . had a maximum length of 127 characters. PRINT Formats and prints a line of information.0.TOTAL2 FILE=PRINTFIL. (We have seen users’ jobs with more than 200 string variables.001 PRINT FORM=6. TIMEPERIOD. and violations of this length were not detected. Enclose with quotes ‘…’ or "…". The response must select one of the answers.Pilot Program Control statements 4 PROMPT QUESTION= ANSWER= WAIT= Poses mid-run questions that can alter the flow of the job. which the user can test via an IF statement. the user can peruse the output from any of the previous step(s) to decide how to respond to the question. QUESTION |KS| Cube Voyager Reference Guide 105 . if it contains any delimiters. PROMPT keywords Keyword ANSWER |S5| Description Possible answers. the program lists a question (defined by the QUESTION keyword) and the possible answers (defined by the ANSWER keyword) and waits for a response. Question to prompt the user with. The program will not continue until a proper selection is made. The ANSWER number is returned to Pilot in the variable named ReturnCode. The use of the keyword PRNFILE on the RUN statement allows the user to redirect the print file for any job steps. it must be within quotes. When encountering a PROMPT statement. There may be up to 5 ANSWERs. When the PROMPT dialog box opens. The same rules about quotes in QUESTION also apply here. a dialogue box is opened. 3 IF (ReturnCode==3) abort IF (ReturnCode==2) break RUN PGM=MATRIX PRNFILE=myfile. . 0< WAIT < 50000 When running in command line mode. ANSWER=’Sum Too High’.4 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. . Example QUESTION=’What do you want to do?’. and the user responds by selecting a button. ‘Sum Too Low’. WAIT is disabled. When Pilot is launched a Windows dialog box opens. If the user makes a choice before WAIT seconds have expired. When in windows mode. 1 ‘Break out of Loop’. enter an invalid key. the program will then wait until a valid number is entered. as soon as a valid number is entered. ENDRUN PROMPT QUESTION=’Examine myfile. the program continues with that selection without requiring a press of the Enter key.txt to determine response to’. the program will not continue until a valid choice is made. . and the user can make a choice and then click on the OK button to proceed. Once any choice is made. 2 ABORT .txt . ANSWER=Continue. and WAIT is disabled. ‘Sum Acceptable – Get Out of Loop’ IF (RETURNCODE==3) break PROMPT 106 Cube Voyager Reference Guide . To gain more response time in command mode. in most cases. PGM=name CTLFILE=name PRNFILE=name REDIRECTIN REDIRECTOUT PARAMETERS Cube Voyager Reference Guide 107 . writes occur at the beginning of stack processing. STACK is static. ENDRUN Loads and executes a program.Pilot Program Control statements 4 REPORT VARS STACK TRACE REPORT keywords Keyword STACK |?| Description Writes the internal stack. the control statement name. if set to true. additional information. turn stack tracing on REPORT Trace=n . Controls the listing of the stack statements as they are processed. TRACE is a trigger key. the program lists the current variables and their values from the VARS array. and. but can be useful for relating TRACE information to internal notation. Each statement will be listed with an internal number. thus controlling the amount of output as desired. TRACE can be turned on and off at any time. This is mostly used for program debugging. TRACE |K?| VARS |?| Example REPORT Vars=y REPORT Trace=y .. When set to true. turn stack tracing off RUN .. or. If you are running a non–Cube Voyager program. A system command (*. If there are no data records following the RUN statement. a clientdeveloped program to run in accordance with Citilabs specifications. it is assumed that the data follows the RUN statement (up to. the quoted parameter must be enclosed by the opposite quote. or a standard OS executable RUN file. You can disable a RUN statement by changing it to !RUN. but not including. or if it requires "def ghi". if the program requires ‘abc’ to be passed to it.) or another RUN statement also signals the end of a RUN statement. you may use additional keywords.. dash. in most cases. The program may be a TRIPS program. a Cube-related program. enclose the parameter within quotes (‘…’ or "…"). the next ENDRUN statement). The program name may be a standard OS file name (path is optional. space.. Citilabs recommends always using ENDRUN. File be used as the program’s standard input. Pilot attaches any control statements between the RUN and ENDRUN command to the specified program..4 Pilot Program Control statements Pilot loads and executes the program specified by PGM. the associated DLL and TDF files must be directly accessible. For example. Only the specified program will read and edit these statements. Parameters may be coded as a series of values. If a parameter will contain any special characters (comma. semi-colon). Parameters that the program expects to find on the invoking command line. If CTLFILE is not specified. Optional.. */) or by using a GOTO statement. Pilot expects to load a Cube Voyager program. However. RUN keywords Keyword CTLFILE |F| Description Optional. it should be coded as ‘"def ghi"’. math operator. If a parameter is to contain quotes.. but is recommended for non-TRIPS programs). PARAMETERS |SV| 108 Cube Voyager Reference Guide . and the those records are copied to a temporary file. You can also disable a RUN statement by placing the statement in a null block (/* .. Though optional. a !RUN statement requires a corresponding ENDRUN. it should be coded as "’abc’". as one string of many parameters enclosed within one set of quotes. CTLFILE is ignored. ENDRUN signals the end of the RUN statement. exe and use the highest # file. REDIRECTIN. and then the directories as registered with the operating system If program*. and REDIRECTOUT are ignored.exe. Switch to indicate that the program is to direct its output to PRNFILE.Pilot Program Control statements 4 RUN keywords (continued) Keyword PGM |S| Description Program to be run. name1. and to locate the directory where it resides. 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. append “. Thus.). PRNFILE |F| Optional. Switch to indicate that CTLFILE is to be directed into the program.exe is found.exe. if name. locate the program by searching the directory from which Pilot was loaded. look in that directory for the latest version of the program by assuming program#. If program contains path information (has a \ or :). 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 . and name3. PRNFILE will be ignored if it is determined that a TRIPS program is being run. File where the program expects to write its standard system print output. name3. If program has no file extension and the last character is not a dot (. REDIRECTIN REDIRECTOUT |?| |?| If it is determined that a TRIPS program is being run (by the presence of &FILES OPRN keyword in the CTLFILE). Pilot determines if it is a Cube Voyager program by searching for both “program. use that path If program does not contain path information.exe are all found. PRNFILE.exe will be assumed.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.DLL” and “program.exe” to program. Optional. if PRNFILE is also specified. Optional. If ctlfile has no length. • • 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. 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. it is not placed on the command line 2.exe ctlfile=datain prnfile=dataout parameters=’abc’ Command: Path\abc. dataout Command: Path\program.exe datain dataout RUN PGM=abc.4 Pilot Program Control statements whose basic operations will not allow this type of integration.exe datain dataout abc RUN PGM=ME ctlfile=datain parameters="/m=20" "/demo" 110 Cube Voyager Reference Guide . 3. tprn is a temporary file which is copied to the Cube Voyager print file. DRI/RDO = redirectin/redirectout Examples RUN PGM=program parameters=datain. In those situations. ".txt. prnfile=zip. standard Cube Voyager run SENDMAIL SMTPSERVER FROM TO CC SUBJECT MESSAGE ATTACHMENTS USERNAME PASSWORD PORT Cube Voyager Reference Guide 111 .zip t*. will be copied to tfile Command: Path\MVESTM70.EXE datain /m=20 /demo RUN PGM=ME .txt RUN PGM=MATRIX .exe" parameters="junk.EXE tfile RUN PGM="c:\util\pkzip. ctlfile follows this statement. -v –c >zip.zip t*. redirectout=t Command: c:\util\pkzip. "-v –c".Pilot Program Control statements 4 Command: Path\MVESTM70.exe junk. 4 Pilot Program Control statements Immediately sends an e-mail. There is a maximum of 1000 attachments. An example might be: smtp.sbcglobal. Cube opens a Password Entry dialog box.com 112 Cube Voyager Reference Guide . SENDMAIL keywords Keyword ATTACHMENTS CC FROM MESSAGE |S| |S| |S| |S| Description List of file names sent as attachments. If coding your script in Cube. PASSWORD |S| PORT SMTPSERVER |I| |S| <25> is the TCP PORT number. E-mail address(es) for copied recipient(s). and SUBJECT must be specified. if the SMTP server requires secure logon. the others are optional. E-mail messages can also be sent as text messages to a cell phone. Use to transmit the status of a job or job step to a recipient. you can insert the password value with the Insert menu command then selecting Password for email. Password for the account specified in USERNAME. Each string is a separate line. The keywords SMTPSERVER. TO. FROM.yahoo. which t allows you to mask the password for security. There is a maximum of 1000 messages. The typical SMTP server uses PORT number 25. Name of the send-mail server. E-mail address to be sent as the return List of individual lines to send in the message area of the e-mail. yourname.DBF. and CLEARERROR to generate e-mail with attachments for various conditions .DBF NETO=DTWNTPP1.sprintpcs.Pilot Program Control statements 4 SENDMAIL keywords (continued) Keyword SUBJECT TO |S| |S| Description Subject of e-mail. RETURNCODE.net Sprint: {phone#}@messaging. set LABEL to jump to if an error occurs StepName='Step 1 . E-mail address(es) of the recipient(s). if the mail SMTP server requires logon. Separate multiple recipient addresses with a comma.Network' RUN PGM=NETWORK NODEI=xDTWNNOD.Network' RUN PGM=NETWORK NODEI=DTWNNOD.NET ENDRUN SENDMAIL SMTPSERVER='smtp.DBF.com Verizon: {phone#}@vtext. USERNAME |S| User name for mail account. Cube Voyager Reference Guide 113 .======================================================================== ONRUNERRORGOTO='ONERROR' . LINKI=DTWNLNK. You can also send mail as a text message to a phone and account that supports text messaging.com'. FROM='[email protected] Check with his/her cell phone service provider to verify the appropriate address. Example Using SENDMAIL with ONRUNERRORGOTO.com'.DBF NETO=DTWNTPP1. LINKI=DTWNLNK.NET ZONES=24 ENDRUN StepName='Step 2 . Examples of cell phone provider messaging e-mail addresses are: • • • T-Mobile: {phone#}@tmomail. Also text message a cell phone SENDMAIL SMTPSERVER='smtp. 'There is no run error'. Run Completed.com.Network') CLEARERROR resume=t code=0 endif 114 Cube Voyager Reference Guide . Run Error'. returncode:'. Subject='Email from Voyager. resume the run if (StepName='Step 2 .StepName .0) .4 Pilot Program Control statements TO='ken@yourname. if an error occurs the processing jumps to this location rcode=str(returncode. TO='ken@yourname. CC='The Boss<[email protected]'. returncode will have value=0. Message='There is a run error. FROM='[email protected]'.com>'.yourname. TO='[email protected]' Exit .com'. Message='Voyager Run Completed'.com'. FROM='[email protected] . 'On Step '. returncode:'.jill@yourname. Message='There is a run error.yourname. Subject='Email from Voyager.com'.3 SENDMAIL SMTPSERVER='smtp. Subject='Email from Voyager. No Error'.sprintpcs. Run Error'. If the error happens on step 2.com'. ATTACHMENTS='DTWNTPP1.2. if no errors then this step gets executed and terminates the run :ONERROR .com'. 'On Step '. ignore the error.rcode. They are excluded. All the RUN statements would have statements following them (including an ENDRUN statement). data for DISTRIBUTION to distribute trip ends ENDRUN RUN PGM=MATRIX . data for HIGHWAY to load trips to highway network ENDRUN RUN PGM=NETWORK .Pilot Program Examples 4 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.0) RUN PGM=NETWORK Cube Voyager Reference Guide 115 . data for MATRIX to combine and factor matrices ENDRUN RUN PGM=HIGHWAY . data for HIGHWAY to build LOS files ENDRUN RUN PGM=DISTRIBUTION . */ RUN PGM=NETWORK .2. with no logic. */ LOOP iter=1. data for NETWORK to build a network ENDRUN RUN PGM=HIGHWAY . so that process can be presented more briefly.5 COMP ID='This is iteration' + str(iter. data for NETWORK to analyze assignment ENDRUN Pilot example 2 /* Example 2: A little more complicated. RESULT <= 0.2.RESULT <= 0. list current variables Newpage BEFORESYS=y.0) RUN PGM=NETWORK RUN PGM=HIGHWAY RUN PGM=DISTTRIBUTION RUN PGM=MATRIX RUN PGM=HIGHWAY RUN PGM=NETWORK ENDRUN IF ( NETWORK.02) BREAK .04) LIST=' exit early ' + str(iter.* 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 .02) GOTO Early_Converge ELSEIF (NETWORK. criteria already satisfied ENDLOOP Pilot example 3 /* Example 3: more capabilities. AFTERSYS=y .4 Pilot Program Examples RUN PGM=HIGHWAY RUN PGM=DISTTRIBUTION RUN PGM=MATRIX RUN PGM=HIGHWAY RUN PGM=NETWORK ENDRUN IF ( NETWORK.0) + ' iterations’ GOTO TRANSIT ENDIF ENDLOOP LIST='Speeds did not converge' EXIT :Early_converge LIST='Convergence after ' + str(iter.2.2. copy transit files to ramdisk *COPY d:\transit\neta\altx*.5 COMP ID='This is iteration' + str(iter. */ LOOP iter=1.0) + ' iterations' :TRANSIT ID=BEGIN TRANSIT PROCESSING REPORT vars=y .RESULT <= 0. Cube Voyager Reference Guide Cube Voyager Reference Guide 117 . a process for modifying a matrix values.5 Fratar 5 Fratar This chapter discusses Fratar distribution. Topics include: • • • Using Fratar Control statements Examples 118 Cube Voyager Reference Guide . In such cases. the column totals will match the target column values. This process continues for some number of iterations. At the end of the iteration. The program makes adjustments to guarantee that the target grand totals do match. the row totals will match the target row values. each row in the matrix is factored according to its production factor. In the second iteration each column in the modified matrix is factored according its attraction factor. but the row totals may not match their targets. This section discusses: • • • • Specifying target values Controlling target totals Convergence — Iteration control Multiple purposes Cube Voyager Reference Guide 119 . but the column totals will most likely not match their targets. 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 process is complete.Fratar Using Fratar 5 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. the row and column totals should converge towards the target totals. When the criteria for convergence is met. the program will fatally terminate. At then end of the iteration. It is possible that the user input values and specifications can preclude obtaining matching totals. Each of the keyword expressions is computed for an array of values for all zones. but a complete understanding of the SETPA statement is necessary. If the final value for a P or A is 0.0. of these filters are specified on a SETPA statement. the PGF and AGF expressions are used. To simplify this description. Direct values and growth factors can be mixed for a purpose.2. growth factors (explicit and implicit). PGF.HBWP2000 would cause the program to simulate the expression: JLOOP J=1. they apply to all expressions on that statement. Example 1 SETPA P[1]=ZI. or some combination of both. To provide the capability of mixing P and PGF for a purpose. and AGF[]= expressions are computed for corresponding arrays.1. An array of production values (Ps) and an array of attraction values (As) are maintained for each purpose. the latest SETPA values replace any prior values.5 Fratar Using Fratar Specifying target values There are several typical ways in which the control totals can be specified: direct values. or both. All specifications are via the SETPA control statements. If either.1.EXTW/2 AGF[1]=PGF[1] INCLUDE=501-550 120 Cube Voyager Reference Guide . To specify P and PGF for the same purpose. They are input to the program via P.HBWP2000[J] . A[1]=ZI.ZONES P[1][J] = ZI.HBWA2000 INCLUDE=1-500 SETPA PGF[1]=ZI.HBWP2000. the program revises it to a growth factor of 1. the SETPA statement may include the basic INCLUDE and EXCLUDE filter specifications. the term “value” will be used to mean either direct values or growth factors. and AGF expressions. If direct values are to be input. separate SETPA statements are used. There must be a set of production values and attraction values for each matrix to be factored.1. ENDJLOOP Similarly. P[1] = ZI. PGF[]=. each would have its own zonal filter set. A[]=. If the sets overlap. If growth factors are to be input. the P and A expressions are used. A.1. the program performs a zonal (I) loop.1. and if the CONTROL for any purpose is specified more Cube Voyager Reference Guide 121 . but that is not an absolute requirement. the target totals for any growth factor values can be fully determined (value = gf * input).EXTW array (divided by 2). will compute only the I=1-500 to J=1-500 portion of the matrix. and the values for zones 501-550 would be the growth factors obtained from the ZI.5) . the values for zones 1-500 would be the direct values obtained directly from the ZI. There are several options for adjustment. Standard numerical expressions (J being the only viable variable that could be included) are used to compute the values. In most cases the values will be obtained from ZDATI (zonal data) files.A. Example 2 SETPA P[1]=5000 INCLUDE=255 .Fratar Using Fratar 5 In this example. Example 3 SETPA MW[1]=. but weird. The matrices are obtained by solving the SETPA MW[]= expressions.HBWP2000 array. The MW expressions are array notation. After all SETPA P. A special feature of these expressions is that if the result is less than zero. the INCLUDE and EXCLUDE filters are employed. or LOOKUP functions. it is desirable to input specific values. Therefore the filters will apply to both the I and J zones. There may be a CONTROL specification for each purpose. but care must be exercised. Sometimes. Again..input a specific value SETPA A[1]=sqrt(J/2+25**3. Next.would be possible. and AGF expressions are processed. they are specified by the use of the CONTROL keywords on the SETPA statement. it is not stored. the program adjusts the values to insure that the P and A totals match for each purpose. obtaining the matrix values for each purpose.2.. INCLUDE=1-500 . Controlling target totals After processing the input matrix.PGF. but applied for each I zone. if they are specified. The changed zones in the P array will be factored so that the final P total will match the A total. Sometimes only certain zones are to be modified. If that is the case. column. AL. If the letter “L” is appended to any of the CONTROL values. lead to a situation where a matrix grand total can not be properly computed. The changed zones in the A array will be factored so that the final A total will match the P total. 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. Traditionally. PL. and PAL. solution. The values in P array for zones that have P changes. PA. If no CONTROL is specified it defaults to PA. All values in both the P and A arrays will be factored so that their totals will match the average of the initial totals. The valid values for CONTROL are: P. because of the potential problems associated with this approach. the latest value prevails. or 100). that has zero to begin with. Value PL AL PAL Description The P totals control. and the remainder of the zones are to be kept constant. the program will fatally terminate. some modelers would scale a matrix by a value (usually 10. and then fill in all empty cells with one. The A totals control. or bad. in some cases. zero accountability is not included in this program 122 Cube Voyager Reference Guide . Use of the this feature can. or row. all values in the P array will be factored so that the P totals will match the A totals. This is not necessarily a good. all values in the A array will be factored so that the A totals will match the P totals. But. If a target value is specified for a zone that initially had no total. The meanings are: Value P A PA Description The P totals control. The A totals control.5 Fratar Using Fratar than one time. it indicates that the modifications are Limited to only the zones that have change. A. It is impossible to modify any cell. a warning message is issued. 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. column total differences are checked. After each iteration. It could also be achieved by setting the SETPA MW expression to: max(1. and the others continue to be processed. If there are multiple matrices being factored. and terminates the process at the minimum RMSE.n*10).mi. A small example of this process: After Iteration 1: RMSE = 22. and after even iterations.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 . It is believed that this process will eventually reach convergence. After odd iterations. the program detects the oscillation. If this happens. The user can specify a maximum number of iterations. the program computes an RMS error value based upon the integer differences between the computed and target row or column totals. so that no matter how the convergence is progressing. the RMSE value begins to oscillate. If the RMSE value is less than the MAXRMSE parameter value. they may reach optimum solutions at different times. the solution is achieved. the “solved” matrices are held steady.Fratar Using Fratar 5 directly. Convergence — Iteration control A concern is when to stop the iterating process. due to some unforeseen conditions. If the scaling scheme is to be applied. row differences are checked. the process will not exceed that number. But if. there are several ways to control it.n. a prior application of the Matrix program can be used to scale and fill in a matrix in any desired manner. But.01 and MAXITERS=10). AGF.5 Fratar Using Fratar As dictated by row factoring. but the row totals are not quite on target. 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. until either the RMSE drops to the MAXRMSE level. or MW index found on any SETPA control statement. The distribution is performed prior to entering the main Matrix program I-loop.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. and the results appear as: After Iteration 2: RMSE = 7. The program assumes that there will be purposes from one. MW[1] through MW[highest purpose] 124 Cube Voyager Reference Guide . In this example. the column totals do not quite match the target. the values are carried with more precision. back and forth. through that highest index. Multiple purposes The number of purposes is determined by the highest P. When the main I-loop is processed. This process goes on. or the number of iterations reaches the MAXITERS value. monotonically. A. the final solution is reached after 5 iterations (MAXRMSE=0. the row totals are correct. Internally. PGF. Another iteration is performed. Cube Voyager Reference Guide 125 . a standard Matrix program I-loop is performed. After the factoring process is complete.Fratar Using Fratar 5 are initialized with the final matrices from the Fratar distribution. ” 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 .5 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. For descriptions of other control statements see Chapter 9. “Matrix Program. This section only describes the differences between the Matrix and Fratar control statements. For large systems. not writing output matrices for each iteration saves considerable computer time. If you anticipate that there will be many iterations before reaching convergence. you may specify the parameters described here. set this switch to false. PARAMETERS keywords Parameter MATOEVERY |K?| Description Switch that can force the program to write output matrices for every iteration. the number of iterations actually performed could be less than this value. If the MAXRMSE criterion is met. and the max is 99. Cube Voyager Reference Guide 127 . The default is 9. instead of waiting until the last iteration. MAXITERS |KI| Maximum number of iterations. but prevents the program from having to run another iteration to write the output matrices after reaching convergence.Fratar Control statements 5 In addition to the standard Matrix parameters (see “PARAMETERS” on page 539). If you anticipate that the process will involve only a few iterations. set this switch true. but forces another processing iteration to write the matrices after reaching convergence. Writing output matrices for each iteration increases run times for each iteration. and it conflicts with the SETPA statements. PCOMP |KIP| 128 Cube Voyager Reference Guide . The default is 10. If the RMSE for a purpose does not exceed this value. The values are reported as nearest integers (without decimal places). If present. ZONES |KI| Highest zone number to process. so this keyword should not be required. and the minimum is 0. Normally. but refers to productions. or the value will default to 100. and refers to only even iterations.5 Fratar Control statements PARAMETERS keywords (continued) Parameter MAXPURPS |KI| Description Number of purposes to process in this application. MAXRMSE |KR| REPORT PCOMP ACOMP In addition to the REPORT keywords available for Matrix. ZONES must be provided. The report is in a format that is similar to the MARGINS report. The keyword is not required. a solution is assumed for the purpose. a fatal message will be issued. If the number of zones cannot be ascertained from the project file or from any binary input matrices. if this value is provided. Cutoff criteria. but they are reported for all odd iterations. Same as ACOMP. But. Only the purposes specified by the keyword are reported. because the program will determine the value from the detection of the values on the SETPA statements. the following are also available for Fratar: REPORT keywords Keyword ACOMP |KIP| Description Requests report comparing computed to target attractions for specified purposes. there will be an input matrix file. this value controls the application. The Ps and As are computed from the expressions that are supplied. the expression is solved in a loop of J=1-Zones. In a purpose where the Ps and As are the same for each zone. but the use of any variables in the expression could cause unpredictable results. monotonically. The keywords may not have a zone index in the SETPA statement. the subsequent values will replace the prior values. the program will issue a warning statement. the expression will simply point to a ZDATI file variable. The highest index encountered establishes the number of purposes. For each array. and the results are stored in the A. If there are any holes in the purpose scheme. it is acceptable to set the Ps. the program will fatally terminate.request reports for the specified purposes SETPA Establishes base productions and attractions. and they are computed only one time -. There should be a P[]= and A[]= and MW[]= expression for every purpose beginning with 1 and continuing. Complex expressions are allowed.Fratar Control statements 5 Example ACOMP=1-3. In most cases. and how many purposes are to be processed.P. Duplication of purposes might be helpful if values for different zones for a Cube Voyager Reference Guide 129 . until all purposes are defined. and then set the As equal to the Ps.5 . P A PGF AGF MW CONTROL INCLUDE EXCLUDE The SETPA statement is required. The SETPA expressions are computed in the order in which they appear in the control stream. If the same purpose is referenced more than one time.prior to the first iteration. These statements define how the production and attraction factors are to be obtained.MW [n][J] cells. if it is not included. If it is used. The possible values are: P A PA PL Production totals control. Processed the same as INCLUDE on COMP statements (see “COMP” on page 47). or if different INCLUDE/EXCLUDE filters are to be used (different SETPA statements must be used for different filters). EXCLUDE filtering follows any INCLUDE filtering. but only Ps in adjustable zones will be adjusted PAL Same as PA. SETPA keywords Keyword A AGF |NV| |NV| Description Expression solved to set the target attraction totals for the indexed purpose. but only As in adjustable zones will be adjusted CONTROL |SV*| AL Same as A. the loop will not be processed for any zones in the list. Same as P. the loop will not be processed for any zones not in the list. The final totals are obtained by multiplying the growth factors by the initial input matrix totals. Ps will be adjusted Both Ps and As will be adjusted to the average of the P and A totals. INCLUDE |IP| 130 Cube Voyager Reference Guide . If it is used. As will be adjusted Attraction totals control.5 Fratar Control statements purpose are to be obtained from different sources. but only adjustable zones will be adjusted EXCLUDE |IP| Processed the same as EXCLUDE on COMP statements (see “COMP” on page 47). INCLUDE filtering precedes any EXCLUDE zones. Expression solved to set the target attraction growth factors for the indexed purpose. String indicating how to adjust final target totals to enable convergence. Expression solved to set the target production totals for the indexed purpose.1.1.1. MW[1]=mi.1 CONTROL=PAL Using multiple CONTROL keywords: SETPA P[1]=(ZI.1.n. but that is not required.P1) A2=(ZI.A1) MW2=1 CONTROL[2]=P SETPA P[3]=(ZI.1. this expression will be a single variable name such as MI. The result is the matrix row for that zone.1.P1) A1=(ZI.A1) MW1=1 CONTROL[1]=A SETPA P[2]=(ZI.n.Fratar Control statements 5 SETPA keywords (continued) Keyword MW |NV| Description Expression solved for each zone during the first iteration.P1) A3=(ZI.xifac. P PGF |NV| |NV| Example Using single CONTROL keyword: SETPA PGF[1]=zi. AGF[1]=PGF[1].1.A1) MW3=1 CONTROL[3]=PA Cube Voyager Reference Guide 131 .1. Expression solved to set the target production growth factors for the indexed purpose. Usually. The MATRIX step generates a 3 zone matrix. R='1 100 240'.RESULT=3.LOOKUP[2]=1. '2 200 200'.LOOKUP[1]=1. */ RUN PGM=MATRIX ZONES=3 MATO=3ZONE.MAT.MO=1 LOOKUP NAME=TOT.01 MAXITERS=10 SETPA P[1]=TOT(1. '3 300 160' MAXRMSE=0.MAT.1 ACOMP=1.J) MW[1]=MI.RESULT=2.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.PCOMP=1 MARGINS=1 ENDRUN 132 Cube Voyager Reference Guide . It is a good example of different ways to “play” with MATRIX.J) A[1]=TOT(2. and the FRATAR step modifies it.MAT MATO=3ZONEF.1.5 Fratar Examples Examples /* The following two steps (MATRIX and FRATAR) setup and run the small example used in the Introduction to illustrate convergence. Cube Voyager Reference Guide Cube Voyager Reference Guide 133 . 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.” 134 Cube Voyager Reference Guide . “Intersection Modeling. see Chapter 7.6 Highway Program 6 Highway Program This chapter discusses the Highway program. See the description of PATHO in “FILEO” on page 201 and “PATHLOAD” on page 230. The Highway program’s primary function is to assign trips to highway network links.” for a detailed description of intersection modeling and the data requirements. turning volumes. and a loaded network. “Intersection Modeling. The descriptions below refer to link based traffic assignment. zonal matrices. There are basic default operations. The Highway program now can write the full path file from an assignment run including full results from every iteration. junction data and turn penalties can be input. but the user can control much of the process Cube Voyager Reference Guide 135 . This makes many forms of path based analysis directly accessible in Cube without having to rerun the assignments with specific commands in the scripts. final junction delay and reports can be output. also refer to “Highway path display” on page 297 of the Cube Base Reference Guide for information about path-based analysis in Cube. zonal data.Highway Program Using the Highway program 6 Using the Highway program This section provides helpful information about using Cube Voyager’s Highway program. A highway network. Refer to Chapter 7. Junction-constrained assignment requires the coding of the junction or intersection movements and controls. new matrices. 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. and usually writes them to output matrices. In each phase the program performs certain specific operations. The Highway program provides the same capabilities as a traditional assignment program. Select link analysis is a major tool for most users. Normally. The underlying assumption is that path building and capacity restraint are based upon a generalized cost on each link. For normal processing. but since there is no fixed format of the network. There are several ways to obtain the free flow time (T0). the values are computed directly from the variables in the input network. there must be a way of computing certain required values for each link. the required variables may not be present. 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. There are only a few automatic operations.6 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. the LINKREAD phase can be used and formulated to provide these values. In most cases. Various options are usually available to provide the user with additional outputs. Then the entire path and assignment process is repeated. Almost all of the operations follow a fixed pattern. the user must supply the process to obtain them. The volumes from each iteration are combined to form a weighted assignment. This process “traps” the trips that meet the select link criteria. the cost is time. If there is no automatic way for the program to determine these values. 136 Cube Voyager Reference Guide . The program operates by processing in various phases. and global parameters are used sparingly. link costs are updated based upon the level of congestion on each link. in the description of the LINKREAD phase. but functions somewhat differently. In that case. After all origin zones have been processed. Different criteria are used to determine when enough iterations have been performed. The hierarchy of the processes to obtain T0 and T1 is outlined below. This process continues until some criteria for termination is reached. In addition to phase operations. and the initial path time (T1). and are driven by basic parameters. and optionally processes a stack of operations provided by the user for that phase. the LINKREAD stack should contain the following statements: DISTANCE=LI. not absolutely necessary T0 = LI. If the variables DISTANCE. 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. SPDCLASS. and SPDCLASS are in the network. it would be better to rename and scale the variables appropriately during the network conversion process. TIME1. so that it is not necessary to remember to deal with them in the Highway program.DISTANCE/100 .Highway Program Using the Highway program 6 The best advice is that the network should contain a variable that can be used directly for T0. and CAPACITY. If such a network is used directly. The major phases in the process are: • • • • SETUP — Optionally. it will usually contain variables named DISTANCE. LANES. If the network distance is properly scaled. and is not necessarily a true T0 (free flow time). test for convergence and adjust link values for next iteration Cube Voyager Reference Guide 137 .TIME1/100 C = LI. factor to get on same scale with trips In reality. T0 will be computed from the DISTANCE. respectively. or that it contains variables so that DISTANCE and SPEED information can be easily obtained. CAPACITY is normally the total capacity for the link. TIME1 is the starting time for assignment.CAPACITY * CAPFAC . DISTANCE and TIME1 are usually in hundredths of miles and hundredths of minutes. LANES. and the SPEED portion of the SPDCAP tables. If the network is the result of conversion from a TRANPLAN network. 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. T0 can be computed from the DISTANCE and the values from the SPDTAB speed table. most users simply use the short form: PHASE=PhaseName without the PROCESS control word. Examples include: COMP PATHLOAD SET • Reporting statements — Accumulate or dynamically display values. These two statements are interchangeable. However. Highway program control statement overview There are several types of control statements in the Highway program: • Definition statements — Define static processes. The phases are specified by using PROCESS PHASE=PhaseName statements.6 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. For more information about phases. if there is no explicit ILOOP phase. the program will terminate with an appropriate message. Examples include: FILEI and FILEO which define the input and output data FUNCTION LOOKUP PARAMETERS • Computational statements — Update variable values. A PHASE is closed with either an ENDPROCESS or an ENDPHASE statement. Examples include: 138 Cube Voyager Reference Guide . 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 simplistic purposes. see “Phases” on page 155. Highway Program Using the Highway program 6 PRINT PRINTROW REPORT • Flow control statements — Set statement order. See “FUNCTION” on page 211. see “Control statements” on page 179. Cube Voyager Reference Guide 139 . You can also use FUNCTION statements to enter single expressions for computing certain values. but capitalization may make them a bit more meaningful. 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. Functions and built-ins This section lists built-in variables. arrays. Examples include: GOTO :label LOOP BREAK CONTINUE ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For details about control statements. Cube Voyager sets I to that value. The specified value must be greater than the current I. Current iteration number. Zero value means do not include in equilibrium. it is the sum of all VOL[] sets. See “Example of _SKIPTOI” on page 146. Link free flow time. Total link volume used in ADJUST phase. do not be reset. Column index. Initial iteration time. you can modify in LINKREAD. C* DISTANCE* I ITERATION J LAMBDA LASTITERATION LINKCLASS* LINKNO LOWCNT NODES NUMLINKS PROJECTLINK SPEED* T0* T1* V* ZONES 140 Cube Voyager Reference Guide . usually 1. Lambda value computed for this iteration. Link distance expressed in miles or kilometers. the others are reserved. Its value is checked at the end of the current I. you can modify in LINKREAD. and varies (1-Zones) for MW[] and JLOOPs. Capacity used in congestion expressions. Current row’s zone (ILOOP). Link speed. Number of zones. Number of links. Link number (available during any implied link loops) Result of LOWEST(). Last iteration indicator. jump to the specified zone immediately. by default. If specified.6 Highway Program Using the Highway program Built-in variables Only the variables with a * may be stored into by the user. usually set to the MAXITERS parameter Class of the current link. Variable _SKIPTOI Description In the ILOOP phase. Number of nodes. Link distances. Link cost values. Link volumes. Cube Voyager Reference Guide 141 .s1. Add matrixes mw[1] + … + mw[sn] into mw[d].sn) ROWMPY(d. Minimum value in the row. Array A B COST DIST* LI. Multiply mw[d] by mw[s]. the default [linkno] is supplied by the program.s) Description Row total. A work matrix. the others are reserved. Number of cells whose values != 0.name* MW[]* TIME* VOL[]* Description A-nodes for each link. see “COMP” on page 182 for more details. B-nodes for each link. Maximum value in the row. Factors the row by fac. Link values from the network. Function ROWSUM(mw) ROWCNT(mw) ROWMIN(mw) ROWMAX(mw) ROWAVE(mw) ROWFIX(mw) ROWFAC(mw. Most times.…. Link times. Convert mw to integer values (start at column intrazonal + 1).fac) ROWADD(d. the link-oriented arrays need not be referenced with an index.Highway Program Using the Highway program 6 Built-in arrays There are arrays that can be referenced with […] to indicate a specific value from the array. Built-in functions These built-in functions are described in “COMP” on page 182. User generated values for links (currently accepts numeric values only). Average cell value where value!=0. The names with a * can be stored into.name LW. The RAAD for the current iteration. Initialized to the value PARAMETERS RELATIVEGAP. may be reset anytime. Actual number of cells found by LOWEST function. Converge phase variables Variable GAP RGAP AAD RAAD PDIFF RMSE BALANCE GAPCUTOFF* RGAPCUTOFF* AADCUTOFF* Description The GAP for the current iteration. The RMSE for the current iteration. The RELATIVEGAP for the current iteration. Built-in variables available in the CONVERGE phase There are various variables available for testing in the CONVERGE phase. Initialized to the value PARAMETERS AAD. Initialized to 0 and set to 1 when convergence criteria have been met. The PDIFF for the current iteration. Capacity from captab. LI. Must be indexed for previous iterations. Initialized to the value PARAMETERS GAP. Must be indexed for previous iterations. may be reset anytime 142 Cube Voyager Reference Guide . Must be indexed for previous iterations. Must be indexed for previous iterations. The AAD for the current iteration.class) CAPACITYFOR(lanes. Sum of link values (Time. Speed from spdtab.6 Highway Program Using the Highway program Function ROWDIV(d. See “CONVERGE phase” on page 171 for examples of usage.) on path for I to J. Must be indexed GAP[] for previous iterations. or LW. Cost.s) LOWEST(mw. Sum of lowest valued cells in a matrix row.class) PATHTRACE(value) LINKNUM(a.b) Description Divide mw[d] by mw[s]. Must be indexed for previous iterations.#) LOWCNT SPEEDFOR(lanes. may be reset anytime. Link number for link a-b. Minimum change in GAP between the last n iterations. Built-in functions available in the CONVERGE phase There are various functions available that return a value for testing in the CONVERGE Phase.Highway Program Using the Highway program 6 Converge phase variables (continued) Variable RAADCUTOFF* PDIFFCUTOFF* RMSECUTOFF* Description Initialized to the value PARAMETERS RAAD. Function that results in the average GAP between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. See “CONVERGE phase” on page 171 for examples of usage. GAPCHANGEMIN Cube Voyager Reference Guide 143 . 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. may be reset anytime. may be reset anytime Initialized to the value PARAMETERS PDIFF. Maximum GAP between the last n iterations. where n = the number of iterations to process. Change in RMSE between the specified iteration (the required argument) and the previous iteration. may be reset anytime Initialized to the value PARAMETERS RMSE. Change in RELATIVEGAP 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 AAD between the specified iteration (the required argument) and the previous iteration. Minimum GAP between the last n iterations. Change in PDIFF between the specified iteration (the required argument) and the previous iteration. Average change in AAD between the last n iterations. Minimum change in AAD between the last n iterations. Minimum change in RELATIVEGAP between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. Minimum RELATIVEGAP between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. 144 Cube Voyager Reference Guide . Minimum AAD between the last n iterations.6 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. Minimum change in 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. where n = the number of iterations to process. Maximum AAD between the last n iterations. Maximum change in AAD 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. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. Minimum RAAD between the last n iterations. Average AAD 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. 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. where n = the number of iterations to process. Average RELATIVEGAP between the last n iterations. Maximum 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. where n = the number of iterations to process. Maximum RMSE between the last n iterations. Minimum change in RMSE between the last n iterations. In many applications. 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.Highway Program Using the Highway program 6 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. 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. For example. Average change in RAAD 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. only a few ILOOP statements will be required. Maximum PDIFF between the last n iterations. Average PDIFF between the last n iterations. where n = the number of iterations to process. an assignment would require only the following statements: Cube Voyager Reference Guide 145 . where n = the number of iterations to process. Maximum change in RMSE between the last n iterations. Minimum 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. Average RMSE between the last n iterations. ....1.1.. FILEO NETO=. PHASE=ILOOP PATHLOAD VOL=MI.. */ . most users tend to think of assignments in terms of time. the first zone will be processed and then jump to I=100...1. In our examples 146 Cube Voyager Reference Guide .6 Highway Program Using the Highway program Example of most simple assignment Assume NETI contains values to obtain T0.. the program assumes that cost is equal to time. zones 2-99 will be skipped. MATI=. but it can be somewhat more difficult if deviations from the normal procedure is desired... all that is needed is an input network and a trip matrix.. MATI=. unless the user specifies otherwise. If the network is in the proper format (contains the required variables) only a few statements are required. Therefore.1.. In this section we would like to walk the novice users through the steps of setting up the scripts for typical situations. RUN PGM=HIGHWAY FILEI NETI=. RUN PGM=HIGHWAY FILEI NETI=. While the program bases its computations upon generalized costs. To accommodate this. PATH=TIME ENDRUN Example of _SKIPTOI /* In this example. FILEO NETO=.. 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. PHASE=ILOOP PATHLOAD VOL=MI. To perform a typical traffic assignment. net PHASE = ILOOP PATH=TIME. and the network has the following variables. Thus. simple case NETI = mybase.net MATI = mytrips.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. NETI. we wish to do a peak-hour assignment. up to 10 iterations of assignment and capacity restraint will be run.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 . peak O-D trips NETO = loaded. By default. In the following examples we will work from this same template and to keep reading to a minimum. VOL[1]=mi. we will not include the RUN. MATI. NETO.Highway Program Using the Highway program 6 we will assume that time is the basis for the process. Variable T0 DISTANCE C Description Link free flow time Optional. and ENDRUN statements. it will stop sooner if equilibrium convergence is reached before 10 iterations.1. VOL[1]=mi. but useful for certain statistics Link capacity in veh/hr Base case is therefore: RUN PGM=HIGHWAY .mat . our illustration script would look like this: PHASE = ILOOP PATH=TIME.1. The volume used in each link’s capacity restraint is determined by the program by performing the V function which by default is: V=VOL [1]+… VOL[n]. We do this by the typical process. So. 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. PARAMETERS CAPFAC=10. VOL[1]=mi.6 Highway Program Using the Highway program • • Separate trips on separate paths Assignment of trips to HOV facilities Daily assignment Now let’s add a few complications: The trip matrix contains daily trips. VOL[2]=mw[1] In this case. That matrix is then assigned to volume set 2 (VOL[2]).1. The only thing that we need to do is to get the capacity into the correct units (we’ll assume that daily capacity is 10 times the hourly capacity). but add an additional select link assignment to the typical assignment. work matrix 1 (MW[1]) is computed to be only the trips from MATI whose paths use the selected link. by adding a capacity factor. but let’s just do the simplest. and we wish to do a daily assignment. VOL[1]=mi.1 Add select link loading Back to base case. MW[1]=mi. We can do this in one of several ways. we merely replace the function in the following manner: FUNCTION V=VOL[1] PHASE = ILOOP PATH=TIME. 148 Cube Voyager Reference Guide .1. factor NETI capacity by 10 to get daily capacity PHASE = ILOOP PATH=TIME. capacity restraint will only involve VOL[1]. Because we supplied the V function. where n is the highest volume set in the setup.1.1. SELECTLINK=(L=2001-2002). 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.1. We have to tell the program to not add the selected link volumes. A typical situation occurs when Cube Voyager Reference Guide 149 . PHASE = ILOOP PATH=TIME. Trucks use a variable from NETI as their base path times.TRKVOL = LI.2 Use preloaded truck volumes Base case but include the volumes from a prior assignment on the network as additional volumes.1. VOL[1]=mi.TRUCKTIME PHASE = ILOOP PATH=TIME. save the prior assignment volumes ENDPHASE FUNCTION V=VOL[1]+LW.1.TRKTIME.1. and you wish to use the volumes (plus 30 percent to get passenger car equivalency) in determining total congestion. Trucks use same paths as cars and the combined volumes are used in the capacity restraint.3 PHASE = ILOOP PATH=TIME. those times will remain constant throughout the assignment.2 Add truck assignment on separate paths Base case plus assign the trucks from the second matrix on MATI.Highway Program Using the Highway program 6 Add truck assignment on same paths Base case plus assigning the trucks from the second matrix on MATI.1.TRKTIME = LI. PHASE = LINKREAD LW. PHASE = LINKREAD LW.1. In this scenario.TRKVOL*1.1. the link times are different then the times used for the first matrix. VOL[2]=mi. VOL[2]=mi. but when the paths for the other matrix are developed.1 ENDPHASE Separate trips on separate paths This involves more planning and a bit more script to set up the process. Assume that truck trips were assigned. we will assume that one matrix will be assigned to the minimum time paths.1 PATH=LW. VOL[1]=mi. VOL[1]=mi.V_1 . SPEED TRKFAC = 1. in which we do the truck time adjustment for the next iteration.TRKTIME) of times to be used in assignment of the truck trips. the program would automatically adjust the car times.3 PHASE = ILOOP PATH = TIME.PHASE = LINKREAD IF (LI. VOL[2]=mi.1. EXCLUDEGROUP=3.2 ENDPHASE PHASE = ADJUST LW.45.FUNCTYPE == 15. and mi.75) TRKFAC = 1. VOL[2] = mi. and those that could use 3+ facilities.35. we will establish a time factor to adjust the time on all links. VOL[1]=mi.1.3.1 PATH=TIME.6 Highway Program Using the Highway program trucks basically operate at a lower speed than cars. The trip matrices have been previously split into matrices that could not use any HOV links. those that could use 2+ facilities. EXCLUDEGROUP=2-3.1. VOL[1] = mi.1 PATH = LW.1.TRKTIME.1. We will use 2+ and 3+ facilities.2. The LINKREAD phase will establish an array (LW. So. respectively.HOV==3) ADDTOGRP=3 PHASE = ILOOP PATH=TIME.1. 25. stored in mi.TRKTIME = T0 * TRKFAC ENDPHASE FUNCTION V = VOL[1] + VOL[2]*1. PHASE = LINKREAD T0 = LI.65.1. In this example.2 LW.DISTANCE * 60 / LI. we have to introduce an ADJUST phase.2 PATH=TIME.TRKTIME = TIME * TRKFAC ENDPHASE Assignment of trips to HOV facilities Base case plus LINKREAD to flag HOV links. mi.1.0 IF (LI. After the first iteration. but there is no automatic way to adjust the truck times.55. which are flagged in the network variable named HOV.3 150 Cube Voyager Reference Guide .HOV==2) ADDTOGRP=2 IF (LI.1. VOL[3]=mi. Every off-gate must have a unique number (1-999). which designate the link’s role in the toll system. 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. This section discusses: • • Network development Path development Network development To use the path-based tolling TOLLMATI function. Every on-gate must have a unique number (1-999). Toll access rules: Toll on-ramps: • Cube Voyager Reference Guide 151 . you must follow several rules when coding closed toll systems. Every toll-road link must be identified as such (that is. Violating any of these rules causes Cube Voyager to terminate. You specify toll records in a FILEI TOLLMATI file. A link can have a non-zero value for at most one of these attributes. • Each network link must have three attributes. value is not 0). • Each toll facility must operate as a completely closed system where users can access and egress the facility only by crossing specified toll gates.Highway Program Using the Highway program 6 Path-based tolls This section describes how to incorporate path-based tolls. You specify the attribute names in a FILEI TOLLMATI statement. Inbound link must be a toll-road link or a toll on-link. you must name ENTRYGATE and EXITGATE to indicate which fields on the record contain the on. ENTRYGATE= EXITGATE= TOLLS= NETIENTRY= NETIEXIT= NETITOLLROAD= The file may be a DBF. 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. and so forth.road link or a toll onlink. For delimited text files. the values are field numbers 152 Cube Voyager Reference Guide . Outbound link must be a non-toll. Outbound link must be a toll-road link or a toll off-link. and TOLLS must name the fields containing the toll values. an MDB-element. 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. The first value for TOLLS is toll set 1.6 Highway Program Using the Highway program • • • • Inbound link must be a non-toll-road link or a toll offlink. The first value for TOLLMATI refers to the FILEI TOLLMATI[#]. or a delimited text file. For DBF or MDB files. 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.and off-gate numbers. specify the keyword TOLLMATI= on a PATHLOAD statement. the second value is set 2. the application does not consider Cube Voyager Reference Guide 153 . the default is the relative field on the record (ENTRYGATE is 1. keywords indicate the NETI link attributes that contain the values for the ramp and road links. and if not. In some systems. If any are unnamed. It saves those on-off combinations and uses them during the PATHLOAD statement. the program determines the onoff combinations that are possible for each PATHLOAD statement. and TOLL is 3). TOLLROAD.. it fatally terminates. It checks if there is a toll for each of those combinations. A possible on-to-off route does not have a toll specified. The NETI. If you use the keywords on more than one such statement.. the defaults names are: TOLLENTRY. Zero is an acceptable value. More than one link has the same on-ramp value. TOLLEXIT. but since the toll routings and costs are fixed for the iteration. therefore. changes in the path array might cause a different on-off routing. and up to ten toll sets. Cube Voyager assumes a toll value of zero.Highway Program Using the Highway program 6 instead of names. they must have the same values. EXITGATE is 2. NOTE: If a record exists for a gate-to-gate combination (for the TOLLMATI#). You can use these keywords on any FILEI TOLLMATI statement. If any of these values is not specified. altering the array would probably not cause a different routing between on-off ramps. but does not contain a specific toll (value missing or blank). but. do not revise the PATH=array within the iteration. At the beginning of each iteration. The program will fatally terminate if: • • • • • A link has a nonzero value on more than one of the required toll attributes. There is a violation of the above access rules. There may be up to ten TOLLMATI record numbers. the on-off travel costs could become incompatible with the array costs. More than one link has the same off-ramp value. With most toll systems. The PATHLOAD path-building process does not directly use the toll facility links. instead.6 Highway Program Using the Highway program such changes. the process uses the predetermined combinations. 154 Cube Voyager Reference Guide . 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. the new PATHTOLL keyword value can be used to skim the toll values for the paths (MW[1]=PATHTOLL). During path building. For an example of a script using TOLLMATI. see “Highway example 8” on page 268. Highway Program Phases 6 Phases You code Highway-program control statements within different phases. The Highway program processes the phases in a specific order. The SETUP phase can only contain COMP and SET statements. its stack. The Cube Voyager Reference Guide 155 . 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 phase’s control statements—that is. the program processes an internal loop from the first link through the last link.TOLLTIME = LI. C. you might use: • • COMP statements to alter. you must give link-work variables names that begin with “LW. Use the SETUP phase to initialize certain variables and/or arrays. T1. or set.TOLLTIME / 100 generates a temporary variable that has no meaning beyond the current link. TIME. The program stores link-work variables as link-work arrays (see “Built-in arrays” on page 141). link values. LINKCLASS.TOLLTIME / 100 generates a value available for every link at any phase in the program.” Link variables not obtained directly from the network are called link-work variables. During the LINKREAD phase. the statement: LW. You reference values obtained directly from the network with the network variable name prefixed by “LI. COST. On the other hand. Remember that DISTANCE. This phase obtains the required initial values from the input network and computes link values that you can reference in other phases. the statement: TOLLTIME = LI.” For example. LINKREAD phase An initial LINKREAD phase follows the SETUP phase. the program obtains a link data record from the input network (NETI). 156 Cube Voyager Reference Guide . and processes any control statements (the LINKREAD stack).6 Highway Program Phases SETUP phase does not have a header: it precedes the first actual PHASE= statement. LINKNO=1. PRINT statements to list information about individual links. NUMLINKS). and DIST contain meaningless values during LINKREAD processing. T0. 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. using the LINKNO variable (that is. To reference link-work variables. For each value of LINKNO. In the LINKREAD stack. C. and DIST in the LINKREAD stack. After processing the LINKREAD stack.) For example. you can disable links with certain GROUP code values during path building to preclude using those links in the path. doing so could alter the internal arrays used and dynamically altered by the capacity-restraint process. COST. NOTE: The program does not set the TIME. There are several methods for setting these variables (see “Setting TIME. the program also processes the LINKREAD stack for each link when reading and processing the link in the ADJUST (capacity restraint) phase. COST and DIST values after processing the LINKREAD stack for each link during the capacity-restraint process (that is. and DIST values” on page 158). COST. you need not specify any stack statements in this phase. you might build lowoccupancy vehicle paths by precluding the use of HOV links. during the ADJUST phase). Other applications can also take advantage of this capability. Cube Voyager Reference Guide 157 . You might use GROUP codes for various reasons. If you do not need any special LINKREAD operations. Therefore. and DIST values. or combination of levels. COST. of GROUPcoded links. You can easily identify paths that use links with certain GROUP codes. LINKCLASS. (See “PATHLOAD” on page 230 for more details. you must not reference DISTANCE.Highway Program Phases 6 NOTE: The program processes the entire LINKREAD stack for each link whenever reading a network link’s data record. For example. and use these paths for extracting matrices. GROUP codes can be very useful in select-link processing. See “SETGROUP” on page 253 for details. TIME. To ensure consistency. the program ensures that certain link variables (T0. T0. You can even identify the paths that have a certain level. and C) have values and sets the link’s TIME. T1. T1. You can use the LINKREAD phase to specify GROUP codes for links. DISTANCE. use that value.CAPACITY.LANES and LI.SPDCLASS). 158 Cube Voyager Reference Guide .LI.LANES and LI. set C = LI. the program sets TIME. If DISTANCE < 0. Else if there is a LI. set LINKCLASS = LI. Else if there is a LI.6 Highway Program Phases Setting TIME. set LINKCLASS = 1.LINKCLASS. • SPEED (possibly used to compute T0): If set by LINKREAD stack. COST. use that value. and 1-99).SPDCLASS and their values are valid (1-9. set C = CAPACITYFOR(LI. • LINKCLASS (essential for selecting appropriate Functions): If set by LINKREAD stack.DISTANCE. set SPEED = LI. • C (capacity. use that value. Else if there is a LI.SPEED. Else If there are valid LI. set SPEED = SPEEDFOR(LI. use that value.CAPCLASS) * CAPFAC. Else set DISTANCE = 0. Else set SPEED = 0. and DIST values After processing the LINKREAD stack. Else set LINKCLASS = 1. set DISTANCE = 0.SPEED. Else if there is a LI.LANES. set DISTANCE = LI. Else set C = 0.LINKCLASS.LI.CAPACITY* CAPFAC. COST. used later in restraining process in the ADJUST phase): If set by LINKREAD stack. Else If there are LI. If LINKCLASS < 1.CAPCLASS values (1-9 and 1-99). and DIST values using the following logic: • DISTANCE (possibly used to compute T0): If set by LINKREAD stack.LANES. Else if there is a LI. • COST (a link-work variable. If T0 < 0. Therefore. Else if there is a LI. NOTE: Though the program examines DISTANCE and SPEED. of T1 values): Set equal to T1. without the required “LW. • DIST (a link-work variable. Else if there is a LI. without the required “LW.Highway Program Phases 6 If C < 0.” prefix. set T0 = LI. • T0 (free flow time): If set by LINKREAD stack. the program will try to obtain DISTANCE and SPEED values.TIME1.TIME1. Else set T1 = T0. of cost values): Compute from the COST function for the LINKCLASS. the program computes T0 by dividing DISTANCE by SPEED. Do not reference COST in LINKREAD stack. Do not reference DIST in LINKREAD stack.” Prefix. use that value.TIME. set T0 = DISTANCE*60/SPEED.” prefix. set T0 = LI. Do not reference TIME in LINKREAD stack because its value is unpredictable during stack processing. of DISTANCE values): Set equal to DISTANCE. set T0=LI.TIME. Usually. • TIME (a link-work variable. without the required “LW. you need not specify them. NOTE: The program treats a link capacity of 0 (zero) as infinite capacity. use that value. If you do not set these values Cube Voyager Reference Guide 159 . set T0 = 0. Else if SPEED > 0.T0. set C = 0.T0. • T1 (initial iteration time): If set by LINKREAD stack. Though the highest set number is 20. Zones). if you set T0 directly. The program executes the ILOOP stack one time for each value of I. in the ILOOP stack). and clears each at the beginning of each iteration. A VOL[#] expression implies an 160 Cube Voyager Reference Guide . This phase is the first phase of the iteration loop (ITERATION=1. or the statement specifies both indices (MW[m][j]). the program will try to set them. LASTITERATION). the program does not use the values of DISTANCE and SPEED. You can enter values into volume sets with PATHLOAD VOL[#] = expressions. 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. The program refers to volume sets as VOL[#]. There may be up to twenty volume sets. The ILOOP phase performs MW[#] statements for all Js (J=1. Almost all control statements are valid during the ILOOP phase (that is. The ILOOP stack can contain nearly any of the functions of the Matrix program. and the ILOOP stack must have at least one PATHLOAD statement. set numbering need not be monotonic.6 Highway Program Phases in control statements. ILOOP phase The ILOOP phase performs a zonal loop (I = 1. and then compute T0. For assignment. The Highway program requires a PHASE=ILOOP statement. Zones). unless the statement occurs within a JLOOP block. you must include a PATHLOAD statement. On the other hand. This statement specifies a set of values that the program assigns to the links in a specified path set. adds values to the first volume set (VOL[1]) from matrix 6 in the MATI[1] file. the trips from any I to J may use various paths. ZONES. As J loops. In example 1. the value (normally trips) for I to J from MI. the program determines vehicle time from the final link volumes and the travel times associated with those volumes.6.6 instructs the program to assign the values from the expression “MI.) Example 3 PATHLOAD VOL[4]=MW[5]+MW[6]+MI. Stratifying vehicle distance traveled by average trip speed During a multiple-iteration assignment.6” to each link in the paths from the origin zone (I) to each of the destination zones (J). For each link in those paths.1. For each link in those paths. and times. The paths are based upon the link times in effect during that iteration. VOL[3]=I*10+J Builds paths based on the value of DISTANCE read from the network. PATH=LW.TOLLTIME Builds paths based on the link-work variable.Highway Program Phases 6 internal loop of J=1.1.1.8” expression. VOL[1]=MI. adds values to the fourth volume set (VOL[4]) computed from the “MW[5] + MW[6] + MI.6 will be assigned to links along the path from I to J. ZONES. you must request REPORT VDTSPD to base vehicle distance on average trip speed. TOLLTIME. After all iterations. Example 2 PATHLOAD PATH=LI. distances.DISTANCE. Example 1 PATHLOAD VOL[1]=MI. PATH=TIME Builds paths based on TIME value. (The program assigns a value for each J in: J=1.1.2. In this case. For each link in those paths. adds values to the third volume set (VOL[3]) computed from the “I*10+J” expression.8.2. You might want to estimate emissions based on the average trip speed rather than on the individual link volumes. Cube Voyager Reference Guide 161 . path=.. & J=. Following the assignment..1... & J=. VOL[1]=MI..) ) MW[1] = MI..1 ENDJLOOP VOL[1]=MW[1]. Select-link processing Use the PATHLOAD statement to initiate select-link processing. && b=... Finally...... INCLUDEJ=. The program uses speed to stratify the vehicle distance of travel.. MW[1]=MI. VOL[1]=MI.) PATH=. The program saves the paths for each I-J movement during normal assignment. && b=..1. 162 Cube Voyager Reference Guide ...1. additional schemes do not require additional resources. You can specify multiple stratification schemes. or SELECTLINKGROUP to solve the MW expression only for those destination zones (J) where the specified SELECT… expressions result in a true condition. SelectLink=(a=.6 Highway Program Phases This option requires considerably more processing and might require considerably more disk space. SELECTGROUP.. Example (most efficient) IF (I=. The program uses the final link times to compute the individual trip time and distance.. Example (simple code – inefficient) MW[1]=0 JLOOP ..1. Specify an MW[] expression followed by SELECTLINK.... The IF process will run faster if the zonal ranges are not too complicated..).) || (I=. SelectLink=(a=. Subsequent VOL[] statements can assign any of the select-link matrices to a link’s volume set.1...1. Solving complicated selections is time consuming. The PATH keyword specifies the link values that the program uses to develop the paths. the program retrieves the paths and retraces all the assigned trips along their paths. this illustrates selective gathering IF ((I=. Example (using SELECTLINK) PATH=.ODTRIPS.. the program calculates the average speed for the trip..). If the I-to-J path uses any links in the subarea network. and use INCLUDEJ and EXCLUDEJ keywords to select the desired J values. crossing the cordon line exactly two times. specifying A=range of desired I values and B=range of desired J values. Cube Voyager Reference Guide 163 . and then reference that matrix with the PATHLOAD VOL[] statement. • • 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). Path begins outside the subarea and ends inside the subarea. Path begins and ends inside the subarea. use the following keywords: • • • FILEI SUBAREANETI — Define the region. Use SELECTLINK. Use IF statements to find the desired I.Highway Program Phases 6 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. the program records the computed value for the path’s J in the subarea matrix. the program computes the SUBAREAMAT expression for each J-zone on the path from I to J. After building paths for the current I-zone. 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. PATHLOAD SUBAREAMAT — Specify values to write to the SUBAREAMATO file. FILEO SUBAREAMATO — Define where to save the selected trips. Path begins inside the subarea and end outside the subarea. Clear the “unwanted” I-J pairs. and either exits again. When a path exits the subarea. becomes the origin zone of the extracted record. (For example. If you want to complete special processing on each link following the normal adjustment process. the ADJUST phase automatically follows the ILOOP phase. If a path begins and ends inside the subarea. the B-node of the cordon link used to exit the subarea becomes the destination zone. Multiple records can be extracted for a path. and the destination zone becomes the destination. The A node of the origin zone becomes the origin. enters. This phase computes the congested time (Tc) on each link and revises the link’s TIME values. which the next iteration uses. The intrazonal value for an internal zone will be extracted even though there is no path. or the A node of the cordon link that was used to enter the subarea. Example (subarea trip extraction) PATHLOAD PATH=TIME. the internal zone becomes the destination zone. a path begins outside. but if requested during a non-assignment application.1. SUBAREAMAT[1]=MI. using the polygon subarea network extraction process.6 Highway Program Phases When a path enters the subarea by crossing a cordon link. or terminates an internal zone.) The final matrices are combined values from all iterations of assignment. the Anode of the cordon link becomes the origin zone of the extracted record. but never crosses the cordon line. exits. only 1 iteration is processed. include the Phase=ADJUST control statement followed by the stack of control statements you want to complete. If the path terminates at an internal zone. the internal zone where the path began. and the B node of the exit cordon link becomes the destination zone. you might include ADJUST statements 164 Cube Voyager Reference Guide . SUBAREAMAT[2]=1 ADJUST phase Part of the iteration loop. Most commonly. enters. a single I-I record is extracted. The subarea network is obtained from Cube Base.1. Similarly. . and arrays the program uses. Use PARAMETERS COMBINE to specify the method used: • Equilibrium (the default) Cube Voyager Reference Guide 165 . you configure multiple iterations. this configuration duplicates some volumes. V is the sum of all VOL[] values that appear on any PATHLOAD statement. Though allowed. Citilabs recommends that you let the program determine when more iterations will not result in any assignment improvements. Though you can specify the maximum number of iterations. the program recalculates the COST values using the Cost Function. After processing user-specified ADJUST statements. and the program computes the final volumes by combining the volumes from each iteration..TOLLTIME values.) Congestion is based on the variable V. In initializing statements. variables. The program can use various methods to combine iteration volumes. you might test the value of LINKNO: IF (LINKNO=1). To accumulate summary values during the link loop. computed for each link. Do not use the default computation for V if you configure a standard assignment along with a select-link assignment.) 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. you must properly initialize the values at the beginning of the link loop. LW values based on values revised by the ADJUST process (such as TIME and COST) should be recalculated. those values must be updated to reflect changes made in TIME. You must make the changes to LW. (See “Functions and built-ins” on page 139 for a description of the builtin functions. For example. Use a FUNCTION V statement to override the default computation of V. (You can also test for ITERATION and LASTITERATION.TOLLTIME because the program does not know your intention and cannot adjust the values automatically. Citilabs recommends that you do not alter TIME values with ADJUST statements. By default.Highway Program Phases 6 to list how the normal adjustment process affects each link and to adjust LW values. if you have a set of LW. Most often. If the network is “well behaved. It is impossible to solve directly for Lambda. 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 term assignment is used to indicate the actual accumulation of trips on link volumes. the term “equilibrium assignment” is somewhat of a misnomer. Lambda is a factor between 0 and 1. will not produce significant differences in the system as a whole. Thus. eventually a state of equilibrium is reached. a factor λ (generally referred to as Lambda) is estimated for the iteration.6 Highway Program Phases • • • • Average Weighted average Iterative Summation (often referred to as incremental) Equilibrium assignment is performed within the ADJUST phase. That state is reached when further adjustments in the link costs used for routing. The user can select one of two Lambda search processes using the PARAMETERS COMBINE LAMBDASEARCH = AREA/EQUATION. and in most situations. If a system has a significant degree of congestion. cost involves some measure of time. Note that both processes estimate Lambda so the results might be 166 Cube Voyager Reference Guide . Time is generally the measurable quantity that can be directly related to congestion. Most users tend to think of equilibrium assignment as the process of determining a weight factor for an iteration. equilibrium is reached when there is no ability for individual I-J path costs to improve. To determine the weight to apply to each iteration’s volume in the volume combining process.” and the appropriate processes are included. without causing degradation in other parts of the network. The basic measure of equilibrium is total system user cost. it may be difficult (practically impossible) to reach a true state of equilibrium. so it is estimated using a linear approximation method. In theory. most equilibrium formulations are based upon time. If the AREA search process is used. the results will be quite similar. 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’. In most cases.TCCOEFF. If a standard function for computing TC is used. This process provides a Lambda calculation that is up to 6 digits in precision. but the EQUATION method can save considerable computation and I/O time. the program solves the expression for only a limited number of Lambdas.TCEXP) Cube Voyager Reference Guide 167 . Cost curves computed for incremental estimates of lambda for every link. the estimation process could be considerably more efficient. If the EQUATION search process is used.Highway Program Phases 6 slightly different. the program minimizes the area under all the V vs. where V’= Vk-1 + λ * (VOLk . This value is then used to weight the current volumes: Vk = λ * VOLk + (1.Vk-1). Weighted Average assignment is the same as Average. and the appropriate values of TCCOEFF and TCEXP. EQUI is the default.6 Highway Program Phases Where TC(V’. and the Lambda which provides Y=0 is obtained by interpolation. the PARAMETERS COMBINE= specifies the one to use.TCEXP) is the TC functions evaluated for link volumes V’. There are several iteration volume combination processes available. The resulting curve is examined. Sum assignment is one in which the final volumes are the result of adding the volumes from each iteration. 168 Cube Voyager Reference Guide . prior iteration volumes are not considered. 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.TCCOEFF. Average assignment simply keeps a running average of the volumes on each link. Iteration volumes are factored by the equilibrium weights computed for each iteration. Iterative assignment keeps only last iteration volumes are output.λ)*Vk-1. but the user can specify a specific weight for each iteration. This is traditionally known as incremental loading. The available processes are: Process EQUI AVE WTD ITE SUM Description Equilibrium assignment. If Iteration > 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. except TIME is not altered). Root mean squared error of the differences in V between iterations. There are several tests that can be made to determine if more iterations are necessary. obtain prior combined iteration volumes (CVOL is prior V). VEk is the equilibrium weighted volumes for iteration k and COSTEk is the cost based on the equilibrium volumes VEk. the turning movements in the network. if appropriate. NumLinks (multiple passes if equilibrium is specified): Obtain link values (as in LINKREAD and LINKREAD stack. Cube Voyager Reference Guide 169 . RGAPk (SUML(VEk-1*COSTEk-1) . 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. Apply the appropriate TC and Cost Functions (based on LinkClass) to compute revised Time and Cost.Highway Program Phases 6 Convergence testing is not performed for Combine=Sum assignment. Sets a fixed maximum number of iterations for convergence The ADJUST phase process is as follows: • Major Link loop: Linkno = 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. For example: 170 Cube Voyager Reference Guide . For example if you have specified PARAMETERS GAP=0. 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. 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 because one of the other PARAMETERS has reached its default minimum. Note that all of these PARAMETERS have default values so they do have minimum targets even though the user has not explicitly coded them. 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.001. convergence is considered to be achieved if ANY of the above PARAMETERS minimum values are obtained.6 Highway Program Phases If this is an Equilibrium pass. combine V with prior combined Vs Process LinkAdjust stack (if present). compute link contribution (Y) to Lambda estimations.001 in order to stop further iterations beyond this value of GAP but have set no other controls. Else if Iteration > 1. End Major Link Loop. • Determine if this is to be the last iteration: If Iteration = MaxIters: LastIteration = 1. Or. the assignment may stop in less then 20 iterations and before GAP<0. and recompute Cost. 001 or 99 iterations were preformed. If you would like to specify alternate rules for when the program determines convergence is reached. the program checks if additional iterations are necessary.001. follows the ADJUST phase in each iteration. GAP=0. process the stack statements in the CONVERGE Phase until BALANCE=1 or MAXITERS is reached. RELATIVEGAP=0. the turning movements in the network. if true). this can now be achieved by using the CONVERGE phase. • CONVERGE phase This phase. RAAD=0. if specified. At the end of the ADJUST phase. if appropriate. Cube Voyager Reference Guide 171 . RMSE=0 Would continue performing iterations until GAP<=0. VEk is the equilibrium weighted volumes for iteration k and COSTEk is the cost based on the equilibrium volumes VEk.Highway Program Phases 6 PARAMETERS MAXITERS=99. • If PHASE=CONVERGE is present. There are several tests that can be made to determine if more iterations are necessary. Convergence testing is not performed for Combine=Sum assignment or for Iteration=1. 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. See “CONVERGE phase” for examples of specifying alternate convergence rules. AAD=0. or LastIteration: Write Neto. If Convergence satisfied by BALANCE=1 (LastIteration set to Iteration. That will indicate to the program that further iterations are not to be undertaken.6 Highway Program Phases RGAPk (SUML(VEk-1*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.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. the test statistics will begin to oscillate near the desired test limit. Some networks may never be able to reach a true balance because there is too much congestion. Things can not be completely smooth because a slight adjustment in a few links may cause a large shift in a slug of traffic. 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. Sometimes. or if further assignment iterations will improve the assignment depending on the assignment method used. the script should set the variable BALANCE to 1. When the results are satisfactory. The CONVERGE phase process is provided to allow the user to program his/her own method of setting convergence. or there is insufficient capacity in certain parts of the network. 172 Cube Voyager Reference Guide . and may never reach a desired result. The user can write script to determine if the desired measure has been met. Root mean squared error of the differences in VE between iterations. Variables available for BALANCE Variable GAP RGAP AAD RAAD PDIFF RMSE Description The GAP for the current iteration. Must be indexed for previous iterations The RMSE for the current iteration. various variables and functions are available. BALANCE is automatically set to 0 when the phase begins. Must be indexed for previous iterations The RAAD for the current iteration. the program will continue until MAXITERS is satisfied. may be reset anytime A variable initialized to the value Parameters PDIFF. may be reset anytime GAPCUTOFF RGAPCUTOFF AADCUTOFF RAADCUTOFF PDIFFCUTOFF RMSECUTOFF Cube Voyager Reference Guide 173 . Must be indexed GAP[] for previous iterations The RELATIVEGAP for the current iteration. Must be indexed for previous iterations A variable initialized to the value Parameters GAP. the standard tests are not performed. may be reset anytime A variable initialized to the value Parameters AAD. may be reset anytime A variable initialized to the value Parameters RELATIVEGAP. may be reset anytime A variable initialized to the value Parameters RMSE.Highway Program Phases 6 Note that if PHASE=CONVERGE is detected within the script. Must be indexed for previous iterations The AAD for the current iteration. termination will be determined by the value of BALANCE after the phase is completed. may be reset anytime A variable initialized to the value Parameters RAAD. If BALANCE is never set to 1. To help the user set BALANCE. Must be indexed for previous iterations The PDIFF for the current iteration. Function that results in the minimum change in GAP between the last n iterations. Function that results in change in RMSE between the specified iteration (the required argument) and the previous iteration. Function that results in the average GAP between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. RGAPCHANGE AADCHANGE RAADCHANGE PDIFFCHANGE RMSECHANGE GAPMIN GAPMAX GAPAVE GAPCHANGEMIN GAPCHANGEMAX GAPCHANGEAVE 174 Cube Voyager Reference Guide . Function that results in the average change in GAP between the last n iterations. Function that results in the maximum change in GAP between the last n iterations. Function that results in the maximum GAP between the last n iterations. Function that results in the minimum GAP between the last n iterations.6 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. where n = the number of iterations to process. Function that results in change in AAD between the specified iteration (the required argument) and the previous iteration. where n = the number of iterations to process. Function that results in change in RELATIVEGAP 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. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in change in RAAD between the specified iteration (the required argument) and the previous iteration. where n = the number of iterations to process. 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. where n = the number of iterations to process. Function that results in the minimum AAD between the last n iterations. Function that results in the average change in AAD between the last n iterations. RGAPMAX RGAPAVE RGAPCHANGEMIN RGAPCHANGEMAX RGAPCHANGEAVE AADMIN AADMAX AADAVE AADCHANGEMIN AADCHANGEMAX AADCHANGEAVE Cube Voyager Reference Guide 175 . 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 maximum AAD between the last n iterations. 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 AAD between the last n iterations. where n = the number of iterations to process. 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 RELATIVEGAP between the last n iterations.Highway Program Phases 6 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 average change in RELATIVEGAP between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the minimum change in RELATIVEGAP between the last n iterations. Function that results in the maximum PDIFF between the last n iterations. Function that results in the minimum change in PDIFF between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. RAADMAX RAADAVE RAADCHANGEMIN RAADCHANGEMAX RAADCHANGEAVE PDIFFMIN PDIFFMAX PDIFFAVE PDIFFCHANGEMIN PDIFFCHANGEMAX PDIFFCHANGEAVE 176 Cube Voyager Reference Guide . where n = the number of iterations to process. Function that results in the maximum RAAD between the last n iterations.6 Highway Program Phases Functions available for BALANCE (continued) Function RAADMIN Description Function that results in the minimum RAAD between the last n iterations. Function that results in the average change in PDIFF between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. Function that results in the minimum PDIFF between the last n iterations. Function that results in the maximum change in RAAD between the last n iterations. Function that results in the minimum change in RAAD between the last n iterations. where n = the number of iterations to process. where n = the number of iterations to process. where n = the number of iterations to process. 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 maximum change in PDIFF 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. 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 maximum RMSE between the last n iterations. Function that results in the minimum change in RMSE between the last n iterations.009) BALANCE = 1 ENDPHASE Example . where n = the number of iterations to process. where n = the number of iterations to process.Highway Program Phases 6 Functions available for BALANCE (continued) Function RMSEMIN Description Function that results in the minimum RMSE between the last n iterations. Function that results in the average change in RMSE between the last n iterations. 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. 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 maximum 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. In this example the assignment would stop only when ALL criteria fall below their specified values.006 && GAPCHANGEMAX(3) < 0.009 && ABS(GAPCHANGEMIN) < 0. PHASE=CONVERGE IF (GAP<GAPCUTOFF & RGAP<RGAPCUTOFF & AAD<AADCUTOFF & Cube Voyager Reference Guide 177 . Do not even test for Iterations 2-5 IF (GAP < GAPCUTOFF) BALANCE = 1 BREAK ENDIF IF (GAPCHANGEAVE(3) < 0. where n = the number of iterations to process. where n = the number of iterations to process. 6 Highway Program Phases RAAD<RAADCUTOFF & RMSE<RMSECUTOFF & PDIFF<PDIFFCUTOFF) BALANCE = 1 ENDIF ENDPHASE 178 Cube Voyager Reference Guide . Control statement ABORT ARRAY BREAK COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FUNCTION GOTO IF .. ENDLINKLOOP LOOKUP LOOP ..... ELSEIF .. 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. 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 .. ELSE .Highway Program Control statements 6 Control statements The following control statements are available in the Highway program. load path.. ENDJLOOP LINKLOOP . ENDLOOP PARAMETERS PATHLOAD PRINT PRINTROW PROCESS .. ENDIF JLOOP ..... 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.. VAR=size. they 180 Cube Voyager Reference Guide . It normally is not used. String values cannot currently be stored in an array.6 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. An array is different than a variable in that it represents vectored data. it should include an index []. ABORT keyword Keyword Description |S| Optional message that can be printed when the program terminates. and if the index exceeds the size. but allows for termination due to some conditions that can be detected in the process. VAR=size Use ARRAY to allocate user arrays that are to be used in the process. MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager.Intrazonal present in MW[1] ARRAY Declares user single dimension arrays. ARRAY statements are not dynamic (stack oriented). Arrays can be useful for different processes. Values stored to arrays must be numeric. the run should be aborted. For example: if it is discovered that an LOS matrix is empty when it should have data. When an array is referenced. MSG Example IF (MW[1][I] != 0) ABORT . the program may fatally terminate. VAR must be a unique name. NODES. all the cells in the array are set to the same value. The size following the keyword is the highest index possible for VAR. or a special name. ARRAY keyword Keyword Description |I| Name of the variable that is to be allocated according to the specified size. the script immediately passes control to the statement after the associated loop.CLASS] + VOLTOT ARRAY VMT=LINKS BREAK Breaks out of a loop. the script terminates processing for the I zone but does not bypass output and zonal reporting statistics. If BREAK is within a LOOP .. If BREAK is not within a LOOP or JLOOP block. ENDJLOOP block. Special names are: ZONES. control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1)..Highway Program Control statements 6 are allocated prior to any stack operations.. LINKS (or NUMLINKS).. Upon encountering BREAK. Size may be either a numeric constant. jump to IF statement Cube Voyager Reference Guide 181 . VAR Example ARRAY sum_toll=20 sum_toll[NI. When an array variable appears in a SET statement.CLASS] = sum_toll[NI.3 IF (condition) statements ELSE BREAK ENDIF . ENDLOOP or JLOOP . Example LOOP L1=1. 182 Cube Voyager Reference Guide . or 1. the program only solves the expression one time only. COMP keywords Keyword MW Subkeyword |KN| Description Value for a working matrix. The program solves the expression one time only. INCLUDE=list of J zones. EXCLUDE=list of J zones Use the COMP statement to compute variable and work matrix values. VAR=expression MW[n]=expression. The program solves the expression for all values of J (1 through Zones). or matrix element from an expression. Matrices can contain up to MAXMW rows. must be between one and Zones. You can specify this keyword in two formats: • MW[n] — Defines the value for row n of a working matrix. no more processing for this origin zone COMP Computes a variable.6 Highway Program Control statements ENDLOOP IF (condition) BREAK . if not. The index n may be either a constant or a variable name. • MW[n][c] — Defines the value for column c in row n. Within a JLOOP statement. with J being the loop’s J if within a JLOOP. matrix. c. as indexed by n. with J being the value of the loop’s current J. The second index. filtering values indicated by any INCLUDE or EXCLUDE lists on this statement. the program compares J to the values in the EXCLUDE list. Specified values can range from 1 to the highest zone number. the program does not evaluate or store the expression for that J. Specified values can range from 1 to the highest zone number. Not permitted if COMP statement within JLOOP .. the program does not evaluate or store the expression for that J. Not permitted if COMP statement within JLOOP . Values of J included when computing the MW[n] expression. Filter applies to all MW[n] values on the COMP statement. INCLUDE |IP| Optional. As the program internally loops on J..Highway Program Control statements 6 COMP keywords (continued) Keyword Subkeyword EXCLUDE |IP| Description Optional. Always processed after INCLUDE subkeyword. Filter applies to all MW[n] values on the COMP statement. ENDJLOOP block. Values of J excluded when computing the MW[n] expression.. If the current J is on the list. the program compares J to the values in the INCLUDE list. As the program internally loops on J. If the current J is not on the list. By default all zones are included. Cube Voyager Reference Guide 183 . By default no zones are excluded. ENDJLOOP block.. EXCLUDE is processed after INCLUDE. unless their first appearance as a result in a COMP statement is with an expression that results in a character string. the filters apply to all MW[]= values. messy -. jkl is declared numeric .n.n.6 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 expression is solved one time for each encounter. the variable must be a character string variable. or the value of the JLOOP J. Examples: abc = '123' def = 123 abc = def . If expression results in a character string.matnum 184 Cube Voyager Reference Guide . INCLUDE and EXCLUDE may not be specified within a JLOOP. xyz is declared a string If a COMP statement includes any INCLUDE or EXCLUDE filters.name MI. The name may be as long as desired (within reason). and special matrix functions on the statement. All variables are assumed to be numeric variables. valid abc = abc + def . invalid: xyz is declared a string (later) . invalid: abc has been declared a string abc = abc + '456' . no matter where they appear on the statement.don’t mix jkl = 1 jkl = xyz xyz = 'xyz' . Special matrix variables MW[] MI. with J being either one (not in JLOOP). name matrix. and underscores (_). max.n.n. the column index (not explicitly expressed) will be supplied as J. the column index (not explicitly expressed) will be supplied as J.n. “General Syntax. they should be used only as VAR = ROWFUNC(#).matnum[Cexpression] is a variation. log. ZI. the column index (not explicitly expressed) will be supplied as J. Value from the MATI[n]. The row index [n] and the matnum must be constants.Highway Program Control statements 6 The expression is a standard Cube Voyager numeric expression. Valid matrix names contain only alphanumeric characters. the column index is computed.n. then you must include the entire MI matrix reference in double quotes to recognize the name. must be a constant. some special purpose functions are available. Normally.name[Cexpression] is a variation. ZI.matnum matrix. The row index [n]. sqrt — see Chapter 3. exp. If matrix names have spaces.matnum Value from the MI[n]. but there are some special variables that may be used within it: Matrix variables Variable MW[Rexpression] Description Value from any work matrix. ln. Rexpression may contain nested MW[]. The matrix-oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists). For example: MW[1]="MI.name matrix. the zone index is computed. Value from the ZDATI[n]. be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression. spaces.n. round. the column index is computed. int. MI.” for more details). the zone index (not explicitly expressed) will be supplied as I.1HBW TRIPS" MI. MI. Cube Voyager Reference Guide 185 . min. and should not be used within JLOOP blocks and MW[]= expressions.name[Cexpression] is a variation.n.name MI.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. NOTE: Zeros are treated as regular numbers in LOWEST function. they will be processed in appropriate order.. Example: DUMMY = ROWFAC(3. The function format has two advantages: coding is much easier. including only cells with values greater than or equal to lo. With z. Sum of lowest n cells.z. In the following matrix function descriptions. and exclude the values for J=z.hi) LOWEST(mw.hi” is allowed.6 Highway Program Control statements Most of these functions could be duplicated with a combination of MW[]= statements.lo. Matrix functions Function LOWCNT Description The actual number of cells that was used in the summary is stored in the variable LOWCNT.5) + ROWFIX(3) will factor matrix 3 and then convert it to integer. without any diagnostics. The range of arguments is to provide for most types of situations.z. Warning: Dividing by LOWCNT if it is 0. the first argument (mw) indicates the work matrix to process. LOWEST(mw.lo. and lo is supplied. Combining functions on a single statement is permissible. ) 186 Cube Voyager Reference Guide . specific zones can be excluded. and processing is more efficient. If an invalid argument is detected by a function. Lo and hi are inclusive values.n.n. including only cells with values greater than or equal to lo.. With lo and hi. This exclusion is in addition to any that may be on an EXCLUDE list. normally. and less than or equal to hi.. Sum of lowest n cells. and hi is not.1.. Sum of lowest n cells. it is possible to exclude possible dummy zones that may appear as zero in the row.hi. Since all MWs are initialized to zeros. LOWEST is quite useful for computing an intrazonal value based upon the proximity to the nearest zones. and must be specified. will cause a program error message (too many will be fatal). the intrazonal cell (I) would be excluded. caution should be exercised when applying LOWEST function with no range specified.. the function will return a zero..n) LOWEST(mw. and less than or equal to hi.z. If “lo. hi will be set to lo. Number of cells with values not equal to 0 Number of cells with values greater than or equal to lo. can include 0.s1.hi) ROWDIV(d. but include only cells with values greater than or equal to lo. Cube Voyager Reference Guide 187 . Convert mw to integer values (start at column n.lo. including only cells with values not equal to 0.n) ROWFIX(mw.lo.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.hi) ROWCNT(mw) ROWCNT(mw.rnd) Factors the row by fac. with rounding factor = 0). Same as MW[mw] = MW[mw] * fac Convert mw to integer values (start at column intrazonal + 1... Same as: JLOOP IF (MW[s] == 0) MW[d] = 0 ELSE MW[d] = MW[d] / MW[s] ENDIF ENDJLOOP ROWFAC(mw.s) Average cell value.n. with rounding factor = 0). Average cell value. Divide MW[d] by MW[s] making all divided-by-zero cells equal to 0. and less than or equal to hi.fac) ROWFIX(mw) ROWFIX(mw. and less than or equal to hi. Convert mw to integer values (start at column n. using specified rounding factor).Highway Program Control statements 6 Matrix functions (continued) Function ROWADD(d. 47-93 MW[3]=5*A.5.LOWCNT)/2 Example 2 MW[2]=J MW[K]=MW[2] * MW[5]) / SQRT(A*MW[3][MW[22]]) A=1. With a rounding factor of 0 each cell is truncated and its fractional remainder is carried to the next cell. but include only cells with values greater than or equal to lo.lo.6 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. With a rounding factor of 0.01. The optional second argument specifies which cell the process is to end with.hi) Row total.8.93. and less than or equal to hi. B=2. MW[A]=A+B INCLUDE=1-5.452 188 Cube Voyager Reference Guide . Multiply MW[d] by MW[s] Same as: MW[d] = MW[d] * MW[s] ROWSUM(mw) ROWSUM(mw. each cell is rounded to the nearest integer and the difference (original – rounded) is carried to the next cell. MW[K][I%10+1]=ODD. It converts each cell to an integer value after adding the rounding factor and the accumulated fractional portions from the previously treated cells.I)/max(1. Minimum value in the row. EXCLUDE=90.4.s) Maximum value in the row.0. MW[4]=MW[3]*2. ROWMAX(mw) ROWMIN(mw) ROWMPY(d. Example 1 MW[mw][I] = LOWEST(mw. 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. Row total. INCLUDE=1-100. To eliminate this bias. the lowest numbered zones would never get their fair share of the fractions.5. If the process always began at zone 1.401-500. Highway Program Control statements 6 . MW[23]=MI. MW[13]=MI.K2.KINC LOOP L3=L2.3 CONTINUE Jumps to the end of a loop. no more processing for this origin zone LOOP L2=K1. jump to ENDLOOP for L3 ENDLOOP ENDLOOP EXIT Terminates stack processing.2. ENDJLOOP block.1. Example LOOP L1=1. applies to the MW[]s= ABC=LOOKUP(DEF)*3 /* move input matrices to work areas */ MW[11]=MI.. the program goes to the end of I-loop processing. processing for the I zone is terminated. MW[12]=MI. Otherwise. MW[22]=MI... control passes to the appropriate ENDLOOP or ENDJLOOP statement.1.3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE .L2+5 IF (condition) CONTINUE .1. When the program encounters an EXIT statement.1. Cube Voyager Reference Guide 189 .1.1..2. If CONTINUE is within a LOOP .2. but output statistics will not be bypassed. bypassing all intermediate statements. ENDLOOP or JLOOP .3 MW[21]=MI.2. Example IF (expression) EXIT FILEI NOTE: See “FILEI” on page 48 for general information about FILEI and for important limitations when using Application Manager. other matrices have only numbers. Example: MI. the vector form of ZDATI (ZDATI=file1. ZI. and need not be in any specified order. MATI=. and MATI[5].n. If matrix names have spaces.) will be treated as an error. defaults to MATI[1].. For example: MW[1]="MI. spaces.name. Since it is required that ZDATI files have variables explicitly defined for them.1.POP indicates the POP variable from ZDATI[6] file.n. Valid matrix names contain only alphanumeric characters. Cube Voyager matrices can have names and/or numbers.. and underscores (_). and zonal data files have names only. or implicitly.. whereas zonal data is read prior to the initiation of the I-loop.1HBW TRIPS" On the FILEI statement the subscript is either explicitly.name4.6. name designates the matrix name or number. and are identified as MI. The n designates subscript of the file. and must be in origin zone (I) order. Data from MATI and ZDATI files are accessed via stack statements. and MATI[3]=name3.name5 sets up MATI[3].6 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). specified.3 indicates matrix number 3 on the MATI[1] file..name and ZI. file2. then you must include the entire MI matrix reference in double quotes to recognize the name. 190 Cube Voyager Reference Guide . MATI[4]. it doesn’t matter). J will always be in the range 1-zones. a fixed unit penalty.1. the subscript references the column within a row. A prohibition is designated as the constant -1. a set identifier for the movement. For matrices.1. The function section is optional. it may have an additional subscript appended to it to specify a zone number. 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.TRMTIME[I] and ZI.Highway Program Control statements 6 When an input file is used in an expression. and the penalty to be assessed. ZI. This file may be read and kept in memory for use during any path development processes (specified with PATH on PATHLOAD statements). but allows the user to specify that a penalty is to be computed from an expression. or a reference to a function in the function section. the penalties will not automatically be applied during path development. Zonal data can be viewed as having zones rows with one column per zone. respectively. the penalty will be revised between iterations in the ADJUST phase. It is the user’s responsibility to make sure that the penalty values are in the proper scale and units as the paths to which they are being applied. or as one row having zones columns (user’s choice. TURNPENI designates a file that contains intersection movement functions and penalties. For example. the user must specify which penalties are to be applied on each PATH selection. Each record in the movement section designates a specific movement (a-b-c). Cube Voyager Reference Guide 191 . If there is no subscript specified. and for zonal data.6.TRMTIME[J] reference the origin and destination terminal times. it references the nth item in the vector. Even if the file is designated on a FILEI statement. the current value of J is used. The file has two sections: functions and movements. Example: MI.3[I] accesses the intrazonal cell. If a function contains a C variable (movement capacity). In this example. If there were no C affixed to the Func1 on the movement record. the C would be considered as 0 in the computations. and be increased according to the T/C ratio. the initial penalty would be 2. T will automatically be the sum of all loadings. standard functions. PrevPen.6 Highway Program Control statements Turn functions are designated as numeric expressions that may contain constants and the variables: T. C. PrevPen. T. it is 0 at the first iteration. T[1] would indicate the turning volume associated with any PATHLOAD VOL[1] statements. If the 2 unit penalty was to remain in effect for all iterations. with C=500.00). Care must be taken if a fixed penalty is to be established for the first iteration. T[0] and T are the same variable. but is the result of the T=expression on the TURNS statement after the first iteration. For example: Func1=MAX(2.00. T is vectored (that is.) TURNPENI function records are structured as: FuncName=expression. 192 Cube Voyager Reference Guide . and it would vary after the first iteration. T is the turn volume at the intersection (it may alternatively be named TURN).T/C*5. C. C is obtained from the record in the movement section as an argument of the function. (Warning: Be careful not to create divided-by-zero errors when applying functions with C=0. 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. This is usually done by using the MAX function in the expression. To apply the above Func1 (2+T/C*5). The name is what the user desires. since T would be 0 on the first iteration. the expression would be: Func1=2+ T/C *5. C is the capacity of the movement. If a T is specified with an index for which there is no PATHLOAD VOL[index]. the movement record would be coded as: 100 200 201 0 Func1(500). the value of T[] in the expressions will be 0. and PrevPen is the penalty that was used in the previous iteration. it may contain an index []). If there is no TURNS statement. T is the total volume for the movement. and the expression is any valid numeric expression that may contain numbers. and then dynamic values are to be used after the first iteration. comma). Turn penalty records may Cube Voyager Reference Guide 193 . It is used to convert the assigned volumes into units of per hour.” N specifies a list of nodes where the intersection modeling is to be invoked during the ADJUST phase. the penalty is assumed to be 0. when the movement is detected and PENI= is specified in the PATHLOAD statement. it is applied any time that penalties are in effect. JUNCTIONI designates a file or Cube Geodatabase network containing descriptions of junction models. “Intersection Modeling. and the turn penalty set numbering system applies. However. A is the entry node to the intersection. There may be up to 9 records (sets 0-8) for the same movement. no matter what the designated sets are. invoking intersection modeling for a node where there is no model description has no effect. if there is a set 0 for the movement. and it is one of parameters of the queuing delay equation. Then it will check all the other possible sets for the movements. the penalty for the highest set number that matches the highest PENI designation for the PATH process will be used. The SET keyword designate the turn penalty set to contain the model results. If the set number is 0. and will be reported on the TURNVOLO file. The format of the file is discussed in Chapter 7. Executing a junction model produces turning delays that may be applied during the next iteration of capacity restraint. and C is the exit node. During path building.Highway Program Control statements 6 TURNPENI movement records are structured as: A B C Set Penalty (one set per record). Set is a number in the range of 0-8. PERIOD is the model period in minutes. If there is no set 0. the penalty process will automatically apply set 0. The records are white space delimited (space. B is the intersection node. 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. it there are additional sets. This form of output is similar to a set of turn penalties. or Tranplan binary matrices. The input demand matrix should be in units of vehicles (or PCU) per model period. The link variables from the network are referred to as LI. If specifying a Cube geodatabase network stored in an MDB file. Specifies the nodes where intersection modeling is to be invoked. Duration of the model period in minutes.name.6 Highway Program Control statements be applied with higher or lower priority (that is. the NETI keyword designates the filename followed by a backslash and the name of the Cube geodatabase network. Only those nodes that both have a model description and are listed in this list are actually modeled. MATI NETI |KFV20| |KF| Specifies the input matrix files. MINUTP. A junction model that is not invoked has no effect. FILEI keywords Keyword JUNCTIONI Subkeyword |KF| Description Specifies the input junction file or Cube Geodatabase network. the JUNCTIONI keyword designates the filename followed by a backslash and the name of the Cube Geodatabase network. set number) than the calculated delays. Equivalent to the FILE keyword of the LOOKUP control statement. Invoking intersection modeling where there is no junction described has no effect. It MUST be a Cube Voyager or TP+ binary network. Specifies the input highway network file. Note if intersection data is loaded from a Cube Geodatabase network. TP+. The files must be Cube Voyager. You must index LOOKUPI. or a Cube geodatabase network stored in an MDB file. 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. JUNCTIONI N |IP| JUNCTIONI PERIOD |R| JUNCTIONI LOOKUPI SET |I| |FKV999| 194 Cube Voyager Reference Guide . In most cases the network will be one created by the polygon subarea network extraction process in Cube. The specified files are toll-point to toll-point records and may be input as DBF. TOLLMATI |KF10| Specifies the input toll matrix files. the subarea will be set up properly. TOLLMATI ENTRYGATE |S| Field name or field number on the input TOLLMATI file that holds the entry toll gate numbers. the ENTRYGATE value must be a field name from the input table. Valid value range for entry toll gate numbers is 1-999. If Cube is used to create the subarea network. Cube Voyager Reference Guide 195 . If the input file is a DBF or MDB table. the first field on the input file will be used. with the proper node renumbering and cordon link specification. See “Path-based tolls” on page 151. If the input file is a delimited ASCII file then the ENTRYGATE value is a field number on the input file. This keyword is used in conjunction with the FILEO SUBAREAMATO = and PATHLOAD SUBAREAMAT[] = expressions. 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. See “ILOOP phase” on page 160 for details about subarea processing. MDB table or delimited text records. the results will be unpredictable.Highway Program Control statements 6 FILEI keywords (continued) Keyword SUBAREANETI Subkeyword |KF| Description Specifies a file that contains subarea network information. If ENTRYGATE is not specified. 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. All links with a non-zero value for this attribute are considered part of one or more closed 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. If the input file is a delimited ASCII file then the EXITGATE value is a field number on the input file. NETI link attribute that contains the exit gate numbers. the second field on the input file will be used. The TOLLFACTOR provides a method for quickly factoring tolls for sensitivity analysis. 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 entry gate numbers. one for each toll set. Valid value range for exit toll gate numbers is 1-999. 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. If EXITGATE is not specified. If specified the factor is applied to all toll values in the TOLLMATI file for the set. The numbers in this link attribute can be used to correspond to one or more unique toll systems in the network. the EXITGATE value must be a field name from the input table. The numbers in this link attribute correspond to the numbers in the EXITGATE field of the TOLLMATI file. NETI link attribute that contains the toll road indicator. TOLLMATI NETIENTRY |S| TOLLMATI NETIEXIT |S| TOLLMATI NETITOLLROAD |S| TOLLMATI TOLLFACTOR |R10| 196 Cube Voyager Reference Guide . If the input file is a DBF or MDB table. Up to 10 toll factors may be specified.6 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. rounded to the nearest US quarter dollar)..50. 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 . the TOLLS value(s) must be a field name from the input table. Up to 10 toll value sets may be coded. Specifies the input file that contains the turn penalty functions and movement records. Tolls can be coded as true toll values or in any units the user desires. Field name(s) or field number(s) on the input TOLLMATI file that holds the toll values. For example if a toll. If the input file is a delimited ASCII file then the TOLLS value(s) is a field number on the input file. and a TOLLFACTOR of 1. the third and subsequent fields on the input file will be used for up to 10 toll sets. By specifying TOLLROUND=0. If the input file is a DBF or MDB table. coded in the TOLLMATI file for a particular entry to exit movement is US$1. 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.25. the factored toll value would be US$1.80.2 has been specified to test a 20% toll increase. the applied toll value for this movement would then be US$1. Switch to designate if the penalty values are to be listed to the print file.Highway Program Control statements 6 FILEI keywords (continued) Keyword TOLLMATI Subkeyword TOLLROUND |R| Description Allows for rounding of tolls or factored tolls to the nearest units specified.75 (that is. If TOLLS is not specified. it opens the node database portion of the file as zonal data. J. the fields to be extracted must be named and identified on the ZDATI statement by either relative field number. the program will go through all field names to find a match with one of the following possible zone field names. any fields from the record can be extracted and used by the program. it is not necessary to name the fields to be extracted. I. MDB. or by exact column positions on the records.6 Highway Program Control statements FILEI keywords (continued) Keyword ZDATI Subkeyword |KFV10| Description Specifies the input files containing zonal data. the program will try to determine the zone number field based on file type. TAZ}. Aside from the zone number. (Note: For files with more than one possible zone field from the list above. If 'Z=' is present. Otherwise. the specified field will be used to extract zone number. The specification of zone number field is optional for those two file formats. or a Cube Voyager or TP+ binary network. node numbers (N) will be used as zone numbers by default. ZONA. All fields will be extracted and can be referenced. it will assume ASCII. in the given order: {Z. or a Cube Voyager or TP+ network. There can be up to 10 zonal data files. it is recommended to specify zone number field explicitly to ensure the correct field is used. If the file is of ASCII format. If it can not identify the file as a DBF. DBF. Every zonal record must include a field that identifies the zone to which the record data applies. ZDATI ZDATI AVE1 AVEX01 |SV| |SV| Average of all records. The file format can be any of: ASCII. ZONE. If the file is a database or a Cube Voyager or TP+ network. The first matched name will be used to extract zone number. The field that contains zone number must be specified using 'Z=' keyword. in the script. Average of all records. 198 Cube Voyager Reference Guide . For DBF and MDB files. MDB. Zonal data is data which is specific for each zone. where the value from the file records is not 0. by existing field names from the input file. When the program detects a Cube Voyager or TP+ network file. The program will try to detect what type of file it is.) For Cube Voyager or TP+ network files. Z=1-5. These are all be valid. For text files. each name value MUST end in a number.POP=#2 would be invalid because Z specifies fixed format. Value with which to initialize the array for the named variable. or the field is blank on a record. because Z specified triggered delimited format.POP=#2.Highway Program Control statements 6 FILEI keywords (continued) Keyword ZDATI ZDATI Subkeyword CNT1 DEFAULT |SV| |R| Description Count of the records that contain the variable. name=name would be the standard. All names must be specified with the same format. Only the variables named will be extracted. If the first value is a number. Identifies a data variable that is to be extracted from each record. this value will be used. the value assigned to name is either a field number (delimited format). delimited format is assumed. otherwise. If delimited format is specified. In most dbf cases. the first name value (including Z) establishes the format. Then. or the columns (fixed format) where the variable is located on the record. AREA=3. It doesn’t matter what string precedes the number (the value need not be prefixed with a string). SALES=xxx4. If the file is a dbf. Minimum value from all the records. Directly from the record from the FILEI with the highest index []. Directly from the record from the FILEI with the lowest index[]. Maximum value of all the records. Example: Z=#1. if there are no records for a zone. the value for each name is the name from the dbf dictionary. fixed format is assumed. ZDATI ZDATI ZDATI ZDATI ZDATI FIRST1 LAST1 MAX1 MIN1 NAME |SV| |SV| |SV| |SV| |S| Cube Voyager Reference Guide 199 . but it is not necessary to keep the same names. MINUTP binary matrix files 200 Cube Voyager Reference Guide . Caveat: The program establishes a buffer to read file records into. Z is a special case for name= (below). TPP binary network file MATI=test11. A variable may appear in only one keyword list.6 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.net . Sum of all the records.dat . Example NETI=network. For delimited files. The second and third values must both be numeric and should be separated by a dash. a dummy variable with a high field number can be specified to generate a larger record length. it is assumed that the value indicates a relative field number on the data record. and if the comparison fails. the record is bypassed.dat. It has to know how long a buffer is required. but ends with a number (Example: #1). The program will compare a field from each record with the string specified in SELECT[1]. The second SELECT value specifies the field to be compared with. but with delimited format. Identifies where the zone number identifier is found on each data record. ZDATI ZDATI SUM1 Z |SV| |S| 1. and an optional third value can be specified to designate the ending column. If the second field is not numeric. This selection is not used if SELECT is not specified. The third value is ignored if the second value is a free field definition. If the estimated length is inadequate. the required length is known. test12. it designates the beginning column of the comparison field on the input record. Z MUST be specified. If the value is a number. even if the file is a dbf. The values for the variables will be obtained only from file records that contain the variable. Indicates a process to use in obtaining the value for the variables that are listed following the keyword. that field is the comparison string. With DBFs and fixed format records. the record length is estimated by multiplying the highest field number by 10. the required length can not be estimated exactly. any variables that are not in any list will be set to LAST. Requested matrices are written for every origin zone for every iteration.Z=1-5.popsr=56-65.popfemale=26-35.DUPLEX=3. but are combined into a single “combined” matrix at the end of the application. there would be no use in running the program if there was no way to obtain the results.RETIREMENT=6 ZDAT[4]=pop. A single network with appended volumes and associated variables is written at the end of the application. By default the NETO file will contain all the input variables from NETI plus the variables V.Highway Program Control statements 6 MATI[4]=tppltrips. CONDO=5.pen.popmale=16-25. poptotal=sum.txt. popmale=cnt FILEO Specifies files that the Highway program outputs. Z=#1. A turning volume file must be requested if a TURNS statement is used.poptotal=6-15. VT.pop19-65=46-55. 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. CSPD Cube Voyager Reference Guide 201 .mat . VC.MULTI_FAMILY=4. TIME. There MUST be a NETO specified if assignment is to be made. TPP or MINUTP matrix file TURNPENI=time.txt.DU1=#2. popyouth=36-45. MISSINGLINK=1 ZDATI[1]=housing. Thus.array or li. the NETO appended variables will have an appended number that is one greater than the highest _# from NETI.array. 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. TIME_1.array or an li. V1T_1 etc.array. VT and VnT are the non-directional (twoway) counterparts of V and Vn. V1_1. FILEO keywords Keyword ESTMDATO ESTMDATO NAME Subkeyword |F| |SV| Description Specifies the file name for the output screenline data file (*. VDT (vehicle distance traveled). VT_1. VC_1. If using COUNTVAR. then do specify VAR.DAT) that is required by Cube Analyst. The value may be an lw. VHT (vehicle hours traveled) and a Vn. (Non-directional volumes can be turned off using NETO EXCLUDE=T_. and VnT for every VOL[n] specified on any PATHLOAD statements. There need not be a name for each screenline.6 Highway Program Control statements (congested speed). but it is suggested that they be included to help in documentation of the file. If the input network is a binary network. the first assignment variables will be named V_1. Specifies the link array that contains the counts. Alternate to using VAR. If the NETI file contains any variable whose name ends in _#. Specifies the link array that contains the count confidence values. A default name of “SL A-B” will be supplied by Cube Voyager if no NAME is provided for a screenline. If the NETO file is being written to a Cube geodatabase network in an MDB file.) These appended variables will have an assignment number appended to their names. The value may be an lw.ICP) that is required by Cube Analyst. Links that have values in this array will be trapped for inclusion in the matrix estimation. If there were no prior assignment result variables appended to the link records. Specifies the names for the screenlines in the ESTMDATO file. Specifies the file name for the output intercept file (*. the source geometry for links in the output network will come from the geometry of the input network. ESTMICPO ESTMICPO ESTMICPO CONFVAR COUNTVAR |F| |S20| |S20| 202 Cube Voyager Reference Guide . the assignment number will be 1. Specifies the link array that contains the counts. ESTMICPO VAR |S20| Cube Voyager Reference Guide 203 .Highway Program Control statements 6 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).array. However. The most common application would be with selected link matrices. 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 value may be an lw.array. If there is no value in the array for a link that has a count. If SCREENLINE is not specified. the program will assign a screenline number to it automatically. do not use COUNTVAR. the program will assign a unique screenline number to each link with a value in the VAR array. Links that have values in this array will be trapped for inclusion in the matrix estimation.array or an li.array or an li. The value may be an lw. the link is ignored in the matrix estimation. Valid range is 1 to 10. Specifies the filename for the MATO specified. If using VAR. Citilabs recommends replacing all instances of VAR with COUNTVAR. Replaced by COUNTVAR.000. If a link has a value in the SCREENLINE array. but does not have a value in the VAR array. JUNCTIONO MATO MATO COMBINE |F| |FV20| |?| Specifies the file name where the results of junction modeling may be stored for display. Specifies the link array that contains screenline numbers for the links. Example: MO=1-5. The value can be a number (0-9) or the character D or S. If no DEC value is defined for a matrix. Specifies the names for the TP+ and Cube Voyager matrices. while S indicates single precision floating point. Each MO does not require a name. “Matrix Program. The output matrices are numbered monotonically beginning with 1. the default value will be integer with 2 implied decimal places. The letter D indicates that the cells are to be stored in double precision floating point format. The highest implicit or explicit index establishes how many matrices will be included in the file. There is a separate DEC for each MO. All internal work matrices are maintained in double precision floating point format (eight bytes per cell).” for a more detailed explanation of the possible binary options. MO[20]=1. Valid matrix names only contain alphanumeric characters. Nine of the matrices (11-19) will be dummy because no data was entered for them. The reader is urged to read the description of FILEO MATO DEC in Chapter 9. and underscores (_). MO[6]=31 establishes that 20 matrices will be written. The same MW may be included more than one time. A number value indicates the output matrix cells are to be integerized with that many decimal places preserved. but can be written to MATO files in different formats in order to keep the storage requirements to a minimum. Cube Voyager programs reading the file can reference the matrices by name and/or number.6 Highway Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword DEC |SV*| Description Specifies the format for the MOs. MATO FORMAT |S| MATO NAME |SV| 204 Cube Voyager Reference Guide . MW may be indexed. but care should be taken to not leave holes in the final list. but including names helps document the file. DEC is not applicable when FORMAT=MINUTP is specified. spaces. 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.11-15. there must be NETO if assignment is being performed. TIME_5.TIME. APPEND=5 would cause V. 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. Alternatively. etc. The NETO can be a binary Cube Voyager/TP+ network. NETO APPEND |I| NETO NETO DEC EXCLUDE |I| |S20| NETO INCLUDE |S20| PATHO PATHO COSTDEC |F10| |I| Cube Voyager Reference Guide 205 . You can specify a single variable with INCLUDE. this allows for more efficient compressing of the data. VC_5. to be named V_5.Highway Program Control statements 6 FILEO keywords (continued) Keyword NETO Subkeyword |F| Description Specifies the file name for the NETO. Specifies how many decimal places are to be maintained in the cost values when they are written to the PATHO file. Specifies that the variables that are appended to NETO will have their assignment number set to this value. Thus. Values in the range 1-5 are valid.vars and selectively include them in the NETO. Specifies the name of a file upon which paths from a PATHLOAD statement are to be written. VC. Specifies that the NETI variables that have names ending with the specified strings are to be excluded when copying NETI records to NETO. Specifies the number of decimal places to written to the NETO Volume fields.vars named by this keyword will appear in the NETO as LW_NAME_# (# is the assignment number value). V1_5. The link cost values will be rounded to this many decimal places. Default value is 2. 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. The value must range from 1-5. All LW. The variable will appear as name_# in NETO. but this only adds a variable that has the same value in each record..V1.. EXCLUDE=_1 will exclude all the first assignment variables. The intent of this keyword is to allow the user to compute LW. Specifies that certain new variables are to be included in the NETO file. This keyword is ignored if the format is not TPP. The matrices on the file will be the final combination of values from all iterations. if anything else is specified. The values may be 0-9. Specifies the file where binary matrices of values from subarea processing are to be written. 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. PRINTO SUBAREAMATO APPEND |?| |KF| SUBAREAMATO DEC |SV20| SUBAREAMATO FORMAT |C| SUBAREAMATO NAME |SV20| 206 Cube Voyager Reference Guide . The number of matrices will be set by the highest PATHLOAD SUBAREAMAT[] index. or it is not specified at all (normal).6 Highway Program Control statements FILEO keywords (continued) Keyword PATHO Subkeyword ITERS |I| Description Indicates which iterations to write the PATHO file. or D for a doubleprecision number. Specifies the individual names for the SUBAREAMATO matrices. S for a single-precision number. If not specified. or any other value is coded. and TRANPLAN. the default is TPP. the values will default to 2. 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. The zonal configuration for the O/P matrices will be based upon the renumbering scheme obtained from the FILEI SUBAREANETI file. MINUTP. Specifies the desired output format for SUBAREAMATO matrices. Possible values are TPP. Specifies the maximum number of decimal places to retain in the SUBAREAMATO matrices. This keyword is ignored if the format is not TPP. otherwise. 2606 2635 2635 2635 2635 2621 2621 2621 2621 2621 2773 2606 2615 2615 2773 1 1 1 2 1 0.junct TURNVOLO |F| Specifies the filename where the turning volumes are to be written.Highway Program Control statements 6 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.00 0. TURNVOLO TURNVOLO DEC DELIMITER |I| |c| Cube Voyager Reference Guide 207 .junct -1. Please note that the presence of the VARS keyword may alter the overall application of this statement.08 .junct 0. The default format for this file is binary so that Cube can display it directly.15 . each may have a different format. There may be more than one TURNVOLO specified. An example of the output is show below. the TURNVOLO will be empty. Specifies the number of decimal places to preserve when the file is either DBF of TXT. 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.15 . 9=TAB).15 . the file will be delimited with this character. If it is not specified.junct 0. Character that is written in a TXT file. 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. but it may also be specified as a number that represents the desired character (for example. If the value is a character. If this keyword is specified. it should be enclosed within quotes. Users must also specify TURNS to instruct program to accumulate turning volumes. the file will be fixed-field format. See “Example using TURNVOLO” on page 210. or TXT). The DBF header will name the variables that are in the data records...nnnn HIGHWAY date. o if not 3-31 same for T[3]. ExitNode.. 7-64 ”Cube Voyager TURNVOL pppp. and any appropriate T# values. Bnode. 0 if not in data record 1 if T[2] present.6 Highway Program Control statements FILEO keywords (continued) Keyword TURNVOLO Subkeyword FORMAT |S| Description Specifies the format for the file (must be BIN. 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.. • BIN — Binary format that is usable only by Cube.” 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. NOTE: FORMAT=BIN will automatically be reset to TXT if VARS= is specified on the statement. DBF. T[0]. 208 Cube Voyager Reference Guide . It does not make sense to have ESTMO=T on a Cube Voyager Reference Guide 209 . ExitNode. DELIMITER= must be specified. or internally by the program. Each volume will be formatted appropriately. or if there is no FORMAT specified. is to not be written to the file. There may be more than one PATHLOAD statement with ESTMO=T on it. If a delimiter is desired. where n is the highest VOL in the application. T. Specifies which variables are to be written to the file. Optionally. If decimals are to be printed with the values. TURNVOLO INCLUDE0 |?| Flag that when set false indicates that a turn movement with T values all equal to 0. FORMAT=BIN will be reset to FORMAT=TXT. the fields will be in fixed width format.T# — (The user has to know which individual Ts are written to the file). it is suggested that an appended format be specified instead of DEC=. Note that if VARS is specified. Note that VARS= will cause this format to change. the program will determine the size. The default value is true. May be used if both VARS= and FORMAT=DBF are specified. the fields will be written with only the delimiter separating them. There is no header for this file.Highway Program Control statements 6 FILEO keywords (continued) Keyword TURNVOLO Subkeyword FORMAT (continued) Description • TXT — ASCII format either in fixed format or delimited. 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. and may even be repeated): A B C T T1 T2…Tn. the variable name may have a standard PRINT form appended to it (enclosed within parenthesis). The names are aligned with the VARS fields and then placed into the created dbf file. the structure of each record is: Anode. If no DELIMITER. the NAMES may be indexed [] to set the alignment for renaming only specific variables. Optionally. FORMAT=TXT. The T values will be determined either by the DEC keyword. Bnode. Any of the following variables may be specified (in any order. that it will default to TXT. If DELIMITER is specified. DEC=2*2 NAME=SLINK1. DEC=0 TURNVOLO=AlternateA.DAT. VAR=LI.TXT. EXCLUDE=_#1. MO=1. PATHLOAD PATH=TIME.Trn.t2(8. INCLUDECOST=F. DEC=0 TURNVOLO=AlternateA.Trn.Bin. MO=1. FORMAT=MINUTP.COMBINE=Y MATO[3]=DEMO12. NAME=TIME_PATH. DEC=0 TURNVOLO=AlternateA. PATHO=1. DEC=2*2 NAME=SLINK1. format=dbf.DBF.3. format=DBF.5-7 NETO=ALTERNATE.Trn. format=TXT. .'SL#3'.5-7 NETO=ALTERNATE. SCREENLINE=LW. 210 Cube Voyager Reference Guide .2).COUNT. NAME='SL#1'.NET. costdec=2. format=BIN TURNVOLO=AlternateA.Trn. _#2 TURNVOLO=AlternateA.TXT. .c(5).Trn.NET.TXT.TOLL1.DAT.3. iters=0 . names= Enter thru exit Total Cars Trucks Example MATO=TPPTEST.Bin.'. vars=a(5).2) TURNVOLO=AlternateA. DEC=0 ESTMICPO=ESTMO. ALLJ=T FILET Specifies where the Highway program writes various temporary files. format=TXT.'.Trn. format=DBF.COMBINE=Y MATO[3]=DEMO12. MO=1-2. VARS=b(5) a(6) c(6) t(10.Trn.Trn.2) t1(10. _#2 TURNVOLO=AlternateA.TXT. DELIMITER='. NAME[5]='SL#5' Example /* Commands to generate a path file.2).DBF.2).6 Highway Program Control statements PATHLOAD statement that does not have VOL[]= on it.t(8. format=BIN TURNVOLO=AlternateA. FORMAT=MINUTP.SCREENLINE ESTMDATO=ESTMO.MAT.2) t2(8. EXCLUDE=_#1.'SL#2'.MAT. DELIMITER='.pth. MO=1-2.ICP. t1(8.b(5).DAT. PATHLOAD must have the keyword PATHO=# in order to output the path file specified with FILEO PATHO= Example using TURNVOLO MATO=TPPTEST.TOLL1. */ FILEO PATHO[1]=myfile. See “FILLMW” on page 531 for a complete description. It is recommended that they Cube Voyager Reference Guide 211 . the program dictates when they will be processed.Highway Program Control statements 6 PATH FILET keyword Keyword Description |S| Specifies the path to the disk area where any temporary files are to be written.. it will default to the path in the environment variable named TMP. use current directory . and opening the files is: • • • • If the PATH=' '. use current directory. If not specified. or TEMP. FUNCTION Defines special functions. use it. and can be anywhere in the input stream. If not specified. root of c: FILLMW Fills work matrices. Example PATH=' ' PATH=. use TMP. and TMP is. Fatal. If the PATH is specified.\ PATH=c:\ . up a directory . The statements are inoperable by themselves. If the operation fails. V TC COST Use FUNCTION statements to enter single expressions for computing certain values. The logic for determining the appropriate path. PATH The value for PATH is entered as a standard operating system path. If no TC functions are defined then a default TC function is applied. TC stands for congested time.15 and TCEXP defaults to 4 if values are not specified with PARAMETERS. or some combination of both. Each of the other functions is entered with an index [] to indicate which LinkClass it is to be applied to. Specifying TC[1] alters the function. If there is no function for a type. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. In the ADJUST phase. The LINKREAD phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. Computes the congested time on a link by LINKCLASS. The V function may be defined one time only. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. some users may wish to code the functions on a single FUNCTION statement with a block control. V/C. All the functions can be on one FUNCTION statement. In LINKREAD. FUNCTION keywords Keyword COST |NV999| Description Computes the cost for a link. it is applied after the stack statements. The user can also code their own functional form if the BPR form is not what is desired. or they can be on individual statements. The default TC function is the standard BPR with the form: TC[1] = T0 *(1 + TCCOEFF * (V/C) ^ TCEXP) where TCCOEFF defaults to 0. and after the user stack statements are completed. a default function will be used. In general. usually following a TC application.6 Highway Program Control statements be placed prior to the first PHASE statement or within the major phase in which they will be processed. TC |NV999| 212 Cube Voyager Reference Guide . TCCOEFF. COST is processed in the LINKREAD and ADJUST phases to compute the cost. TC[#]=f(T0. To reduce confusion. This is the only way to alter the cost values. it is applied during capacity restraint. TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs). TCEXP) but the user is free to experiment with any forms that make sense to them for their application. 3 TC[1] = T0 * (1 + 0. GOTO label When GOTO is processed. Use care when the :label statement is within a different IF or LOOP block. Example GOTO buildhwy GOTO :buildhwy Cube Voyager Reference Guide 213 . + V[n]).. 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. You cannot place a :label statement inside a JLOOP statement. The target statement must begin with a colon (:). V is assumed to be the sum of all the VOL sets (V[1] + V[2] + ..18 * (V/C) ^ 4)) COST[255] = TIME * 2 } GOTO Jumps immediately to a named statement. For example: if a separate select link VOL set is being accumulated in addition to the total VOL set. T0 * (1. you can use a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP. It is applied in the ADJUST phase. named “:label.” Each GOTO statement must have an associated :label statement. If there is no V function. NOTE: GOTO is not valid in the SETUP phase. However. that VOL set should be excluded from the total volume. Some times the total volume should not be the sum of all the VOLs. flow immediately branches to the target statement.5 + 0.20 * (V/C) ^ 6) TC[201] = MIN(T0*5.Highway Program Control statements 6 FUNCTION keywords (continued) Keyword V |N| Description Computes the total volume on a link after an iteration. Example FUNCTION { V = VOL[1] + VOL[3] + VOL[10]*1. single IF with process 214 Cube Voyager Reference Guide . JLOOP..6 Highway Program Control statements Example GOTO tolls . or MW[]... ENDIF Performs certain operations based on conditions.. You may append the following control statements to a single IF statement: • • • • • • BREAK COMP CONTINUE EXIT GOTO PRINT Example IF (LI. or other IF blocks. use them judiciously. IF expression ELSEIF expression ELSE expression ENDIF Use IF/ENDIF blocks to determine if certain operations are to be performed.b. MI. Although IF expressions can be quite powerful for zonal selection..DIST< 20) LIST=a.name. Lengthy IF expression solutions could be time consuming. the same rules for indexing in a COMP statement are applied.. IF blocks may be nested. :tolls . ELSEIF .LI. ELSE .dist.n.n. If a variable in the expression is MI.n..name. but they may not overlap LOOP. sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples below).. ZI. IF (expression) GOTO :tolls .. It is permissible to go backwards.name or MW[] should realistically only be used within a JLOOP.. IF . Highway Program Control statements 6 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 loop’s control variable, J. Default value is 1. If you do not define Jbeg, you cannot define Jend or Jinc. In that case, Jend defaults to the number of zones in the network, and Jinc defaults to 1. Jend defines the terminal value of the loop’s control variable, J. Valid values range from 1 to the network’s maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1. Jinc defines the increment for the loop’s control variable, J. If not specified, set to 1 or -1, depending on the direction from Jbeg to Jend. • • Because the list of values for J can be expressions, you must separate the values with commas. Enclose expressions containing commas in parentheses. 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 6 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 6 • • • • • • • 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 6 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 LOOP…ENDLOOP blocks to repeat a series of statements. LOOP initializes a variable; ENDLOOP compares the contents of the variable to another value, and branches back to the statement following the LOOP statement if the comparison fails. You can nest LOOP blocks, but you can overlap them with IF blocks. The process differs considerably from JLOOP. The logic is as follows: • At LOOP: Initialize Lvar to Lbeg. Drop through to next statement. 218 Cube Voyager Reference Guide Highway Program Control statements 6 • 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 6 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 6 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 6 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 (see“LAMBDASEARCH” 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 6 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 6 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 6 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 6 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 6 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 6 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 6 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 6 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 6 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 6 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 6 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 link’s information will be stored in MW[10]; the second link’s information will be stored in MW[11]; the fifth link’s information will be stored in MW[6], and so on. LINKIDARRAY LINKID#MW |IP| List of MW numbers where the monotonic succession of numbers of the links (beginning at 1) is to be stored. For example, LINKID#MW=10-13,6,8 means that the number of the first link will be stored in MW[10]; the second link will be stored in MW[11]; the fifth link will be stored in MW[6]. Link arrays can then be addressed directly by using these values. For example, ANODE = A[MW[1]] xxx = LW.xyz[MW[2]]. Cube Voyager Reference Guide 233 6 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 6 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 6 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 Links are coded as A-B (directional) or A-B* (non-directional – link may be traversed in either direction). B. N) can be specified as single values and/or as ranges. A node that must be used in the path. or if N is 105. The process is from left to right. When the multiple value specification is used. the link/node is considered in conjunction with other links/nodes in the path. inclusive. on both an individual link and a total path basis. it is considered as a candidate for processing in the total path. Example: N=100. The expression must be enclosed within parenthesis.200-205 means if N is 100. Any of these variables can have multiple values specified for them. only useful to select links with a path ends at B. Cube Voyager Reference Guide 237 . In the total path basis. A link that must be used in the path.105. the implication is a logical OR amongst the values. Each link/node is processed. The selection is processed by examining each link/node in the path. only useful to select links with a path begins at A. The B-node of a link. L can have multiple links specified. and as long as it does not fail any conditions.Highway Program Control statements 6 PATHLOAD keywords (continued) Keyword MW[] Subkeyword SELECTLINK |s| Description Expression used to determine if the I-J path uses certain facilities. Examples may better illustrate the process. Nodes (A. or if N is a value between 200 and 205. and can contain any of the following variables: A B N L The A-node of a link. Example SELECTLINKGROUP=((grp[1]>3 && grp[2]>=1)|| grp[7]>=5 || grp[6]=2) 238 Cube Voyager Reference Guide . 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. Those totals are available to the expression. The tracing mechanism accumulates how many links of each group code are used in the path. Citilabs recommends using nested parentheses to help categorize the comparison sets. nothing else is really appropriate. 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.6 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. If L=104-105* instead of L=104-105. the expression would be true.57 || L=105-104)) The path crosses any node 100-105. and link (101-102 or 102-101): true ((N=100-105) && (N=8. most any desired combination of path usage can be specified. The expression should contain mostly GRP[] values and perhaps I and J. and node 102 is on the path in any link but the first: false (L=101-102. and (it crosses node (8 or 57) or link 105-104): false. With this type of Boolean selection. MW[] SELECTLINKGROUP |s| Expression used to determine if the I-J path meets select link criteria based upon some level of link group codes.104-200) Link 101-102. Default value is F. Switch to indicate if the path records are to include the cost values (based upon the PATH=array values). 2. Using lower accuracy will speed up the assignment process considerably. LI. 3. 2. T/F flag used with PATHOGROUP to keep partial or full paths for the specified GROUP(s). Valid values are: Cost. If PATHO is not specified.Highway Program Control statements 6 PATHLOAD keywords (continued) Keyword PATH PATH DEC Subkeyword |KS| |S| Description Specifies the link value on which the paths are to be built. or LW. unless this application is path building only (No FILEO NETO=value and no PATHLOAD VOL= value). the PATHO file will not be written for this statement. The generated file can be very large and writing it can cause a considerable increase in running time. or for various post processing capabilities. this can cause a considerable increase in the size of the file.name.name. Specifies the accuracy of the link value on which the paths are to be built. Dist. or for only the I-J paths where an actual assignment is performed. 1. The cost through every link in every path is written. By default this value is false. respectively. or recreation of parts of the assignment. and F. The path file can be used in Cube for analysis of what happened during this assignment. Valid values for DEC are: 0. 4. The file will contain I-J paths generated by this PATHLOAD statement. 3. 1. Time. The number of I-J paths will be determined by the value of the PATHLOAD PATHO ALLJ keyword. 4 decimal places and floating point. especially for larger networks. such as selected link analysis. PATHO ALLJ |?| PATHO PATHO FULLPATH INCLUDECOST |?| |?| Cube Voyager Reference Guide 239 . PATHO |I| Number (#) to specify that a path file is to be written to FILEO PATHO[#]. Switch that indicates if PATHO write processing is to be invoked for all I-J paths. which represent 0. the trace will contain only I. 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). The ADDTOGROUP numbers are typically associated with specific LI. 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. List of numbers (1-32). values via a conditional statement thus links are either associated with the group or not. the same NAME path set may not be written to a file more than one time for an I zone. A PATHO file may have multiple path sets written to it by different PATHLOAD statements. 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. The numbers are associated with GROUP ADDTOGROUP= process in LINKREAD. and the FULLPATH subkeyword is F. You can specify any combination of valid PENI indices. the nodes of the specified links in the group(s). and the FULLPATH subkeyword is T. then the SET keyword is required to reserve one penalty set numbers for use with the junction delays. This can considerable reduce the size of the stored path file. and J. PENI |IP| Specifies the PENI set(s) that are to be used in building this path. and J. If the path does contain a specified link in the group(s). the valid numbers on the TURNPENI file. and there will be no message indicating that this attempted duplication occurred. PATHO PATHOGROUP |IP| 240 Cube Voyager Reference Guide . the trace will contain I. If a JUNCTIONI file is provided.6 Highway Program Control statements PATHLOAD keywords (continued) Keyword PATHO Subkeyword NAME |S| Description Name to be applied to the paths written for this statement. When the trace of a path is examined. However. A set number must be 1-8. 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. all the nodes of any path that uses any of the specified links in the group(s). or LW. if the path from I-J has some portion within the subarea. A random path cost value (for PATH=x) will be selected from the +/. C. See “ILOOP phase” on page 160. For example: SUBAREAMAT[1] = MW[3] specifies that for every J of the current I path set. it applies to all penalties (TURNPENI and SET=).spread range value from the original path cost value (C) as follows: Min(SPREADPERC/100 * sqrt(C). Default is unlimited. If the value for a link is negative. then every link can have a different spread percentage. Default is 10(%). Specifies the maximum spread value allowed for stochastic assignment (COMBINE=PROBIT|BURRELL). This is not specifically related to JUNCTION.) which indicates the percent spread for a link during stochastic assignment. If it is a link array. and in conjunction with SPREADPERCVAR and SPREADPERCMAX. SPREADMAX) SPREADPERC |R| SPREADPERCVAR |S| Single variable or link array (must be LI. There must be an index for the keyword. SPREADPERC specifies the percent spread used to calculate the spread range value. then the SPREADPERC value will be used.Highway Program Control statements 6 PATHLOAD keywords (continued) Keyword PENIFACTOR Subkeyword |N| Description Expression that specifies a factor for all penalties during path building. Stochastic Assignment – used with COMBINE=PROBIT|BURRELL. SPREADMAX |R| SUBAREAMAT |N| Cube Voyager Reference Guide 241 . Expression that the program computes for every J and writes the resulting value onto any subarea extracted records. The highest index sets the number of matrices on the SUBAREAMAT file. a value is to be inserted to the subarea matrix. it must be a numeric constant. Or LW. then the TOLLFACTOR expression must specify a value in minutes/$US. The value has to be a positive integer. An assumed traveler value of time of US$15/Hour would be implemented by setting TOLLFACTOR to 4 (60/VOT). THRUNODE |I| Sets the minimum node number allowed to be included in the path building process. but the program will terminate with error level 2. Specifying TOLLMATI=1. The default value excludes centroids as intermediate points of a path. The default value is ZONES+1. TOLLFACTOR |N| Expression that specifies a factor for converting tolls to COST units. See “Path-based tolls” on page 151. The printed messages will be assigned an error level of 1 less than the second value for all messages except the last one. 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. Units must be (path cost units)/(toll cost units). For example: MAXMSG=50.2 indicates to use toll set 2 on TOLLMATI file 1. all components of this function are typically appropriately factored to be in generalized minutes. 242 Cube Voyager Reference Guide . at the 50th message.2 indicates that the first 50 improper crossings are to be printed at error level 1. If a generalized COST function is used for path building. if tolls are coded in $US and path costs in minutes. Generally paths are built on TIME and TIME is in the units of minutes. For example. Two values are allowed: • • The first value specifies how many messages are printed for the SUBAREAMAT.6 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. The second value specifies the error level to assign to the message when the number of messages reaches the first value. ) array or it can be set to _pathcost to list the accumulated value of the COST function along the path trace.Zones. See “TRACE example” on page 245.) or work (lw.Highway Program Control statements 6 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. J. Example: PATHLOAD PATH=TIME TRACE=(I=1-10 & J=100150) The selected path traces will be listed in the run print file. Most likely. The TRACE expression is evaluated for J=1. but any valid variable can be used. 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. and Iteration. The select expression must be enclosed within parenthesis. the variables used in the expression would be I. Cube Voyager Reference Guide 243 . VOL[2]=MI.5 minutes from the origin zone. but there are many cases. Specifies the name of a link value that should be used in restricting the links that should be included in the VOL assignment. The examples below illustrate these capabilities.TRIPS. if a 3 minute link’s A node were 6 minutes from I. An example would be to obtain what portion of the volume on a link is in cold start mode. It should be noted that when specifying multiple VOL keywords.1. 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.5 would mean to assign only to the links that are within 7.5-99999.6 Highway Program Control statements PATHLOAD keywords (continued) Keyword VOL[] Subkeyword |N| Description Specifies an expression to be solved for J. you must specify the FUNCTION V so the program knows which VOL combinations are to be used for capacity analysis. VOL should be indexed []. VOL[] Valuename |S| 244 Cube Voyager Reference Guide . that is easily accomplished. the index is implied to be 1.5 is 50% of the way from 6 minutes to 9 minutes). only 50% of the trip value would be added to the link volume (7. For example. there will be a single VOL for a PATHLOAD statement. the range would be 0-some number. but if the range were say. TIME=0-7. there may be up to 20 volume sets in a single application of Highway. only the hot running portion of the trip would be assigned. 7. and that the result of the expression is to be assigned to the links in the path generated by the PATH keyword. The values are added to the volumes. but if it is not. In most cases. In that case. The index range is 1-20. where it will be advantageous to have more than one VOL. Or. Normally. In the example. and to determine what types of trips make up the volumes on each link. perhaps it is desired to assign all vehicles. The primary use of this keyword is for air quality analysis. A single range of numbers is required for this keyword. PRINTO=1. li.0).0.DAT FILEI NETI = TEST.J. mw[2]=PATHTRACE(li.flag1=1 ENDPHASE PROCESS PHASE=ILOOP if (I < FromNode) _skiptoI=FromNode ._pathcost(8.Print results to formatted file to check against TRACE JLOOP IF (J=ToNode) .li.2).ToNode(5.TIME mw[1]=PATHTRACE(li.B.4).TIME). Cube Voyager Reference Guide 245 .2) .flag1(3. 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. LIST=FromNode(5.0).mw[1](10. TRACE=(I=FromNode & J=ToNode) PRINTO=2 PRINT=T F=6.TIME(8.'DISTANCE' PRINT CSV=T.Highway Program Control statements 6 TRACE example RUN PGM=HIGHWAY FILEO PRINTO[1] = PATH.3).3).CSV FILEO PRINTO[2] = PATH_TRACE_RPT.A.0).'ToNode'. TO.DISTANCE). build paths for select I PATHLOAD PATH=li. LIST='FromNode'.mw[2](10.DISTANCE(8.lw. PRINTO=1.fac_dist(10. lw.NET PHASE = LINKREAD FromNode=1500 ToNode=1875 lw. TIME. DISTANCE PRINT CSV=T.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.'TIME'.DISTANCE lw. FROM. speeds up process IF (I=FromNode) .fac_dist=10*li. LIST=I. 5 This first PATHLOAD statement causes the COST paths to be built. The second PATHLOAD statement causes the following sequence of events: 1. Note that MW[6] was cleared at the beginning of the ILOOP for I.1. The values from MW[6] (the selected link trips) are assigned to the COST paths and added into VOL[2]. The values from MW[3] are assigned to the COST paths and added into VOL[1] volumes. SELECTLINK=(L=2001-2004). VOL[1]=MI. 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. PENI=1. MW[1] and MW[2] are the same in this case PATH=TIME. and then the values from MI. 2.TIME=0-7.3 MW[1]=PATHTRACE(COST).MW[2]=PATHCOST . COST paths are built.VOL[3]=MW[3]. 4. MW[6] is set equal to the values in MW[3] for the Js whose path from I crosses link 2001-2004.6 Highway Program Control statements PATHLOAD example PATHLOAD PATH=COST.DISTANCE). VOL[1]=MW[3]. The comments illustrate how to properly skim a path when penalties should be incorporated. The values from MW[3] are assigned to only the links that are within 7.ODTRIPS are assigned and added to VOL[1]. 5. VOL[2]=MW[6]. the MW[6] values could be incorrect. 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. MW[6]=MW[3].5 minutes from I and added into VOL[3] (these are the cold start volumes).ODTRIPS PATHLOAD PATH=COST. */ PATH=LI.MW[2]=PATHCOST 246 Cube Voyager Reference Guide .MW[1]=PATHTRACE(LI. but if the user caused any values to be set into MW[6] prior to this statement.DISTANCE.1. 3. */ PHASE=LINKREAD If ((A=1001 & B=1002) | (A=1002 & B=1001)) ADDTOGROUP=1 PHASE=ILOOP PATHLOAD PATH=TIME.15)Divert = RelativeSaving MW[3] = Divert ENDJLOOP . 2. MW[1]and MW[2] could be different because penalties are used . Compute another path with the bridge excluded (group=1)and extract the times along the path into MW[2] 3. If MW[1]=PATHTRACE(TIME.1.3). CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) Cube Voyager Reference Guide 247 .) 4. a bridge) is added to the network.they would be the same. The two assignments are made to the same volume set. MW[3] = the fraction of trips diverted to the bridge path TimeSaved = MW[2] .Highway Program Control statements 6 .MW[1]. and it can be unavailable to the path builder by excluding links with group code 1.1. The steps are: 1. VOL[1]=MI. In this example the link is already in the network. 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]. and is not meant to imply any type of realistic diversion. EXCLUDEGROUP=1 MW[2]=PATHTRACE(TIME) . Compute a path split based upon the total times for the two sets of paths. VOL[1]=MI.w bridge PATHLOAD PATH=TIME. and the remaining trips to the other path set. 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. MW[1]=PATHTRACE(TIME) .TRIPS*MW[3] PATHLOAD PATH=TIME. /* Following is an example of trip splitting based upon the relative difference of time if a link (say.1. in the path.wo bridge JLOOP. Divert = 0 RelativeSaving = TimeSaved / MW[2] IF (TimeSaved > 10 && RelativeSaving >. Assign a portion of the trips to the one path set. 2 is always >= 1.assign bridge trips PATHLOAD PATH=TIME.TRIPS*(1-MW[3]) PRINT Formats and prints a line of information. but. they could have just as easily be kept separate. If the time saved exceeds 10 minutes and the relative saving (time saved / total trip time) is greater than 15 percent. EXCLUDEGROUP=1. Compute the time path with the bridge included and extract the times along the path into MW[1]. And. To simplify coding. PHASE=name may be used directly.A. B(5). Example IF (ITERATION = 0) . the ENDPROCESS statement is not necessary. base1=y maxperline=10 PROCESS . NI.. to further simplify coding. T0(6. PHASE ENDPHASE A user process phase stack is defined by a PROCESS statement that names it and an ENDPROCESS statement that ends it.B.2) PRINTROW Formats and prints row(s) of matrices.6 Highway Program Control statements See “PRINT” on page 66 for details. the PROCESS control word is not necessary.1 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10 form=6D. MW J TITLE FORM MAXPERLINE BASE1 See “PRINTROW” on page 73 for details. the occurrence of another 248 Cube Voyager Reference Guide .. LIST INPUT LINKS LIST= A(5).VC(5. Example PRINTROW mw=1-2.DIST(6). ENDPROCESS Establishes phase blocks.2) ENDIF IF (ADJUST=1 && ITERATION >5 && VC >2.0) LIST='BIGVC for: '. VOL[1]=MI. until an ENDPROCESS statement or another PROCESS statement is encountered.FLAGCODE ENDPHASE REPORT Requests reports and establishes tracing.1. PROCESS keywords Keyword PHASE |KS| Description Names the phase stack. CAPACITY PENI Cube Voyager Reference Guide 249 .ODTRIPS ENDPHASE PHASE=ADJUST LW. Exception: Static statements. The control statements that follow it.DISTANCE*60 / SPEED ENDPHASE PHASE=ILOOP PATH=TIME. such as PARAMETERS. FILEI. will be executed when the phase is internally executed. are not processed within the stack. If ENDPROCESS is used. Example PHASE=LINKREAD T0 = LI. and LOOKUP. 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. it may be coded as either ENDPROCESS or ENDPHASE.TIME = TIME * LW. FILEO.Highway Program Control statements 6 PROCESS statement acts as the ENDPROCESS statement. Trace can be turned on and off at any time. There may be any number of VDTSPD keywords. Switch to turn off dynamic printing of the turn delays calculated by the junction model and reported every iteration. Specifies which destination zones are to be included in this report. If there are a larger number of junctions coded in the network then PENI=T could result in voluminous print file. only the first five J values will be reported. so be careful). If no subkeywords are appended to this keyword. If this keyword is not specified. Controls the listing of the stack statements as they are processed (can be quite voluminous. If this keyword is not specified. Note that this report requires considerably more computer resources (both process time and disk space). Switch that indicates if the speed portion on the SPDCAP tables is to be reported. all destination zones will be included.6 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. thus controlling the amount of output as desired. all origin zones will be included. If a COMP is traced. the program will simulate: RANGE=0-100-1. Specifies which origin zones are to be included in this report. SPEED TRACE |?| |K?| VDTSPD |?| VDTSPD I |IV| VDTSPD J |IV| 250 Cube Voyager Reference Guide . Switch that indicates if the vehicle distance traveled stratified by average trip speed is reported. Each subreport will not only contain values for the RANGE specified. With multiple RANGE sets.5-100-5 specifies that two different schemes are to be obtained.5 Interval includes speeds >= 4 and < 5 5 . an I-J value can be placed into more than one RANGE set. For example: • • • RANGE=0-100 specifies that the report is to VDTSPD RANGE |IP| have only one number reported.4 Interval includes speeds >= 3 and < 4 4 .3 Interval includes speeds >= 2 and < 3 3 . the printed report will appear as: x . There must be at least two values.y Interval includes speeds >= 5. Specifies the speed stratification for this report. and possibly three for each sub report. RANGE=0-7. y is the highest speed found Cube Voyager Reference Guide 251 . Specifying FILE will not preclude the reports from being printed. it will also include any values less than the low value and any values greater than the highest value.2 Interval includes speeds >= x and < 2. If RANGE=2-5-1 is specified. The values can have at most one decimal place.Highway Program Control statements 6 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. the output will be stacked onto the file. x is the lowest speed found 2 . If the same file is specified following different VDTSPD keywords.5. 7. RANGE=0-100-1 specifies that the report is to have 100 values reported. VAL VARS Use SET to set any number of variables to some value. the entire array will be set to VAL. 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. FILE=VDTSPD. It must be a numeric constant. If this keyword is not specified. VOL=1. A COMP statement is not as efficient as a SET statement. turn stack tracing on REPORT CAPACITY=yes . SET keywords Keyword VAL |R| Description Value that the VARS that follow will be set to. report the capacities by lane by CAPCLASS REPORT VDTSPD=T. All variables are set to zero when they are first allocated.5-100-5. Sets the maximum number of decimal places to be printed for any variable. COMP statements produce most changes. 7.6 Highway Program Control statements REPORT keywords (continued) Keyword VDTSPD Subkeyword VOL |IP| Description Specifies which volume sets are to be included in this report.TXT SET Sets multiple variables or arrays to the same value.5. the program will report all volume sets. VARS |S| 252 Cube Voyager Reference Guide . If a VARS is the name of an array established on an ARRAY statement. ZDAT ZDAT DEC |?| |I| Example TRACE=y . I=1-933. RANGES=0-7. J=1-933. Switch that indicates if all the internal arrays obtained from FILEI ZDATI files are to be reported. This one value applies to all variables on all ZDATI statements. The codes are numbered 1-32. REMOVEFROMGROUP |KIP| Example PHASE=LINKREAD IF (LI. that is the user’s responsibility.VA3. VARS=TOT1. Group codes are used primarily for designating links that are to be excluded in path-building.6.SPDCLASS==1-3. is also the same (VAL is 0) SET VAL=123 VARS=C123. sets all to 123 SET VAL=0. VARS=TOT1. is a COMP statement to do the same thing SET VARS=TOT1 TOT2 COUNTER . This keyword normally should not be used.Highway Program Control statements 6 Example SET VAL=0.VA2. VY SETGROUP Sets group codes for a link.TOT2. TOT2. it is applicable during only the LINKREAD phase. There are no preconceived definitions for the codes. TOT3 . Group codes can be quite helpful in project analysis or for determining specific interchange to interchange movements. VARS=VX. and for inclusion in select link analysis. SETGROUP keywords Keyword ADDTOGROUP |KIP| Description Specifies that the current link is to be assigned the codes that are in the value list. VARS=VA1.55) ADDTOGROUP=1 Cube Voyager Reference Guide 253 .COUNTER TOT1=0 TOT2=0 COUNTER=0 . Specifies that the current link is to have the designated values removed from its codes. ADDTOGROUP REMOVEFROMGROUP Use SETGROUP to set group codes for a link. VAL=100. Each link can have up to 32 different group codes assigned to it.9. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. the values from the NETI are updated when NETI is opened..7. for all lane stratification (SPEED[1.2.. LANES may be interspersed with other keywords and values on the statement. Speed to be applied to the link.6 Highway Program Control statements SORT Sorts user-defined arrays.. LANES |IV| SPEED |RV*99| 254 Cube Voyager Reference Guide .). inclusive.. Speed is maintained with one decimal place. inclusive. The speed array is initialized to the index number. for all lane stratification (CAPACITY[1]=20. ARRAY NUMRECS See “SORT” on page 76 for details. All values must be 09999. SPDCAP keywords Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour. All values must be 03276.99]=1.. 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. All values must be 1-9. This capability allows you to test various scenarios without having to modify the network.. Lane stratification that any following CAPACITY and/or SPEED values are to apply to. If this statement is used in the control file for the Highway program. The capacity array is initialized to 20 times the index number.. inclusive. CAPACITY[2]=40. The revised tables will be written to the NETO file. SPDCAP Revises speed and capacity tables.99). Example . .700 SPDCAP LANES=2.50.4-9..21. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement. CAPACITY[20]=300.3.. the single volume is computed by adding all the individual turn volume sets together (T = TURN[1] + TURN [2] + TURN [.Highway Program Control statements 6 A network contains an array of capacity and speed data.88. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables.3..5. If there is at least one TURNS statement.. LANES=2-8. When an array is accessed.30. NT Use TURNS to request that the volumes at specific interchanges (nodes) be accumulated. Usually.6. then revise the values for 20. the program will accumulate turns for every PATHLOAD VOL[]= statement that is present..8.8 SPDCAP CAPACITY=99*50. The value of T for each movement will be computed in the Adjust phase. By default. and the capacity and/or speed classification (CAPCLASS. the program uses the number of lanes (LANES) as the row index. the T= expression should be parallel to the V= expression that is specified on a FUNCTION statement. CAPACITY and SPEED are entered as vector data..400. At the end of each iteration (in the Adjust phase). Inappropriate. LANES=5. LANES will be preset to 1-9. and contains 891 values. the LANES will not be used. Cube Voyager Reference Guide 255 . a single total turn volume will be computed for each movement at the nodes where turns are requested.] ..2. This default accumulation process can be overridden by using the T= capabilities on this statement. SPEED=20. and then combined with other iteration values to form the “combined” volume.SPEED[15]=15 SPDCAP SPEED=30.Set entire table to 50.). Each array is dimensioned with ninety-nine values for each of nine lane stratification. TURNS Requests turning movement volumes. and may have null fields to skip the revision of certain columns. SPDCLASS) as the column index to obtain a value for a link. and 24 for lanes 1. and may be indexed to set a specific loading place. LANES=1.3. FORMAT=BIN TURNS N=1000-2000. The turn volumes will be written to the file(s) specified on that statement. T=TURN[1] + TURN[3] 256 Cube Voyager Reference Guide . Expression used to compute the total volume at each of the nodes.19000-32000.5000-6000. you must specify a FILEO TURNVOLO statement. TURNS keywords Keyword N T |IP| |N| Description List of nodes at which turning volumes are to be accumulated.3000. Example FILEO TURNVOLO=myfile.6 Highway Program Control statements To accumulate turn volumes.trn. Topics include: • • Process overview User stacks Process overview It is important to have a basic understanding of the logic of the program. build paths. PHASE=CONVERGE .Highway Program Theory 6 Theory This section discusses the theory used in the Highway program. skim paths. normally this phase is not used .. TC. they can be placed properly. include V. optional for user specified convergence tests .. ENDRUN Cube Voyager Reference Guide 257 . insert any statements required to: .. then only the actual operations of each segment need be completed.. PHASE=ADJUST . revise special LW.values for next iteration . If you use a basic template. Citilabs suggests that you use a basic template for all applications. extract custom information from the input network. Example of suggested basic application template RUN PGM=HIGHWAY FILEI FILEO FUNCTION ... Although you can place phases in the script in any order... and COST functions here PHASE=SETUP . PHASE=LINKREAD .. so that when certain special operations are to be performed. load trips to paths .. . PHASE=ILOOP . Write requested MATOs. If there is a user supplied LINKREAD block.MAXITERS PHASE = ILOOP Loop I=1. EndLoop ENDPHASE • PHASE = ADJUST Loop LINKNO=1. then set the required values that LINKREAD did not set properly Set the Time and Cost values • EndLoop ENDPHASE • • LOOP ITERATION=1. perform the statements of the block.ZONES • • • Read required MATIs. etc. TC. This phase is not specified by most users. process it.NUMLINKS • • Read each link record.NUMLINKS • • • Read each link record. If there is a PHASE=SETUP block. ENDPHASE • PHASE = LINKREAD Loop LINKNO=1.6 Highway Program Theory The internal logic of the program is as follows: • PHASE = SETUP Establish user SET arrays. COST) for the link. Obtain link values using most of the LINKREAD process Apply the appropriate Functions (V. 258 Cube Voyager Reference Guide . Process the ILOOP stack. but it does provide a mechanism for altering program variable values at crucial times. means all the user supplied statements for the phase. Phase refers to a phase the program automatically processes. exit ITERATION Loop.) The operational statements that are to be preformed in this stack follow the PHASE statement. Stack and phase are sometimes used interchangeably. or Time for the next iteration. Non-operational statements (FILEI. may be specified one time only. The term stack. PARAMETERS. The stack is terminated by the presence of another PHASE = stackname statement. Most times. Apply Function Cost. FILEO. but they are ignored during stack processing. (PHASE is a trigger key. Process the CONVERGE stack (user or default) If Convergence met. Iteration loop User stacks These are stacks of control statements that you provide to perform certain operations at various times in the process. IF and LOOP blocks must be Cube Voyager Reference Guide 259 . Each of the phases. and stack refers to the user supplied statement for that phase. the other stacks will not be necessary. • EndLoop. an ENDPHASE statement. Combine MATO matrices.Highway Program Theory 6 • Process the user’s ADJUST stack to either list the results of the assignment. as used here.values. so most users will just code PHASE= without the leading control word. Each stack begins with a PROCESS PHASE = StackName statement. The ILOOP stack is required. ENDPHASE • ENDLOOP . Depending upon the values for COMBINE and ITERATION: • • Combine link volumes. but all the others are optional. It is suggested that all non-operational statements be placed at the beginning of the input for reader clarification. or the end of input. or to revise LW. FUNCTION and others) can be within a stack. Most users will not have any need for this stack. and is used as explained above in that section. It also provides the capability to print certain link values during the process.values are dependent upon Time and/or Cost. If LW. ADJUST stack This stack is processed as the last operation in the ADJUST phase link loop. the LW. it is used to obtain required link values (if they are not directly available from the input network). Alternatively. but will have impact on the actual program process only from ILOOP. and is described previously. It provides a place for computing and accumulating special values such as objective functions (currently undocumented). CONVERGE stack This stack is processed during convergence testing in the ADJUST phase. It MUST be present. Primarily. 260 Cube Voyager Reference Guide .values can be adjusted with ILOOP statements. ILOOP stack This stack is the entire ILOOP phase.values and GROUP codes. the adjustment can be made here. and GOTO and associated label statements must be within the same stack. and it is necessary to reflect the changes in those values to the LW. EXIT and ABORT will cause termination of a stack.values for the next iteration.6 Highway Program Theory complete within a stack. LINKREAD stack This stack is in the LINKREAD phase. and to set link LW. Its primary purpose is to set BALANCE to 1 if certain conditions are met. .net FILEI MATI[1] = TRIPS.0001 PROCESS PHASE = LINKREAD C = LI. .mat FILEO NETO = LOADED.NET PARAMETERS COMBINE=EQUI MAXITERS = 99 GAP=. . assumes DISTANCE and SPEED are available on the input network . the standard BPR formula for all links.CAR. no LINKCLASS defined. set capacity equal to a link field . DISTANCE AND SPEED on the link attributes. therefore defaults to 1 for all links ENDPROCESS PROCESS PHASE=ILOOP . No COST function defined therefore COST defaults to TIME ENDRUN Cube Voyager Reference Guide 261 . */ RUN PGM=HIGHWAY FILEI NETI = Network. main loop for program PATHLOAD PATH=TIME.CAPACITY . No TC functions defined therefore congested travel times computed using .1. load trips from input matrix to volume set 1 ENDPROCESS . build path based on time VOL[1]=MI.Highway Program Examples 6 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. 5 . MW[1]=PATHTRACE(TIME). skim TIME and DISTANCE for the min TIME paths into work matrices 1 and 2 PATHLOAD PATH=TIME. Intrazonal time . . Loop across all origin zones and build path using congested time.NET FILEO MATO[1] = HWY_SKIMS. ‘HWY Distance’ PROCESS PHASE=LINKREAD T0=li.PEN FILEO NETO = LOADED. 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.MAT FILEI TURNPENI = TURNPEN.NET FILEI MATI[1] = TRIPS.DISTANCE) . building paths on a generalized cost function with the cost functions differentiated by the facility type (LINKCLASS). Final congested travel times on the input network ENDPROCESS PROCESS PHASE=ILOOP . make the intrazonal time equal to half the time to the nearest zone COMP MW[1][I] = rowmin(1) * 0. MO=1-2. MW[2]=PATHTRACE(LI. Turn penalties are included in the path building process and the PATH file is saved for graphical analysis */ RUN PGM=HIGHWAY FILEI NETI = NETWORK. For intrazonals.6 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.TIME_1 . */ RUN PGM=HIGHWAY FILEI NETI = LOADED.MAT.NAME= 'HWY Time'.NET 262 Cube Voyager Reference Guide . 0+0. include turn penalties.1. EXCLUDEGROUP=1.CLASS = 5-10) LINKCLASS = 2 . cost function for major roads cost[2]=time*time_cost2+li. VOL[2]=MI. group railway links for exclusion from assignment IF (li. load truck trips.0+0.distance*distance_cost2} .CLASS = 1-4) LINKCLASS = 1 . congested time function for minor roads cost[1]=time*time_cost1+li. set link classes for major roads IF (li. . VOL[1]=MI. set link classes for minor roads IF (li.CAPACITY * 1.PTH .005 time_cost1 = 0.2 distance_cost2 = 0.TRUCKS. ----.15*((v/c)^4)) . final turn delays and the binary junction data file */ RUN PGM=HIGHWAY Cube Voyager Reference Guide 263 .1. set parameters and values for time and distance costs PARAMETERS COMBINE = EQUI GAP = 0. congested time function for major roads tc[2]=t0*(1.CLASS = 11 | li.CLASS = 12) ADDTOGROUP=1 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH=COST. .5 time_cost2 = 0. exclude rail links PATHO=1 NAME=COST_PATH INCLUDECOSTS=T ALLJ=T . PENI=1-2.CAR.SET CAPACITY and LINKCLASS PROCESS PHASE=LINKREAD CAPACITY = LI. Define cost and delay functions function { tc[1]=t0*(1. 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.15*((v/c)^8)) . .Highway Program Examples 6 FILEO PATHO[1] = HWY_PATHS.4 . .0 .distance*distance_cost1 . save path file ENDPROCESS PROCESS PHASE=ADJUST .7 distance_cost1 = 0. load car trips. 1. congested time function for major roads tc[2]=t0*(1. set convergence method and criteria PARAMETERS COMBINE = EQUI.MAT FILEI JUNCTIONI = JUNC_BASE.NHB. 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.15*((v/c)^4)) . GAP = 0.NET FILEO PATHO[1] = ROADPATHS.1.CAP IF (LI. maxiters=99 PARAMETERS EQUITURNCOSTFAC=1 .DAT FILEO JUNCTIONO = TURNS. INCLUDECOSTS=T. subarea network created with POLYGON tools in CUBE/VIPER FILEI SUBAREANETI=subarea1.mat NAME=HTW.0+0. PATHO=1.PENI=1 ENDPROCESS PROCESS PHASE=ADJUST function { tc[1]=t0*(1. The subarea network is created with CUBE/VIPER POLYGON tools with the default renumbering of the network.set=1 FILEO NETO = LOADED.NET FILEO SUBAREAMATO=submat1.IND.FUNC_CLASS = 3-10) LINKCLASS=2 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH = TIME. NAME='assignment'.MAT FILEO NETO=Loaded_DEMO.15*((v/c)^8)) .SET CAPACITY and group links PROCESS PHASE=LINKREAD C = LI.NET .NET FILEI MATI[1] = VEHICLETRIPS.WTH.FUNC_CLASS = 1-2) LINKCLASS=1 IF (LI. ----.TOTAL 264 Cube Voyager Reference Guide .005. period=60.PTH FILEO TURNPENO = TURNDELAYS.HTO.net MATI=TRIPSBYPURPOSE. */ RUN PGM=HIGHWAY NETI=DEMO.ALLJ=T.OTH.0+0.6 Highway Program Examples FILEI NETI = NETWORK. VOL[1]=MI.INT . Equilibrium assignment could be performed specifying COMBINE=EQUI .0. SUBAREAMAT[1]=mi.4.1.NET NETO=DEMOSelectLink. SUBAREAMAT[5]=mi.0.4 dec=2. this PATHLOAD statement builds paths on TIME.2.SUBAREAMAT[4]=mi. VOL[5]=mi.Highway Program Examples 6 PARAMETERS COMBINE=EQUI GAP=.0.2.VOL[1]=mi. volume function V sets the volume to use for V/C in the delay function .CLASS C=LI.MAT.VOL[4]=mi.05.mo=1-2. SUBAREAMAT[3]=mi.4.1.6 ENDPHASE PHASE=ADJUST .0. and the total trips to separate volume sets.1.VOL[3]=mi.1. combine=Y .0.6.1. In step 1 several examples of select link assignment are shown.05. assigns each trip purpose .1.1.05.1.0.NET MATO = MATVOUT. extracts a subarea matrix for each trip purpose and the total trips PATHLOAD PATH=TIME.5. set volume to use in congested travel time functions ENDPHASE ENDRUN Highway example 6 /* EXAMPLE 6 This script has two steps.1.3.0001 PHASE=LINKREAD LINKCLASS=LI.VOL[2]=mi.1. No delay functions (TC[#]=) are specified here so the default BPR .05 . or volume averaging by specifying COMBINE=AVE if desired PHASE=LINKREAD Cube Voyager Reference Guide 265 .1..0. the number of fractions defines the number of iterations .MAT NETI=DEMO.1.0. Step 1 Select Link Assignment RUN PGM=HIGHWAY MATI=TRIPS. .1. this is an example of an incremental assignment procedure .3.FRACTIONS=0.0.1.1.0 5.1.0.5. formula is used for all link classes FUNCTION V=VOL[6] .1.1.CAPACITY ENDPHASE PHASE=ILOOP .1.VOL[6]=mi. at each iteration the listed fraction of the trip table is assigned COMBINE=SUM.0. In step two a MATRIX job is run to build trip end reports for the select link trip matrices created in step 1 */ .0.1.SUBAREAMAT[6]=mi.SUBAREAMAT[2]=mi.05.1. 6 Highway Program Examples LINKCLASS=LI.6 to these paths and put them in Volume set 1 (V1_1 on the output network). but only want to calculate congested travel times based on the true total volumes on each link. mw[1] = mi. This is why you need the function V=vol[1]. Step 2 Extract and report select link trip ends RUN PGM=MATRIX .6 into working matrix 4 if they are on paths that use the selected links (L=). and lastly put the total trips assigned from mi.1.1.VOL[1]=mi.1. Without this statement.1.6. Note that on the MATO line mo=4 will output the selected trip matrix (4) for the links L=.6. mw[4] = mi.6.1. put trips from mi. vol[2] = mw[1] mw[2]=mi. The V function is automatically executed during the adjust phase. assign trips from mi.VOL[3]=mi.6. note this example was for a 25 zone network 266 Cube Voyager Reference Guide . assign trips from mi.6 /* this step says “build paths based on time. */ ENDPHASE PHASE=ADJUST function { V=vol[1] } /* this function sets the volume for the capacity restraint to be the total volume.CAPACITY ENDPHASE PHASE=ILOOP PATH=TIME.1. selectlink = (L=1449-1495).1.6 to these paths and put them in Volume set 3 (V3_1 on the output network). V is set to the sum of all volume sets which double counts volume when you have a select link volume set */ ENDPHASE ENDRUN . selectlink = (L=1494-1423). 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.1. 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).6 into working matrix 1 if they are on paths that use the selected links (L=).1. 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). Now you have 4 volume sets. Note that V=vol[3] would give the same result as these two sets are the same. put trips from mi.CLASS C=LI.1.6 into working matrix 2. vol[4]=mw[4] /* this step says “build paths based on time. #2 is the number of toll gates traversed on the path. */ RUN PGM=HIGHWAY FILEI NETI = SF_BAY_AREA. include the 1st. #3 is the number of the last toll gate traversed on the path and #4-#8. don't use HOV facilities. .NET FILEO MATO[1] = test.3) ADDTOGROUP=1 . mo=1-8 PHASE=LINKREAD LW.mat mw[1]=mi.25 PRINT FORM=10. 3rd and 4th gate number traversed on the path if used.TOLL. LINKIDARRAY=li.TIM. LINKIDCNTMW=2 LINKIDLASTUSE=3 LINKIDMW=4-8 ENDPHASE ENDRUN Cube Voyager Reference Guide 267 .0.TIM). 2nd.FFS * 60 If (li.TOLL. In this example. EXCLUDEGROUP=1. MW[1] = PATHTRACE(LW. they by pass tolls ENDPHASE PHASE=ILOOP PATHLOAD PATH = LW. file =SelectTripEnds.SUM_MAT[INDEX]. The output work matrices include: #1 is the travel time on the I-J path.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.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.ROW_TOT[INDEX].TIM=LI. LIST=INDEX. 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.1. the LINKIDARRAY uses li.Highway Program Examples 6 FILEI MATI=matvout.mat.DISTANCE/LI.USE=2. NET" FILEI TURNPENI = "PROHIBIT1. the paths are built on COST and the COST function will include any gate to gate tolls traversed on a path. NETITOLLROAD=TOLLROAD FILEI NETI = "BASE.PTH" FILEO JUNCTIONO = "JUNCTION1. ----------------------------------------------------------.DBF".2 . EXITGATE=OFF_RAMP. 268 Cube Voyager Reference Guide . FORMAT=DBF FILEO NETO = "TOLLLOAD.COST_TRUCK.MAT".COEF=0.COST.99 NAME=PATHCOST.MAT" FILEO TURNVOLO[1] = "TURNS.00 ELSE LW.PATHTOLL. ENTRYGATE=ON_RAMP. NETIENTRY=ONRAMP.00 ENDIF ENDPROCESS PROCESS PHASE=ILOOP .15 LW.6 Highway Program Examples Highway example 8 /* Example 8 Example of using TOLLMATI to incorporate closed system tolls into the pathbuilding process.DAT" FILEO MATO[1] = "TOLLSKIM.DBF".1.15 LW.LOADS PAR MAXITERS=20 TURNS N=1-9999 PROCESS PHASE=LINKREAD C = LI. trips to load MW[99]=MI. MO=1-5. ----------------------------------------------------------. TOLLS=COST_CAR. */ RUN PGM=HIGHWAY FILEI TOLLMATI[1] = "TOLL.NET" FILEO PATHO[1] = "TOLLPATH.VEHTOLLS. Assign WITH TOLL COST CONSIDERED PATHLOAD PATH=COST. In this example. NETIEXIT=OFFRAMP.1.FUNC_CLASS = 1-2) LW. VOL[1]=MW[99].CAP IF (LI.TIME.PEN" FILEI MATI[1] = "PKHOURTRIPS.EXPO=4.1+MI.COEF=0.EXPO=8. NOACCESS=0.0. . cross trips with tolls ENDPROCESS PROCESS PHASE=ADJUST function { tc=t0*(1. congested time function for major roads } ENDPHASE ENDRUN Cube Voyager Reference Guide 269 . MW[4]=PATHTRACE(TIME.EXPO)) . NOACCESS=0. . TOLLFACTOR=2. MW[2]=PATHTRACE(COST. toll factor is in min/toll units. here 2min/$ (implies VOT=$30/hr) MW[1]=PATHCOST.COEF*((v/c)^LW.0+LW. NOACCESS=0. MW[5]=mw[3]*mw[99] .1). MW[3]=PATHTOLL.1.Highway Program Examples 6 PENI=1 TOLLMATI=1.1). 6 Highway Program Examples 270 Cube Voyager Reference Guide . Cube Voyager Reference Guide Cube Voyager Reference Guide 271 . 7 Intersection Modeling 7 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 . we can be sure that. They have been applied to most kinds of geographic region and most kinds of planning decision. when we wish to compare schemes. This form of model has a unique Wardrop equilibrium solution. we have stable comparable results. it may be necessary to use nonseparable cost functions to achieve adequate verisimilitude in the sensitivities of the costs to the flows. the Frank-Wolfe algorithm (invoked by default in Cube Voyager) gives us a reasonably good solution algorithm. 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. provided both models have been run to an adequate level of convergence. Furthermore. Furthermore we can achieve good convergence in reasonable time. if the policy responses being evaluated include traffic management Cube Voyager Reference Guide 273 . However. Thus later in the planning process.Intersection Modeling Introduction to intersection modeling 7 Introduction to intersection modeling This section provides an overview to intersection modeling. In such a situation. Models with separable costs and monotonic nondecreasing cost functions have been very successful in modelling interurban travel. 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. in congested urban environments. it can easily be observed that most of the delay arises from the conflicts between streams at intersections. Furthermore. Indeed.7 Intersection Modeling Introduction to intersection modeling measures (for example. so a car counts 1. with each lane group having a capacity. intersection modelling tends to make the overall network model less stable. Trucks vary between 1. Data from a file of “Junction Descriptions” is read to determine the exact model form for each modelled node. However there are several other keywords permitted in an intersection description. If necessary.5 (light van) and 2. changing the form of control at key intersections) it must be possible to represent the proposals in the model. the flow pattern is passed to the intersection model. using the default method of combination. you can change to using COMBINE=AVE to guarantee eventual convergence. the model may never reach adequate levels of convergence. Limitations of intersection modeling As noted above. The model will allocate the turning movements into lane groups. Some of these extra keywords are used by 274 Cube Voyager Reference Guide . 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. How the intersection models work Cube Voyager intersection modelling occurs during the ADJUST phase of a capacity restrained assignment. Cube Voyager intersection modelling and other programs This chapter describes only those junction description keywords that are directly relevant to Cube Voyager intersection modelling. Note that the capacity of a lane group will be reduced by any conflicting flows through the intersection. When the costs arising from a flow pattern are required. a bus counts 2. Consequently the assignment may take many more iterations to converge.5 (tractor-trailer). 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. Intersection Modeling Introduction to intersection modeling 7 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 . 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 . also following the usual Cube Voyager script syntax. and the remainder are JUNCTION statements. Comments. It follows the usual syntax for Cube Voyager script statements. of which at most one is a UNITS statement.7 Intersection Modeling Control statements Control statements A junction file contains a sequence of statements. are also allowed in the file. This section describes: • • JUNCTION UNITS JUNCTION Each JUNCTION statement describes the control of some particular intersection in the network. Intersection Modeling Control statements 7 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| v |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 . UNITS LENGTH 278 Cube Voyager Reference Guide .7 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. ApproachWidth. measurements will be taken to be in meters. in the Junction statement. The keywords. InscribedDiameter. If no UNITS statement is found. MajorRoadWidth and CentralReservationWidth. FlareLength. Width. The value of the Length may be either “feet” or “meters” (case insensitive). that have units of length are: AverageLaneWidth. EntryWidth.Intersection Modeling Control statements 7 This statement defines whether the lengths used to define junction geometry are measured in feet or meters. Visibility. EntryRadius. At most one UNITS statement may appear in a junction file. Example UNITS LENGTH=FEET UNITS LENGTH=METERS Cube Voyager Reference Guide 279 . It has two functions within the junction description: 1. Approach.7 Intersection Modeling Common keywords Common keywords This section describes common keywords. It describes how neighbors of the modeled node are grouped into approaches. StorageSpace. because Cube Voyager can only model 280 Cube Voyager Reference Guide . Phase. or the end of the JUNCTION statement. CentralBusinessDistrict. CycleTime. LaneAdjust. MajorRoadWidth. 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. The value of the keyword is a list of node numbers of nodes adjacent to the node being modeled. This sequence continues until the next occurrence of Node. for example. FourLaneMajor. Approach1. 2. The grouping of neighboring nodes into a single approach may be necessary. Type. It begins a sequence of keywords which describe the specified approach. CentralReservationWidth. Cube Voyager requires that the legs of a junction can be assigned a clockwise ordering by using the coordinates of the nodes involved. which is a neighbor of the modeled node. For example. Every node. Cube Voyager Reference Guide 281 . or because the two lanes of a road are represented by individual links. Any valid approach which includes both nodes b and d must also include node c. in the diagram below. Any grouping of links into legs must not invalidate the ordering. zone centroid connectors). this restriction may be overcome by modeling the circulating section explicitly). must appear in exactly one Approach clause. because some of the neighbors are fictional (for example.Intersection Modeling Common keywords 7 three. a is a modeled node.or four-legged intersections (although. at roundabouts. the approaches are numbered in clockwise order. At two-way stop-controlled and priority (two-way yield-controlled) intersections. Its value is the node number of a node adjacent to the modeled node. 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. Node. If it has the value false. ENABLE Every junction description may contain at most one occurrence of the logical-valued keyword ENABLE. By default. At three-legged intersections. The approach containing the specified node. the approaches are numbered in anti-clockwise order.7 Intersection Modeling Common keywords APPROACH1 Every junction description must contain exactly one occurrence of the integer-valued keyword APPROACH1. the choice of APPROACH1 is arbitrary with no modeling consequences. the first and third approaches are major and the second and fourth (if any) approach are minor. 282 Cube Voyager Reference Guide . Cube Voyager will ignore the entire junction description (that is. no intersection modeling will occur at the node). is taken to be the first approach and the other approaches are numbered in relation to it. but if LEFTDRIVE = y is in force. Modeling can also be turned on and off in the Cube Voyager Highway script file using the N clause of the FILEI JUNCTIONI command. By default. calculated values will replace these initial estimates. so no calculated values will be available yet. This real valued keyword specifies the delays. except EXITLANES. no volumes exist yet to use for junction-delay calculations. in minutes per vehicle. However.Intersection Modeling Common keywords 7 ENABLE is a quick way of turning modeling on and off at a particular node from within the junction file during model development. may be coded for the approach. On the assignment’s first iteration. to be used during the first PATHLOAD command to be executed. Cube Voyager Reference Guide 283 . a value of 0. Capitalizing as EstimatedDelay might improve readability. This occurs prior to the first Adjust phase.” EXITONLY=y indicates that the leg is not an approach. During the first iteration. No other keywords.0 minutes is used. this is a very poor estimate and it is very desirable that better values be supplied. in urban areas. For any “approach. this user-specified value provides an initial estimate of the movement delay during path building. EXITONLY NOTE: Keywords are case-insensitive. it is an exit only. An approach’s ESTIMATEDDELAY value is analogous to a link’s initial travel time. ESTIMATEDDELAY NOTE: Keywords are case insensitive. Once an Adjust phase has been executed. Capitalizing as ExitOnly might improve readability. INITIALQUEUE is more like additional demand added to the assigned demand prior to junction calculations. It is coded by approach. a default value of one vehicle per hour is applied. The results only include the delay that these initially queueing vehicles cause to the vehicles that arrive during the modeled period. Rather than being additional time added to the delay at the end of the process. the discharge rate depends on the junction’s conflicting flows. If no value is coded. 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). It defaults to zero.7 Intersection Modeling Common keywords The coding of EXITONLY must agree with the network (that is. If the calculated capacity for any stream from an approach is less than the minimum capacity value for that approach. This substitution occurs before any delay calculations are started. 284 Cube Voyager Reference Guide . INITIALQUEUE NOTE: Keywords are case insensitive. MINIMUMCAPACITY The MINIMUMCAPACITY keyword takes a positive value in vehicles per hour as its argument. Note that the initial queue’s discharge rate is not a constant. 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. However. if there is no assignment (that is. Capitalizing as InitialQueue might improve readability. the minimum capacity will be used instead of the calculated value. INITIALQUEUE is the queue at the start of the modeled period. Consequently. the exit only approach must correspond to a set of one-way links leading away from the modeled intersection). INITIALQUEUE has no effect. just path building for skimming). the delay to the vehicles in the initial queue is not part of the results. drivers will no longer wait for an appropriate gap in the opposing stream. 2. In this circumstance. 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). BUSBLOCKAGE. trips will be diverted away from that turn during subsequent iterations. Driver behavior: If conditions are very congested. CAPACITYINTERCEPT. AVERAGELANEWIDTH. Thus a positive feedback may occur between having low traffic on the turn and having high delay on the turn. they will just force their way into a smaller gap. Modeling expediency: If a minimum capacity of one vehicle per hour results in a predicted delay of the order of an hour. the default value leads to delays being estimated as an hour). The sequence continues until the next occurrence of APPROACHWIDTH. the delay for the lightly trafficked movement will be close to 60/MinimumCapacity (that is.Intersection Modeling Common keywords 7 The minimum capacity is most likely to apply when a movement is very lightly trafficked but is very heavily opposed. This is especially true when the opposing stream is a slow moving queue. 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. 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. Cube Voyager Reference Guide 285 . Eventually. the platoon ratio is estimated as 2(1. MINIMUMCAPACITY. it will not usually be necessary to code CRITICALGAP or FOLLOWUPTIME.0. EXITONLY. However. GRADE. the service times depend on whether the arrival was at a green signal aspect or a red one. arrivals are random). At geometrically modeled signals. FLARELENGTH. When coding gap-acceptance roundabouts. but if they are coded they must be coded by movement.2 are appropriate for signals in advanced traffic 286 Cube Voyager Reference Guide . NUMBEROFLANES.55 for signalized intersections and 1. RANDOMNESS is 0. MOVEMENT. SINGLELANE. Its value is the node number of the junction to be modeled. NODE Every junction description must contain exactly one occurrence of the integer-valued keyword NODE. TURNCHANNELIZED. When coding two-way stop-controlled intersections. RANDOMNESS RANDOMNESS is a real-valued keyword which specifies how random the service times are with respect to the arrival times. the appropriate RANDOMNESS values are reduced.0 . The lower value for signals reflects that even if arrivals at a signal are random. before any movements for that approach are described. INSCRIBEDDIAMETER. RANDOMNESS. ENTRYWIDTH. or the end of the approach. RANDOMNESS values of 0.0 for unsignalized intersections. ENTRYANGLE.0 < RANDOMNESS <= 1. these two keywords should appear within each approach. ENTRYRADIUS.RANDOMNESS) By default.1 or 0. Its value must satisfy the inequality 0.7 Intersection Modeling Common keywords CAPACITYSLOPE. in urban areas where there are signal linkage effects. FREEFLOWCAP. PARKINGMANEUVERS. These values are appropriate for isolated junctions (that is. Care should be taken when coding CRITICALGAP and FOLLOWUPTIME which can occur as keywords at both the approach and movement levels. OPAC) or in offline signal plans at the time that they are installed. code very low values of randomness. 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. Consequently.01. Offline signal plans are generally not completely up to date so they are usually more random than ATMS. such as 0. values of 0. SCOOT.4. Therefore.8 are appropriate for unsignalized intersections in these areas. for the relevant approaches. in areas where offline signal plans operate RANDOMNESS values for signals should be 0. other keywords will be used to distinguish between them: Cube Voyager Reference Guide 287 .4. SCATS. Its value should be taken from the following list: • • • • • • Roundabout Priority FixedTimeSignal Adaptive Signal TwoWayStop AllWayStop The keywords are case insensitive.Intersection Modeling Common keywords 7 management systems (for example. TYPE Every junction description must contain exactly one occurrence of the keyword TYPE.3 or 0.6 to 0. It determines the type of junction to be modeled.3 or 0. 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. the capitalization in the list above is merely to improve readability. Unsignalized intersections in this region should have RANDOMNESS values of the order 0. 288 Cube Voyager Reference Guide . The HCM methodology is invoked using the keyword LANEADJUST. (Note that when forecasting future years. future or base year) and “actuated controllers” (that is.7 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. by default Cube Voyager also applies the HCM delay calculations. The issues of “adaptive settings” (that is. 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. However. However. When observed baseyear signal settings are available. a delay equation formulated by Ian Catling is used. use TYPE=FixedTimeSignal to perform delay calculations for those settings. Note that the HCM methodology can model semi-actuated signal controllers. Chapter 16. This facility is invoked using TYPE=AdaptiveSignal. even if the signal controller is fixed time. given a feasible signal setting and a set of constraints. hardware in the field) are independent of each other. Cube Voyager can optimize the settings for the forecast flows. Both methodologies may be invoked either using supplied settings or adaptive green time calculations. adaptive modeling is always recommended. Giving the keyword UnitExtension to a positive value for some approach invokes this model. If you code DELAYEQUATION=Catling you can force the use of Catling’s delay formulation at an HCM signals. for all other models. When HCM capacity calculations are executed. (where stop-controlled intersections are the norm). (where they are very common) would be called a “two-way yieldcontrolled intersection” in the U.K.S. Cube Voyager Reference Guide 289 .Intersection Modeling Common keywords 7 Note that the type of control called a “priority junction” in the U. The difference is primarily due to two factors: lost time while the signals are changing phase and pedestrian phases.. 290 Cube Voyager Reference Guide . 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.K.S. flashing amber. In the U. and there is a model which requires saturation flows to be estimated or measured externally. green. yellow. Note that the total duration of all the phases should be significantly less than the duration of the signal cycle.. green.. amber. A set of signal aspects for all movements through an intersection is called a phase. Modelers reclassify the aspect into effective green (when the traffic can go) and effective red (when the traffic stops).K. red amber.S. There is a detailed model of junction geometry. red. Note that effective green begins and ends later than actual green (due to reaction times). At any given time. red. which has been calibrated to traffic conditions in the U.7 Intersection Modeling Signal-controlled intersections Signal-controlled intersections This section describes signal controls. green. Cube Voyager offers two ways of modeling the capacity of signals. vehicles making a particular movement through the intersection will see a particular signal aspect: • • In the U. which has been calibrated to traffic conditions in the U. The detailed model also imposes more constraints on the allowed signal phasing than the saturation flow only model. the movement can share with the movement to its left).) This is best handled by introducing a dummy link into the network.Intersection Modeling Signal-controlled intersections 7 A left turn (right turn when LEFTDRIVE=T) which sees a green phase will either be protected (that is. Cube Voyager does not offer any model of “right turn on red” although this is allowed in many areas of the U. the vehicles must give way to some oncoming traffic). 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. Both methodologies can model both permitted and protected phases.S. 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.K. “left turn on red. Note that this keyword does not Cube Voyager Reference Guide 291 . and omitting some lane(s) from the definition of the approach. (The LEFTDRIVE=T equivalent. allowing the right-turners to bypass the signal control.” is not permitted in the U. no opposing flow is running) or permitted (that is. If SINGLELANE = T then CANSHARELEFT should not be coded. Capitalizing as CanShareRight might improve readability. The cycle time must be strictly greater than the sum of all the coded green times. then there must be a movement to this movement’s left and the movement to this movement’s left must have CANSHARERIGHT = T coded. 292 Cube Voyager Reference Guide . and the movement to this movement’s right must have CANSHARELEFT = T coded. the movement can share with the movement to its right). This real-valued keyword is required for all signals. CANSHARERIGHT NOTE: Keywords are case insensitive.7 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 CANSHARERIGHT = T coded. CYCLETIME NOTE: Keywords are case insensitive. This keyword specifies that there is a shared lane to the right of the exclusive lanes for this movement (that is. 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 CANSHARELEFT = T coded. If SINGLELANE = T then CANSHARERIGHT should not be coded. then there must be a movement to this movement’s right. Its value is the length of the signal cycle in seconds. Capitalizing as CycleTime might improve readability. EXCLUSIVELANES NOTE: Keywords are case insensitive. There should be one such pair for each phase of the signals during which vehicles move (that is. Maximimum=180. If SINGLELANE = T. Set LANEADJUST to Y at a signal to invoke the HCM2000 capacity calculations. the constraints will be deduced from the constraints on the individual green times. LANEADJUST NOTE: Keywords are case insensitive.Intersection Modeling Signal-controlled intersections 7 At actuated signals. Minimum = 60. For example: Actual Cycle = 120. PHASE and ACTUALGREEN These keywords occur in pairs. then EXCLUSIVELANES should not be coded. Capitalizing as ExclusiveLanes might improve readability. If no constraints are placed on the cycle time at an adaptively modeled signal. 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. all-red and/or pedestrian phases should not be coded). which are reserved for the exclusive use of vehicles making the specified movement. Set LANEADJUST to N at a signal if you are supplying saturation flows. Capitalizing as LaneAdjust might improve readability. every occurrence of the integervalued keyword. on the specified approach. This integer-valued keyword gives the number of lanes. PHASE must be followed by a single occurrence of the real-valued keyword ACTUALGREEN. Cube Voyager Reference Guide 293 . Cube Voyager may remove the phase altogether (that is. The vehicles making the movement see a green signal aspect when the specified phase(s) is/are running and red otherwise. At geometrically specified signals. The effective green time is the period during which vehicles move across the stop line. If no minimum is applied. PHASES The keyword PHASES is integer-valued but. Note that the (node-level) keyword PHASE is used to define phases and the (movement-level) keyword PHASES associates movements with the defined phases. If the signal is being modeled adaptively. without gaps.7 Intersection Modeling Signal-controlled intersections The values of the PHASE keyword should form a continuous sequence. two digits). set green-time to zero). Capitalizing as SatFlowPerLane might improve readability. then any two-digit phase specifications must specify contiguous phases. The value of the ACTUALGREEN keyword is the duration. 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. 294 Cube Voyager Reference Guide . Every phase must be mentioned in a PHASE keyword for some movement at the intersection. digit) or of two phase numbers (that is. of the effective green-time associated with the phase. SATFLOWPERLANE NOTE: Keywords are case insensitive. it consist of either one phase number (that is. until the number of phases is reached. in seconds. conceptually. No such restriction is required when saturation flows are coded. starting at one and increasing. and the coded value of ACTUALGREEN is taken to be part of the example feasible solution. then the keywords maximum (required) and minimum (optional) may be used to specify constraints. 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. Capitalizing as SingleLane might improve readability. Cube Voyager Reference Guide 295 . The logical-valued keyword is used to indicate that an approach consists of a single lane. except that no signal aspects are involved. 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. CANSHARERIGHT. 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. or CANSHARELEFT on that approach.Intersection Modeling Signal-controlled intersections 7 This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly. 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. SINGLELANE NOTE: Keywords are case-insensitive. 8m.7 Intersection Modeling Signal-controlled intersections At two-way stop-controlled intersections and priority junctions. as appropriate.4m to 4. Capitalizing as AverageLaneWidth might improve readability. If the value falls outside this range. a default of 3. 296 Cube Voyager Reference Guide . has two lanes.6m is used. The average lane width must be in the range from 2. of an approach to a geometrically modeled signalized junction. the approach should be recoded to have more or fewer lanes. If no value is provided. a minor arm that does not have SINGLELANE = Y explicitly coded. This real-valued keyword describes the mean lane width. 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. in meters or feet. the second refers to the other side of the road (for example. The real values supplied to this keyword are number of buses stopping per hour. BUSBLOCKAGE NOTE: Keywords are case insensitive. the crossed box is the bicycle conflict zone where right turning traffic may be impeded by any bicycles crossing the intersection. Capitalizing as ConflictingBike might improve readability.Intersection Modeling Signal-controlled intersections 7 CONFLICTINGBIKE NOTE: Keywords are case insensitive. Bicycle traffic which weaves with turning traffic in advance of the stop line should be excluded from this value. The diagram below illustrates the relevant bicycle flow for right hand rule of the road. The flow of bicycles in from the curb-side lane in units of bicycles per hour. The CONFLICTINGBIKE is the flow of bicycles through this region. because these bicycles do not interact with the other vehicles while they are still within the intersection. Capitalizing as BusBlockage might improve readability. In the diagram. if there is a tram line in the center of the road or there is a Cube Voyager Reference Guide 297 . The first element refers to the normal curb side of the road. NOTE: If exit lanes are omitted from an arm that pedestrians cross. Capitalizing as CentralBusinessDistrict might improve readability. EXITLANES The number of lanes traveling away from the modeled intersection.7 Intersection Modeling Signal-controlled intersections bus stop on the offside of a one-way street). the capacity of movements entering the arm may be reduced significantly. This keyword is only applicable at geometrically modeled signals. 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. CBD. Only buses stopping within 75 meters (246 feet) of the stop line (either upstream or downstream) should be included. CENTRALBUSINESSDISTRICT NOTE: Keywords are case insensitive. 298 Cube Voyager Reference Guide . CENTRALBUSINESSDISTRICT is a logical-valued keyword which may be applied at geometrically-modeled fixed-time signals. You can also use the abbreviation. Cube Voyager only uses this value for pedestrian and bicycle modeling. By default. The keyword accepts the values “HCM” or “Catling” (case-insensitive). 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 HCM delay equations are invoked. expressed as a percentage.Intersection Modeling Signal-controlled intersections 7 GRADE The real-valued keyword GRADE describes the grade. Coding PARKINGMANUEVERS = 0 means that parking is allowed. it is like Cube Voyager Reference Guide 299 . parking is not allowed. it consist of either one phase number (that is. two digits). Capitalizing as ParkingManeuvers might improve readability. Note that this is a two-way flow. PEDESTRIANPHASE The keyword PEDESTRIANPHASE is integer-valued but. if there is parking in a central reservation or on the offside of a one way street). PARKINGMANEUVERS NOTE: Keywords are case insensitive. Only parking within 80 meters of the stop line should be included By default. digit) or of two phase numbers (that is. 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. negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. In this respect. but it is extremely rare. the second refers to the other side of the road (that is. but more extreme grades do occur. conceptually. It is a signed value. By default the approach is assumed to be flat (GRADE = 0). The models have been calibrated for grades the range -6% to +11%. This keyword is only applicable at geometrically modeled signals. For example the maximum grade in San Francisco is about 31%. PEDESTRIANFLOW The number of pedestrians crossing the approach per hour. of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. PHASES The keyword PHASES is integer-valued but. in seconds. for example in the U. Junction. The right filter phase coded below might be used as a proxy for RTOR when the right turns are heavy. Geometric signals example Cube Voyager does not contain a model for right turn on red. two digits). UNITEXTENSION The minimum gap. an icon of a man walking is displayed in green. conceptually. Node = 276. 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. 300 Cube Voyager Reference Guide .7 Intersection Modeling Signal-controlled intersections the keyword PHASES. the two phases must be adjacent.K.S. between successive vehicles moving on a traffic-actuated approach to a signalized intersection that will cause the signal controller to terminate the green display. laneadjust=t. one digit) or of two phase numbers (that is. the word WALK or an icon of a man walking is displayed in white whereas in the U. any two-digit phase specifications must specify contiguous phases. The phases mentioned are the phases when pedestrians crossing the approach are given permission to use the crosswalk. No such restriction is required when coding saturation flows. At geometrically specified signals. it consist of either one phase number (that is. Type = FixedTimeSignal. If using a two-digit number. The symbols displayed to the pedestrians vary by country. EstimatedDelay = 0.6. ExclusiveLanes = 1.6. EstimatedDelay = 0. EstimatedDelay = 0. Phases = 3. ActualGreen = 59. minimumcapacity=50.1. Movement = Left. ExclusiveLanes = 1.3. Approach = 291.1. Movement = Right. ExclusiveLanes = 1. Phase = 1. ActualGreen = 5. AverageLaneWidth = 3. EstimatedDelay = 0. Phases = 1. Phases = 32. Phases = 12. minimumcapacity=50. Approach = 264. ExclusiveLanes = 1. Phases = 1. Phase = 3. Phase = 2. minimumcapacity=50. Movement = Through. Movement = Through. AverageLaneWidth = 3. ExclusiveLanes = 1. Movement = Through. EstimatedDelay = 0. Cube Voyager Reference Guide 301 . Phases = 1.1. Approach = 267. ActualGreen = 11. EstimatedDelay = 0. Movement = Left. AverageLaneWidth = 3. Movement = Right.1.Intersection Modeling Signal-controlled intersections 7 Approach1 = 291.3. CycleTime = 90.6.3. ExclusiveLanes = 1. Movement = Left. ExclusiveLanes = 1. Phases = 3. EstimatedDelay = 0. Movement = Right. ActualGreen = 11. Movement = Left. AverageLaneWidth = 3. Movement = Right. Approach = 306. EstimatedDelay = 0. Phase = 2. Phase = 1. Phases = 32 Saturation flow signals example This example illustrates the coding of fixed-time signals: Junction. Movement = Through. Movement = Through. ExclusiveLanes = 1.1.2. EstimatedDelay = 0. ExclusiveLanes = 1. Approach = 291. ExclusiveLanes = 1.7 Intersection Modeling Signal-controlled intersections EstimatedDelay = 0.6. ActualGreen = 59. CanShareRight=y.2. ActualGreen = 5. ExclusiveLanes = 1.1.2. EstimatedDelay = 0. EstimatedDelay = 0. Approach1 = 291. CanShareLeft=y. Phases = 3. Phases = 1. EstimatedDelay = 0. ExclusiveLanes = 1.2.1. Movement = Left. 302 Cube Voyager Reference Guide . EstimatedDelay = 0. Phases = 12. Phase = 3. CycleTime = 90. Phases = 3. Node = 276. Type = FixedTimeSignal. Phases = 1. Movement = Right. Approach = 306. Phases = 3. ExclusiveLanes = 1. ExclusiveLanes = 1. Approach = 264. CanShareLeft=y. CanShareLeft=y. Movement = Right. CanShareRight=y. ExclusiveLanes = 1. CanShareRight=y.1. EstimatedDelay = 0. ExclusiveLanes = 1. Phases = 1. EstimatedDelay = 0. Movement = Right. Phases = 3. EstimatedDelay = 0. Approach = 267. ExclusiveLanes = 1. Movement = Left. Phases = 3.2. Phases = 23. EstimatedDelay = 0.Intersection Modeling Signal-controlled intersections 7 ExclusiveLanes = 1. Movement = Through. Movement = Through. EstimatedDelay = 0. Movement = Right. Phases = 1. EstimatedDelay = 0.2.1.3. Phases = 1.1. Movement = Left. Phases = 2. EstimatedDelay = 0.2. Phases = 3. EstimatedDelay = 0. EstimatedDelay = 0. Phases = 2. CanShareRight=y. Movement = Left. EstimatedDelay = 0. CanShareLeft=y.3.3. Cube Voyager Reference Guide 303 .2. ExclusiveLanes = 1. Movement = Through. Phases = 23 304 Cube Voyager Reference Guide .7 Intersection Modeling Signal-controlled intersections ExclusiveLanes = 1. Traffic on the minor road must stop. There is a hierarchy of flows. illustrated below.Intersection Modeling Two-way stop-controlled intersections 7 Two-way stop-controlled intersections This section describes two-way stop-controlled intersections. in which lower rank flows must give way to all higher rank streams. before entering the intersection. 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”). Cube Voyager Reference Guide 305 . or approaches (at a crossroads) have “stop” signs. even if there is no major road traffic visible. The value is the number of vehicles which can wait in the center of the major road without obstructing major road flows. is a gap-acceptance model that has been calibrated against traffic conditions in the USA. between the lanes of the major road. or there are islands. First the vehicle crosses to the central reservation. then it completes its movement through the intersection. may do so in two stages.7 Intersection Modeling Two-way stop-controlled intersections The capacity model. 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 . minor road traffic. 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. which crosses the major road. which has been implemented in Cube Voyager. This situation is enabled when a non-zero value of storage space is coded. 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. Note that the coded value is the base critical gap. is one of the parameters of any gapacceptance capacity model. Capitalizing as CriticalGap might improve readability. no or negligible flare.1 6. it is applicable by movement.5 7.9 6. Capitalizing as FollowUpTime might improve readability. FOLLOWUPTIME NOTE: Keywords are case insensitive. It is defined as the minimum time interval in a higher priority stream that allows intersection entry for one vehicle.1 Four-Lane Major Street 4. It is modified to allow for junction geometry. 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.Intersection Modeling Two-way stop-controlled intersections 7 CRITICALGAP NOTE: Keywords are case insensitive. At two-way stop-controlled intersections.1 6. Cube Voyager Reference Guide 307 . The critical gap.5 Normally this value is allowed to default. in seconds. that is.2 6.5 7. By default this value is zero. This logical-valued keyword determines the number of lanes on the major road of a two-way stop-controlled intersection. Capitalizing as FreeFlowCap might improve readability. only code when there are observations indicating site-specific driver behavior at the intersection FOURLANEMAJOR NOTE: Keywords are case insensitive. It is the capacity for the unmodelled movements from the arm. It is defined as the time between the departure of one vehicle the next using the same gap in a higher priority stream.5 Normally this value is allowed to default.0 3.2 3. then the major road has two lanes in each direction (total four). in seconds. 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. it is applicable by movement. At two-way stop-controlled intersections.7 Intersection Modeling Two-way stop-controlled intersections The follow-up time. otherwise the major road has one lane in each direction (total 2). This value is only relevant for major approaches where FOURLANEMAJOR is false. Capitalizing as FourLaneMajor might improve readability. under a condition of continuous queuing on the entry. If FourLaneMajor = y is coded. is one of the parameters of any gapacceptance capacity model. FREEFLOWCAP NOTE: Keywords are case insensitive. By default.3 4. these movements have 308 Cube Voyager Reference Guide . GRADE The real-valued keyword GRADE describes the grade. Pedestrians may cross the road singly. By default the approach is assumed to be flat (GRADE = 0). By default this value is 1. PEDESTRIANFLOW The number of pedestrian platoons crossing the approach per hour. Each such group counts as one pedestrian platoon. Capitalizing as SingleLane might improve readability. For example the maximum grade in San Francisco is about 31%. For more details of pedestrian platoons refer to Chapter 18 of HCM 2000. when combined with the capacity of the modelled turn. or they may cross in groups. 4 feet per second. equivalently. It is a signed value. PEDESTRIANSPEED The average speed at which pedestrians cross the approach in feet or meters per second. which. The models have been calibrated for grades the range -6% to +11%. SINGLELANE NOTE: Keywords are case insensitive.Intersection Modeling Two-way stop-controlled intersections 7 infinite capacity. especially to Equation 18-18 and the surrounding text. If you code a sensible value (such as 1800 vph). of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. the resulting capacity will be reduced. Cube Voyager Reference Guide 309 . but there will be a corresponding increase in delays. but more extreme grades do occur. gives strange large capacities in the results. expressed as a percentage. two or three abreast.2 meters or. negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. a minor arm. CANSHARERIGHT. At two-way stop-controlled intersections and priority junctions. 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. 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.7 Intersection Modeling Two-way stop-controlled intersections The logical-valued keyword is used to indicate that an approach consists of a single lane. Capitalizing as StorageSpace might improve readability. 310 Cube Voyager Reference Guide . has two lanes. STORAGESPACE NOTE: Keywords are case insensitive. which does not have SINGLELANE = Y explicitly 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. or CANSHARELEFT on that approach. TURNCHANNELIZED NOTE: Keywords are case insensitive. Cube Voyager Reference Guide 311 .Intersection Modeling Two-way stop-controlled intersections 7 This integer-valued keyword applies to two-way stop-controlled intersections. Capitalizing as TurnChannelized might improve readability. It does not matter whether the central reservation is curbed or striped (ghost islands). It is the number of vehicles (PCU) that can wait in the central reservation without impeding major road traffic. two-lane minors and a central reservation. FourLaneMajor = y. Setting TURNCHANNELIZED to T for an approach indicates that the unopposed turn from that approach is channelized. StorageSpace = 3. The turn is said to be channelized if there is a triangular. Approach = 7.7 Intersection Modeling Two-way stop-controlled intersections The turn referred to is the turn which follows the curb (by default. the left turn). when LEFTDRIVE = T. Example The example describes a two-way-stop-controlled intersection with two-lane majors. 312 Cube Voyager Reference Guide . 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. Junction Node = 9 Type = TwoWayStop Approach1 = 8. Approach = 5. Approach = 8. By default. the right turn. TurnChannelized = y. Approach = 6. no turns are channelized. curbed island separating the turners from the other movements on the approach. However. Cube Voyager offers a capacity model of all-way-stop-controlled intersections which has been calibrated against traffic conditions in the US. The model’s only variable is the number of lanes for each arm. 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. NumberOfLanes = 2 Cube Voyager Reference Guide 313 . Valid values are 1. NOTE: Keywords are case insensitive. Junction Node Approach = 6 Approach = 7 Approach = 8 Approach = 5 = 9 Type = AllWayStop Approach1 = 8. as the flows are increased.Intersection Modeling All-way-stop-controlled intersections 7 All-way-stop-controlled intersections All-way-stop-controlled intersections are unsignalized intersections with “stop” signs at every approach. 2. the model is very nonlinear and. The capacities reported by models of undersaturated all-way-stopcontrolled intersections can appear very large. NumberOfLanes = 1. NumberOfLanes = 1. All-way-stop-controlled intersection keyword Keyword NUMBEROFLANES |I| Description Number of lanes at an approach to an all-waystop-controlled intersection. the capacities will decrease. or 3. NumberOfLanes = 2. The approach characteristics of the actual roundabout entries remain unchanged. without compromising the modeling of the intersection. can always represent the circulating lane explicitly in the network. therefore. Individual roundabout models are placed at each entry. The circulating flow past an entry is the only flow which influences the capacity of that entry.7 Intersection Modeling Roundabouts Roundabouts This section describes roundabouts. 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 . 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. The model builder. 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. and slope and intercept.Intersection Modeling Roundabouts 7 that approach are not significantly constrained. on one hand. Worldwide experience with roundabouts and roundabout models leads to the following conclusions: • • When a well calibrated empirical model exists. 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 should be used in preference to a gap acceptance model However. or you can supply geometric data and let Cube Voyager calculate the slope and intercept using formulas calibrated in the UK. You can calculate the slope and intercept outside of Cube Voyager. Empirical model — Each entry is characterized by a capacity slope and a capacity intercept. This technique is particularly useful for modeling roundabouts with five or more legs. the calibration of relationships between geometry. Cube Voyager offers two ways to model roundabouts: • • Gap-acceptance model — Each entry is characterized by a critical gap and a follow-up time. on the other. it may be necessary to fine tune the slope and intercept for local conditions • • Cube Voyager Reference Guide 315 . one of the geometric parameters for the U.7 Intersection Modeling Roundabouts • When no general countrywide empirical relationships exist. This real-valued keyword allows the specification of the approach half width (in meters or feet). Capitalizing as ApproachWidth might improve readability.-calibrated empirical roundabout model. 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. 316 Cube Voyager Reference Guide . 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.K. Cube Voyager Reference Guide 317 . In the diagram below. Capitalizing as CapacityIntercept might improve readability. the double arrow marked “v” (below the arrow) and “AWID” (to the left of the arrow) illustrates the measurement.Intersection Modeling Roundabouts 7 To measure the approach half width. CAPACITYINTERCEPT NOTE: Keywords are case insensitive. 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. The CAPACITYINTERCEPT keyword may be used to supply the capacity intercept directly. each approach is characterized by two real numbers. At an empirically modeled roundabout. The capacity slope is the marginal decrease in 318 Cube Voyager Reference Guide . the capacity slope and the capacity intercept. CAPACITYSLOPE must also be coded for that entry and none of the roundabout geometric parameters may be coded for that entry. each approach is characterized by two real numbers. If CAPACITYINTERCEPT is coded for a roundabout entry.7 Intersection Modeling Roundabouts At an empirically modeled roundabout. The capacity intercept is the entry capacity when the circulating flow is zero. CAPACITYSLOPE NOTE: Keywords are case insensitive. Capitalizing as CapacitySlope might improve readability. the capacity slope and the capacity intercept. a single integer value should be supplied. Its value is the number of vehicles that may queue at the junction without impeding pedestrians who wish to cross. If CAPACITYSLOPE is coded for a roundabout entry. CROSSING2ENTRY This keyword specifies the position of a zebra crossing on an approach to a roundabout or a minor approach priority junction. CAPACITYINTERCEPT must also be coded for that entry and none of the roundabout geometric parameters may be coded for that entry. separate values should be supplied for each of the two lanes. However. The CAPACITYSLOPE keyword may be used to supply the capacity slope directly. on two-lane minor approaches to priority junctions.Intersection Modeling Roundabouts 7 entry capacity when the circulating flow is increased by one PCU per hour. Cube Voyager Reference Guide 319 . At roundabouts and single lane minor approaches to priority junctions. This real-valued keyword allows the entry angle. There are three cases for the measurement of phi. of a roundabout to be coded. Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction. theta. 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 .7 Intersection Modeling Roundabouts CROSSING2EXIT This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. ENTRYANGLE NOTE: Keywords are case insensitive. Capitalizing as EntryAngle might improve readability. If it is absent then no crossing will be modeled. 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. However. 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 7 • • • • 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. the line AD is replaced by a curve A’D’ which is always parallel to the weaving section. ½(angle GLB)). 322 Cube Voyager Reference Guide . Capitalizing as EntryRadius might improve readability. whichever is greater ENTRYRADIUS NOTE: Keywords are case insensitive.7 Intersection Modeling Roundabouts • • • • JK is constructed in the same way as EF.K. one of the geometric parameters for the U.-calibrated empirical roundabout model. 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 . This real-valued keyword allows the specification of the entry radius (in meters or feet). The entry radius is defined as the minimum radius of curvature of the curb line at the entry. 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. Capitalizing as EntryWidth might improve readability. Cube Voyager Reference Guide 323 .calibrated empirical roundabout mode.K. one of the geometric parameters for the U.Intersection Modeling Roundabouts 7 ENTRYWIDTH NOTE: Keywords are case insensitive. This real-valued keyword allows the specification of the entry width (in meters or feet). the double arrow marked “C” and “EWID” illustrates the measurement. Let C be the mid point of D-B. e). Capitalizing as FlareLength might improve readability. 324 Cube Voyager Reference Guide . Let D be a point on A-b such that the length of A-D is v. This real-valued keyword allows the specification of the modified flare length (in meters or feet) for the entry to an empirically modelled roundabout. Let v be the approach width. 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.7 Intersection Modeling Roundabouts FLARELENGTH NOTE: Keywords are case insensitive. 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). INSCRIBEDDIAMETER NOTE: Keywords are case insensitive. Usually this is the largest circle that can be inscribed wholly within the outline of the junction (see figure below). However. Empirical roundabouts: Example The following example uses geometrical data to calculate slopes and intercepts: Junction. Cube Voyager Reference Guide 325 . This real-valued keyword allows the specification of the inscribed circle diameter of the roundabout (in meters or feet).Intersection Modeling Roundabouts 7 • • 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’. a local value in the region of the entry should be taken. when the intersection is very asymmetrical. Capitalizing as InscribedDiameter might improve readability. ApproachWidth = 7. ApproachWidth = 6. InscribedDiameter = 25.0.0. Approach1 = 223. FlareLength = 25.0.0. FlareLength = 15.0. InscribedDiameter = 25. Approach1 = 223.0. Node = 213. ApproachWidth = 6. InscribedDiameter = 25. EntryWidth = 10. InscribedDiameter = 25.0. Approach = 321.0. Type = Roundabout.3.0. it was decided to recode approach 224 to give the slope and intercept directly: Junction. ApproachWidth = 6. Approach = 321.2. FlareLength = 15.0.0. Approach = 224.5.7 Intersection Modeling Roundabouts Node = 213. EntryWidth = 10.0. Approach = 223.0. EntryWidth = 10. ApproachWidth = 6. CapacitySlope = 0. InscribedDiameter = 25.0. Type = Roundabout. CapacityIntercept = 3600. Approach = 223. After comparing the model results to the performance of the intersection on the ground. EntryWidth = 10.0. 326 Cube Voyager Reference Guide .0. EntryWidth = 12. FlareLength = 15. Approach = 224.0. FlareLength = 15.0. FOLLOWUPTIME NOTE: Keywords are case insensitive.6 seconds. Highway Capacity Manual 2000 suggests that.1 seconds. for a singlelane roundabout entry in the US. Capitalizing as FollowUpTime might improve readability. The critical gap. is one of the parameters of any gapacceptance capacity model.1 to 4. the critical gap should be in the range 4. The U. Highway Capacity Manual 2000 suggests that. in seconds. The U. in seconds. it is applicable by arm. The follow-up time. 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.Intersection Modeling Roundabouts 7 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. for a singlelane roundabout entry in the America. it is applicable by arm. At roundabouts.S.S. is one of the parameters of any gapacceptance capacity model. Cube Voyager Reference Guide 327 . It is defined as the minimum time interval in the circulating stream that allows intersection entry for one vehicle. At roundabouts.6 to 3. the follow-up time should be in the range 2. 6.1.1. Approach1 = 32. Type = Roundabout.6 328 Cube Voyager Reference Guide . CriticalGap = 4.35. Approach = 256. CriticalGap = 4.85. Node = 253. Approach = 486. CriticalGap = 4. FollowUpTime = 2. 208. FollowUpTime = 2. FollowUpTime = 3. Approach = 32.7 Intersection Modeling Roundabouts Gap-acceptance roundabouts: Example The following illustrates a gap-acceptance roundabout model: Junction. very large capacities may be reported. (where “twoway yield-controlled intersections” are rare). but must give way to any major road traffic. Cube Voyager offers two model variants.. 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.K. which is unconstrained. Cube Voyager Reference Guide 329 . The capacity is chosen to give the correct ratio of volume to capacity (as calculated for the constrained movement). (where “priority junctions” are common) and the U. the yield signs are optional. or approaches (at a crossroads) have “yield” signs.Intersection Modeling Priority junctions 7 Priority junctions This section describes priority junctions (two-way yield-controlled intersections). In the U. It has different names in the U. In the U.. both of which are calibrated to U.S. the minor road approach (at a “T”). shares a lane.K. Traffic on the minor need not stop before entering the intersection. 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. This occurs when a movement. When a single-lane major road is being modeled.S.K. Capitalizing as SingleLane might improve readability. “GapAcceptance=n”. The logical-valued keyword is used to indicate that an approach consists of a single lane. SINGLELANE NOTE: Keywords are case insensitive. 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. invokes modeling of layout geometry at a priority junction. The default.7 Intersection Modeling Priority junctions Keywords This section describes keywords for priority junctions: • • GEOMETRIC SINGLELANE GEOMETRIC The keyword “Geometric=y”. at a priority junction is for the user to supply saturation flows directly. 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 . a minor arm. road markings). Its value is the width. CANSHARERIGHT. At two-way stop-controlled intersections and priority junctions. then CENTRALRESERVATIONWIDTH should be zero (the default). 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.Intersection Modeling Priority junctions 7 Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES. of the curbed central reservation in the major road. which does not have SINGLELANE = Y explicitly coded. Otherwise its value should be in the range from 2. or CANSHARELEFT on that approach. CENTRALRESERVATIONWIDTH is a real-valued keyword (only) applicable to geometrically modeled priority junctions. If there is no central reservation. or the central reservation is composed of ghost islands (that is. in meters or feet.2 to 5. has two lanes. Capitalizing as CentralReservationWidth might improve readability. Cube Voyager Reference Guide 331 . Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction. 332 Cube Voyager Reference Guide . 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. on two-lane minor approaches to priority junctions. 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. the CENTRALRESERVATIONWIDTH is given by ½(W5 + W6).7 Intersection Modeling Priority junctions In the diagram below. However. separate values should be supplied for each of the two lanes. CROSSING2ENTRY This keyword specifies the position of a zebra crossing on an approach to a roundabout or a minor approach priority junction. a single integer value should be supplied. If it is absent then no crossing will be modeled. Capitalizing as FreeFlowCap might improve readability. FREEFLOWCAP NOTE: Keywords are case insensitive. CROSSING2EXIT This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. Cube Voyager Reference Guide 333 . MAJORROADWIDTH is only applicable to geometrically modeled priority junctions. the unmodelled movements from the major approaches of a priority junction have infinite capacity. It is illustrated in the four diagrams below. In each case the major road width is given by the expression ½(W1 + W2 + W3 + W4).Intersection Modeling Priority junctions 7 By default. in meters or feet. MAJORROADWIDTH is a real valued keyword whose value is the width. this may result in too large a capacity for the approach as a whole when it must share a lane with a modelled turn. However. MAJORROADWIDTH NOTE: Keywords are case insensitive. Capitalizing as MajorRoadWidth might improve readability. The presence or absence of this keyword allows the two methodologies for priority junction modeling to be distinguished. where it is required. of the major road lane (excluding any central reservation or ghost islands) near the intersection. You can supply a capacity for these movements by coding FreeFlowCap=value and SingleLane=t. 7 Intersection Modeling Priority junctions VISIBILITY This real-valued keyword allows the visibilities. at a geometrically coded priority junction (two-way yield-controlled intersection) to be entered. towards the road center line. in meters or feet.05 meters above the road surface. The major road visibility is measured from the mid-point of the turning lane (again at height 1. 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. 334 Cube Voyager Reference Guide . along the major road.05m). Geometric priority junctions: Example This example illustrates the coding of a three-arm priority junction. Code the width of the right lane in the right movement. Code the width of the single lane in the left movement. Type = Priority. Code the width of the left lane in the left movement. Node = 250. Width = 2. Coding techniques for minor roads vary with the number of lanes. but not both. Cube Voyager Reference Guide 335 . MajorRoadWidth = 10. Approach = 455. The coded widths should be the lane’s average width during the final 25 meters of the approach before the give-way line. The width for the major road’s opposed movement is the width of the lane from which vehicles on the major road turn. To describe a two-lane minor road: • • • Do not code SINGLELANE = T.2. Movement = Right.5. with input geometric data. Code widths for left and right movements on minor roads and for the opposed movement from the major road.Intersection Modeling Priority junctions 7 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). To describe a one-lane minor road: • • Code SINGLELANE = T. CentralReservation = 1.9. Approach1 = 455. Junction. or the right movement. Movement = Left.0. Movement = Right. Movement = Right. Width = 2. Approach = 255. This keyword specifies that there is a shared lane to the left of the exclusive lanes for this movement (that is. Visibility = 127. SingleLane = y. Approach = 251.7 Intersection Modeling Priority junctions Visibility = 170.0. Note that this keyword does not 336 Cube Voyager Reference Guide . Width = 3. the movement can share with the movement to its left). Visibility = 150.0. Capitalizing as CanShareLeft might improve readability.0.9.05. Visibility = 130. Approach = 249.1. Visibility = 125. Movement = Right.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. Width = 2. Movement = Left.05. Width = 2.0. Visibility = 100. If a movement has CANSHARERIGHT = T coded. and the movement to this movement’s right must have CANSHARELEFT = T coded. CANSHARERIGHT NOTE: Keywords are case insensitive. Cube Voyager Reference Guide 337 . If SingleLane = t then ExclusiveLanes should not be coded. If SINGLELANE = T then CANSHARELEFT should not be coded. Capitalizing as CanShareRight might improve readability. then there must be a movement to this movement’s right. If a movement has CANSHARELEFT = T coded then there must be a movement to this movement’s left and the movement to this movement’s left must have CANSHARERIGHT = T coded.Intersection Modeling Priority junctions 7 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. 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 SINGLELANE = T then CANSHARERIGHT should not be coded. This integer-valued keyword gives the number of lanes. EXCLUSIVELANES NOTE: Keywords are case insensitive. on the specified approach. Capitalizing as ExclusiveLanes might improve readability. the movement can share with the movement to its right). This keyword specifies that there is a shared lane to the right of the exclusive lanes for this movement (that is. which are reserved for the exclusive use of vehicles making the specified movement. 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. Node = 229. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly. Approach = 396. 338 Cube Voyager Reference Guide . CanShareLeft = y. 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. Movement = Through. except that no signal aspects are involved. ExclusiveLanes = 1. Junction. Movement = Through. CanShareLeft = y. CanShareLeft = y. ExclusiveLanes = 1. Movement = Left. CanShareRight = y. Movement = Right. CanShareRight = y. Approach1 = 396. Type = Priority. Approach = 228. ExclusiveLanes = 1. ExclusiveLanes = 1. This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. ExclusiveLanes = 1.7 Intersection Modeling Priority junctions SATFLOWPERLANE NOTE: Keywords are case insensitive. Capitalizing as SatFlowPerLane might improve readability. Movement = Left. CanShareRight = y. CanShareRight = y. ExclusiveLanes = 1. Movement = Right. Movement = Through. CanShareRight = y. CanShareRight = y. CanShareLeft = y Cube Voyager Reference Guide 339 .Intersection Modeling Priority junctions 7 CanShareRight = y. Movement = Right. ExclusiveLanes = 1. ExclusiveLanes = 1. Movement = Right. Movement = Through. Approach = 315. ExclusiveLanes = 1. Movement = Left. CanShareLeft = y. Approach = 409. Movement = Left. CanShareLeft = y. CanShareLeft = y. CanShareLeft = y. ExclusiveLanes = 1. CanShareRight = y. 7 Intersection Modeling Priority junctions 340 Cube Voyager Reference Guide . Cube Voyager Reference Guide Cube Voyager Reference Guide 341 . 8 Network Program 8 Network Program This chapter discusses the Network program. Topics include: • • • • Introduction to the Network program Control statements Theory Examples 342 Cube Voyager Reference Guide . TP+. the program immediately writes it in Cube Voyager format to a temporary file. The program processes each of these records using logic that you can control. the Network program requires a node variable. No auxiliary files will be open. the Network program requires an A-node. Node and link records in a given data file need not be unique. named A. It is a network database that contains speed/capacity information. In MINUTP networks. 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. Optionally. and a B-node. The program generates a data record for each unique node and each link found in any of the input files. Upon detecting a Tranplan network as input. or TRIPS binary network format. and edit the network in Cube Graphics.and Y-coordinates of each node. the node information consists solely of coordinates for each node. standard database in dBASE style (DBF). named X and Y. In a Cube Voyager or TP+ network. the node records must also have two additional variables. and can generate one output network. The program can process up to ten input networks simultaneously. The program can read input network files of various formats: ASCII records. Tranplan. and link records.) If you specify an output network. a file of link records and/or a file of node records may be written in either ASCII or DBF format. the program writes a file in a proprietary (Cube Voyager or MINUTP) binary format. that represent the X. named B. Each A-node and B-node must exist on a node record. For a valid node record. You can summarize and report on the processed data. To open.Network Program Introduction to the Network program 8 Introduction to the Network program Network is a utility program for processing highway networks. there may be any number of items for nodes. Beginning with Cube Voyager Reference Guide 343 . For a valid link record. (Note: Cube Voyager treats a FSUTMS network as a standard Tranplan network. view. MINUTP. or any Cube Voyager. Only Cube deals with FSUTMS networks differently. and then uses that file in place of the original file for subsequent processing. node records. Cube geodatabase networks. named N. 0. 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 . output networks may be a Cube Voyager custom network feature class.8 Network Program Introduction to the Network program version 5. records that are merged from other LINKIs retain their GEOMETRYSOURCE value. DBF. The Network program may take up to ten input networks. 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. you can specifically set the value in a script based on other attributes in the various input networks (for example. or combinations of link and node files in ASCII. Other input formats could also have a field called GEOMETRYSOURCE defined by the user. and other areas use LINKI[2]). The value of the GEOMETRYSOURCE field in the output network dictates the source of the link geometry. the output network could have a mix of GEOMETRYSOURCE values. for example). If Merge Record=T. By default. In addition.Network Program Introduction to the Network program 8 Built-in variables Variable A B GEOMETRYSOURCE Description Node number of a link’s A node Node number of a link’s 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. 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 . Therefore. the output GEOMETRYSOURCE field will have a value of 2 (unless there is no record in LINKI[2] for a certain link). This field’s value is the index of the input file (3 for LINKI[3]. or MDB formats. These ten networks can be any of the supported binary formats. Each input network coming from a geodatabase network will have a field called GEOMETRYSOURCE. Cube geodatabase networks. downtown use LINKI[3]. So if LINKI[1] is a binary network without a GEOMETRYSOURCE field and LINKI[2] is a geodatabase network. the value is taken from the first available value from all the input networks. capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass.spdclass) CAPACITYFOR(lanes. 346 Cube Voyager Reference Guide .8 Network Program Introduction to the Network program Built-in functions Function SPEEDFOR(lanes. Returns the capacity times the lanes for the designated number of lanes and capclass. ... “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 . 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.. ENDIF LOOKUP LOOP .. Control word ABORT ARRAY BREAK COMP COMPARE CONTINUE CROSSTAB DELETE EXIT FILEI FILEO IF .. ELSE ... ENDLOOP MERGE PARAMETERS PLOT PLOTTER PRINT PROCESS .. ELSEIF .Network Program Control statements 8 Control statements This section describes the control words available in the Network program.. Example IF (a > 1000) ABORT MSG='Must be the wrong Network' ARRAY Declares user single dimension arrays. Arrays can be useful for different processes. When an array is referenced. the most 348 Cube Voyager Reference Guide . VAR=size. it should include an index []. the program may fatally terminate. An array is different than a variable in that it represents vectored data. VAR=size Use ARRAY to allocate user arrays that are to be used in the process.8 Network Program Control statements ABORT Aborts the Network program and Cube Voyager. Values stored in arrays must be numeric. 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. and if the index exceeds the size. MSG Use ABORT to quit the Network program at with a “fatal” return code. Arrays cannot store string values. Arrays are cleared when they are allocated. Example 1 if (a=1-500 || b=1-500) BREAK . if (a.Network Program Control statements 8 common use may be to store information for specific zones. bypass the links that go from right to left BREAK endif Cube Voyager Reference Guide 349 . the remainder of the block operations are bypassed and the next data record is processed. Most likely. or a special name. and LINKS if there is a binary input network. However. The size following the keyword is the highest index possible for VAR. BN=LINKS. Special names are: ZONES. VAR must be a unique name. When a data record is being subjected to the operations in a phase block.x) . they are allocated prior to any stack operations. and the operation is BREAK. stack processing jumps to the statement after the associated ENDLOOP statement.x > b. VMT=LINKS . ARRAY variable Variable VAR |I| Description VAR is the name of the variable that is to be allocated according to the specified size. Example ARRAY abc=100. Size may be either a numeric constant. NODES. BREAK would be used in conjunction with an IF statement. do not process centroid links. ARRAY statements are not dynamic (stack oriented). NETI must be a binary network BREAK Breaks out of stack processing for current data record. xyz=100 ARRAY AN=LINKS. if BREAK is encountered within a LOOP. NODES and LINKS should not be used if links are to be added to the network. The program tries to detect any possible changes. This limit includes the “_” prefix of temporary variables._zones _total = _total + array1[index] if (_total>1000) BREAK endloop list=’INDEX =’. The phase for which this COMP statement is coded will establish which variables may be included within the expression. but there must be comma between an expression and the next variable=expression. but it might not detect all inconsistencies. BREAK jumps to here COMP Computes a value for a variable. unless it is a working variable (begins with an underscore). Variable = Expression COMP statements specify that new variables are to be created or that existing variables are to have new values computed for them. If a variable is misused as to mode. 350 Cube Voyager Reference Guide . There may be more than one variable computed on a statement. any name that appears on the left side of the equals sign will be placed into the output network record.index . the mode of the target (named) variable will be set to string instead of numeric. A normal numerical expression is required. The expression will be solved and the results stored in the named variable. A variable’s mode should be consistent throughout the application. The maximum length of the name is 15 characters.8 Network Program Control statements Example 2 /* this example finds the index where subtotal of ARRAY1 exceeds 1000 */ loop index=1. If the expression results in a string. or misuse of variable modes. During any phase other than the SUMMARY. The statement need not begin with COMP. and where the results can be stored. and the capacity extracted for that value would be multiplied by 9. the first argument is the number of lanes and the second argument is the class. The expression may contain function names with their arguments. if CAPACITYFOR (88.x)^2 + (a. k=j*2+3*i newb = nodecode(b) sumab = newb+newa cdist = sqrt((a. Returns the capacity times the lanes for the designated number of lanes and capclass. Thus. lanes would be reset to 9. the internal value will be reset to the appropriate limit.spdclass) CAPACITYFOR(lanes. such as always beginning with the same letter.Facility*10+Area) COMPARE Compares network records.Network Program Control statements 8 unpredictable results could occur. To obtain speed and/or capacity values from the SPDCAP tables. In the SPEEDFOR and CAPACITYFOR functions. Similarly. If the lanes value is less than 1.y-b.. RECORD (LIST TITLE) Cube Voyager Reference Guide 351 . They are coded as: Function SPEEDFOR(lanes. the function value of lanes will be reset accordingly. Example i = 0 j = a / i.y)^2) _LinkSpeed = SPEEDFOR(Lanes. if the second argument is less than 1.) were specified. or greater than 9.capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass. or greater than 99.x-b. the SPEEDFOR and CAPACITYFOR functions are utilized. It might be prudent to have a standard naming convention for string variables.. Record not in file one. then only the first 100 links with differences will be listed. Indicates how many of the links with differences are to be listed to the print file. a single line is generated. In addition to a summary report. TITLE |S| Optional title to print with the summary report. At the end of the phase (NODEMERGE or LINKMERGE). COMPARE keywords Keyword RECORD |IP| Description Indicates which LINKI or NODEI set of records is to be compared. If LIST=100. LIST |I| 352 Cube Voyager Reference Guide . The meaning of the returned value is as follows: Value of _COMPARE n 0 -1 -2 Meaning n attributes are different between two records. This keyword may occur only one time on a COMPARE statement. If a link exists in one file but not in the other. To make this statement function properly. The value is stored in a temporary variable: _COMPARE. the MERGE RECORD=T statement should be coded. COMPARE also returns a value indicating the result after the comparison of each record. if the record keys match.8 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. Two numbers. But. No differences between two records. The LIST parameter controls the listing of individual differences. There may be multiple COMPARE statements in a single application. each variable for which there is a difference will be listed on a separate line with the values from both files and the difference. separated by a dash. must be coded. The default is 0. a summary of the comparison is reported. Record not in file two. It is suggested that the value be embedded within quotes. 23 1.--. link in both but different ENDRUN Example 2 illustrates how to use _COMPARE to flag the links in the merged network.321 1 1 -1 DISTANCE -. NET2.23 -- The 1=2 column lists the number of records where the records are the same. compare link record 1 with 2 IF (_COMPARE=-2) CMPFLAG=1 .321 1. link in NET1.--. LIST=20 .321 2 2 -2 CAPCLASS -.1 < 2 ------Variable Cnt Cnt Min Max Ave -------.-- Ave -----1 -1 -2 -1.-.--.321 ------. 2: 1=2 ------.-. The CMPFLAG attribute can be used in selection expressions in Viper to post the comparison results.NET MERGE RECORD=T PHASE=LINKMERGE COMPARE RECORD=1-2.--.-. not in NET1 IF (_COMPARE>0) CMPFLAG=3 .NET. The final AVE column lists the average difference for the variable.--7 -.-. Cube Voyager Reference Guide 353 . and the 1 > 2 set lists the summary where file 1 values are greater than file 2. Example 2 RUN PGM=NETWORK NETI=NET1.-7 -.--.321 1 1 -1 SPDCLASS -.-.-.--.-. using only records where there is a difference.-.23 NAME -.-.net LINKI[2] = future.--.net COMPARE RECORD=1-2 The following is a sample output in the print file: COMPARE 1 vs.-. 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.--------A 321 ----B 321 ----LANES -. link in NET2.1 > 2 ---Cnt Min Max Ave --.-.--.Network Program Control statements 8 Example 1 LINKI[1] = current. The Min and Max differences show the range of differences for the variable. not in NET2 IF (_COMPARE=-1) CMPFLAG=2 .NET NETO=NET3.23 -1.-. the report collapses into only one column or one row. Use the ROW keyword along with the RANGE subkeyword and the COL keyword along with the RANGE subkeyword to specify the table’s dimensions. control passes to the appropriate ENDLOOP statement. the statement tabulates all the variables to the same specifications. bypassing all stack statements until the associated end of loop. 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.3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ._KINC LOOP _L3=_L2. Example LOOP _L1=1. Although the CROSSTAB statement can include several instances of the VAR keyword.8 Network Program Control statements CONTINUE Immediately jumps to the end of a loop. If it is within a loop. Use the COMP keyword to generate additional reports after network generation using the values from the 354 Cube Voyager Reference Guide . If you omit either ROW or COL._K2. stack processing for the record is terminated. no more processing for this data record LOOP _L2=_K1._L2+5 IF (condition) CONTINUE . jump to ENDLOOP for _L3 ENDLOOP ENDLOOP CROSSTAB Cross tabulates variables. Otherwise (not in a loop). 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. but applies to the COL variable. VehTime. Care should be taken to not cause the reported line to be too long (limit the number of column ranges). Same as for ROW (RANGE). The standard Cube Voyager FORM syntax is used. and to all subsequent COMP variables until a new value is encountered. if the statement includes VAR = VehDist. For example.” The format applies to the COMP that it is coded with. COMP |NV| COMP FORM |S| ROW |S| Cube Voyager Reference Guide 355 . There may be up to ten COMP expressions on a statement. NOTE: The program does not automatically produce totals because your ranges may overlap. 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.Network Program Control statements 8 tabulated variables. 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. If FORM is not coded for any COMP. Specifies the format for the COMP reports. See below for a description of the process used in placing values in the appropriate range slots. then including COMP = VehDist / VehTime would produce a table of average speeds. the program will supply “7cs. You can produce totals and subtotals with appropriate use of RANGE values. 8 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. The value of each variable will be accumulated into the cells of the generated table(s). digits. they are discussed below. If FORM is not coded for any VAR. Each range has a lower limit. the program will supply “7cs. an upper limit. VAR |SV10| VAR FORM |S| Range classification strategy The ROW RANGE and COL RANGE values are stored as singleprecision numbers. A separate report will be generated for each variable named. The standard Cube Voyager FORM syntax is used. the program generates a row for each increment. Because computers do arithmetic on a binary basis. A range as either one. significant digits. Name(s) of the variable(s) that are to be tabulated. There may be up to ten VAR keywords on a statement. and progressing until the upper limit is reached.01 is a definite number in base 10. The first format will be backfilled to apply to any prior VAR variables. If more than one number. the values are separated by dashes. For example: the number 0. but it can only be approximated in base 2. The three values are low. whereas double precision provides accuracy to up to fifteen. or seven. two. Format to use when printing the accumulated values in the table. high. If there is no increment. and to all subsequent VAR variables until a new value is encountered. If there is no upper limit. or sixteen. There are certain problems associated with stratifying non-integer data. the program makes the upper limit equal to the lower limit. the program assumes one row. If the program compares a variable to a 356 Cube Voyager Reference Guide . Single precision provides accuracy to about six. If there is an increment. and increment. The program establishes ranges for stratifying the ROW variable values. or three numbers.” The format applies to the VAR that it is coded with. and an increment. starting at the lower limit. numbers which seem to be easily described in base 10 cannot always be represented exactly in the computer. and the actual variable values are computed and stored as double-precision floating-point numbers. You can control the level of precision when specifying the RANGE values. If RANGE is 1-10. The RANGE values and the ROW and COL variable values are factored and integerized (rounded) according to the decimal digits. If the value fits with the range.5 1-3-0.45 3.9999999999 be included in it? If RANGE is 1-10-1.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.3 1-3-0. should a value of 10. RANGE 1-10 1-10-1 1-10-1 1-10-1.0001 fall into? To address all these concerns. and which range should the value of 2. the value satisfies the range.5 1-3-0.50 1.99 1.00 1. or equal to. should a value of 0. a similar initial check is made to determine if the value fits within the outer RANGE limits.01 3. it might fail due to this limitation of the computer. and less than.3 1-3-0.45 1. The comparison result may differ. the increment index is computed (in integer) as: ((value-lo) / inc) + 1. If a single RANGE (no increment) is used.45 1. the program checks the value against the limits as: if the value is greater than. or equal to. The level of precision is set by the maximum number of decimal places in any of the RANGE values (low-high-increment). depending upon the floating point capabilities of the computer. If a RANGE with an increment is used.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 .0 1-10-0. Another concern is the definition of limits.Network Program Control statements 8 range limit.001 be included. the program is designed to check for RANGE satisfaction based upon an integer representation of both the RANGE limits and the data.29 3. the higher value. the lower RANGE. Examples may best illustrate this process. 3 .5-9999.5-1. Use EXIT to exit the current phase. For this reason.1c.2. 358 Cube Voyager Reference Guide .remove all links connected to nodes 2150-2199 EXIT Exits current phase. DELETE would be used in conjunction with an IF statement. Most likely. VAR=VMT FORM=6.647. FORM = 6.5. _CNT. 1-7. and the record is removed from the network. COMP=sqrt(VMT)+10*(min(1000. The remaining input records to the phase will not be read. the program may adjust the number of decimal digits if either RANGE limit would exceed the maximum after revising. 1-3.1. When a data record is being subjected to the operations in a phase block. ROW=CLASS.2c.5-0.2-2. ROW=VC. Example If (a=2150-2199 || b=2150-2199) DELETE . COMP=VMT / VHT. COL=LANES. no reason to process beyond this link. VAR=VHT. RANGE=1-7-1. 1. FORM=8. 0. and the operation is DELETE. COL=LANE. RANGE=0. RANGE=1-10.8 Network Program Control statements There is a caveat with this process. 4-7.5-1.VHT)). 2. the remainder of the block operations are bypassed. Example CrossTab VAR=DIST. The maximum integer revised value for either RANGE or ROW is 2. RANGE=1-50-1.483.147. Example IF (a > 1000) EXIT. 1-100-5.2-0. weird example & ave trip length CrossTab DELETE Deletes data record. Network Program Control statements 8 FILEI NOTE: See “FILEI” on page 48 for general information about FILEI and for important limitations when using Application Manager. The program does not edit input record keys before stack processing. provide a NODEI file with the same index as the LINKI file. the program truncates field names longer than 15 characters. To preclude the program from using the node data in the automatic NODEI file (not recommended). MAX=). If truncation results in duplicate field names. the automatic corresponding NODEI file is the network’s node stand-alone feature class. Cube geodatabase networks have associated link and node stand-alone feature classes. the program automatically renames fields to avoid duplicate names. you may list non-binary LINKI and NODEI files in any order. If the limits are exceeded. Upon reading input files. the program automatically assumes a corresponding NODEI file. Inputs data files. You can decide how to handle Cube Voyager Reference Guide 359 . If you code value limits for a variable (with MIN=. Upon recognizing a LINKI file as a binary file. the program rejects the record as an error and does not process the record. If a LINKI file is a Cube geodatabase network. You may designate up to ten NODEI and ten LINKI files in a FILEI statement. the program only checks those limits during the INPUT phase. NODEI files that have the same index as a binary-network LINKI file must precede the LINKI file. 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. On the other hand. CAPC.CAPCLASS. 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. Since most applications will input binary networks or Cube geodatabase networks. the variables DIST. 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. Cube geodatabase network. the program lists the record as an error. it will assume ASCII. or B) and DELETE the record. If it cannot identify the file as a DBF. NOTE: A valid network in Cube Voyager/TP+ need not have coordinate variables on the node records. The program will try to detect what type of file it is.8 Network Program Control statements records with invalid keys. and LANE will automatically be renamed to DISTANCE. 360 Cube Voyager Reference Guide . SPDC. or recode the key. and LANES. If the input file contains many extraneous records (invalid data records—possible if coming from a GIS DBF with extra data). If it detects that the file is a MINUTP binary network. you can use the keyword NETI as an alias for LINKI. MDB. If these fields in the DBF or MDB do not use this naming convention. 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 a key is outside this range. SPDCLASS. After stack processing. A. respectively. or a binary network. FILEI keywords Keyword LINKI Subkeyword |KFV10| Description Name of a file that contains link-based records. If the LINKI file and the NODEI file are DBF or MDB format then at a minimum. the program ensures that key values range from 1 to the number of nodes. you can check the key (N. then the RENAME keyword below can be used to rename the variables on input. the unlisted vars will be set to LAST.v4 ave=v6. AVEX0 The descriptions of these keywords are identical to those described for the MERGE statement. variables during the run. 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.v7. and you do not want to extract certain variables from the input records. vars= v1.v3. LAST.v3.Network Program Control statements 8 FILEI keywords (continued) Keyword LINKI Subkeyword COMBINE |?| Description Flag that indicates whether multiple link or node records exist on the input data file.v4. The default for any variables not combined will be consistent with the value of PARAMETERS REPL_DUPL.v2. Use to rename a variable from the input file. AVE.y. Only relevant if the file is a DBF or binary network file and you do not want certain variables from the file. If REPL_DUPL is true. first=x. ave=v1.temp1-V2 Cube Voyager Reference Guide 361 .x. MAX. The following subkeywords can be used to specify how to combine attributes values across multiple link or node records.v8 combine=t. vars=n. Name(s) of variable(s) excluded from the file. FIRST. Example of usage: FILEI LINKI=linki. MIN. combine=t. or if the input is defined as a series of variables (in delimited format -.V2-V1.dat. SUM.not with BEG/LEN).v8 FILEI NODEI=node. The format is RENAME=oldname-newname.dat. both names must be specified. CNT.v6. LINKI EXCLUDE |SV| LINKI RENAME |SP| Names can be swapped on one statement. otherwise to FIRST.v5. to swap names for V1 and V2: RENAME=V1-temp1. which is the actual data record. and how to identify it. Used only with ASCII input where the first valid data record follows some identifying header record. The expression value must be enclosed within parenthesis (). The record variable defined as REV will be treated as any other link variable. The primary purpose is to allow the user to specify that there is a header. and before any field editing. If the value is not a 1 or a 2. This keyword is only required for TRIPS networks. The REV parameter is used only if: • • There is no REV variable on the record. with the B-A values being the same as the A-B values).8 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. If there is a VAR=REV defined for the link data records. the value of the REV should be a 1 or a 2. Under normal conditions. STOP is processed immediately after a record is read. SELECT is processed after any STOP statement. START is used to position the file before actual data records are read. There is a REV variable on the record. LINKI SELECT [s] Used only with ASCII input when it is desired to select only certain records from the file. LINKI START [s] LINKI STOP [s] LINKI TRIPSXY [F] 362 Cube Voyager Reference Guide . the reversibility of the link is determined by the value assigned to this keyword. but its value is neither 1 nor 2. Used in a manner similar to the START keyword. but it will not be written to the output network (the NETO will not contain a variable named REV). an input record represents a single directional link from A to B. but is associated with a trailer record. The expression should contain a SUBSTR function to extract the header. and the only valid variable is RECORD. the default is 1. Name of a file that contains TRIPS X-Y data. The syntax is the same as for START. and before any editing. The only valid values for this keyword are 1 and 2. 3 1 .. the variable will be rejected as an error.. May be used to specify a minimum allowable value for the field. a comma. LEN |I| TYP |S| MIN |R| Cube Voyager Reference Guide 363 . 2.2.2. where n specifies the number of characters. 0-9).3 All four of the above illustrated records contain three fields: 1.Network Program Control statements 8 FILEI keywords (continued) Keyword LINKI Subkeyword VAR |SV| Description Name of a variable to be extracted from the file. The program assumes that ASCII files are free format and all fields are separated by white space. 2 3 1 . if they contain special characters (other than alphanumeric characters: a-z. If the input value of the variable is less than this value. BEG and LEN will have to be specified. To read variables from fixed-format text files. If TYP=A is specified for free format input. BEG. the LEN must also be specified. use the subkeywords TYP and LEN. use the BEG and LEN subkeywords. and 3.. case is ignored. The first column of the record is designated as 1.. To read character-string variables from fixed-format text files. and the variable is to be extracted from specific positions on each file record. or append (C) or (Cn) to the variable name. and LEN subkeywords. Examples of free-form records: 1 2 3 1. TYP A variable values on free format input must be enclosed within quote or literal marks ('.' or ". To read character-string variables from free-format text files. use the TYP. Subkeywords of VAR include: BEG |I| Designates the beginning of the field in the input records. May be used to specify that the format of the variable is not numeric. Designates the length of the field that begins at position BEG. An “A” means that the variable is alphanumeric. If the file is ASCII."). or it will default to 1. or some combination of both. Name lengths may not exceed 15 characters. Y .dat. If the first two numbers that follow the name are separated by a dash. and B is in columns 6-10).dat.dbf..B.5.len.b.beg=6. var=rev.beg=14. You must index LOOKUPI. If both forms may be used to specify variable (numeric format.len=5. the numbers indicate the actual columns of the data record where the field is located. See “LINKI” on page 360 for comments regarding file detection.dat exclude=dist.8 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).len=5. For example: VAR=A.5 (A is in columns 1-5 and B is in 610). file is ASCII NODEI[2]=\demo\demo21. followed by any of the sub-keywords). The total format is name.section. All these fields must be numeric.0.1. Example This section contains some examples of FILEI LINKI and FILEI NODEI usage.21. file is binary network NODEI[1]=C:\DEMO\DEMOXY. 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. VAR=a. var=b.fil. var=dist. Equivalent to the FILE keyword of the LOOKUP control statement.beg=35.B.5 .tsin .dbf 364 Cube Voyager Reference Guide . linki[4] = c:\citya\nets\nodea. The parameter list is considered as exhausted when a non-numeric field is encountered.1.6. or null.max.min.DAT VAR=N. Typ must be coded as 1 to indicate that the variable is to be an alphanumeric field.beg. var=a.section follows name in free form nodei[4]=c:\citya\nets\linka. A null field is specified by coding two commas with nothing between them..len=1 LINKI[3]=freeform. this format is automatically triggered. NODEI |KFV10| Name of a file or an MDB and element that contains node-based records.len=4.1-5. Example: VAR=A.typ. LINKI[2]=\demo\?07.X.6-10 (A is in columns 1-5. If the field following the variable name is a number. NODEI uses the same keywords as LINKI except REV and TRIPSXY.beg=1. LINKI[1]=\demo\demo20.name.5. tab is code 9).). See “Defining a numeric print format” on page 70 and “Defining a character print format” on page 71.2)=='LD').2)=='LD') FILEO Generates output files—a network file. start=(substr(record.1.lxy. 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. Sets the print format of all variables written to the file. LINKO LINKO EXCLUDE FORM |SV| |S| Cube Voyager Reference Guide 365 .Network Program Control statements 8 LINKI[8]=Mixed_Node_and_Link.2)=='XY') NODEI[8]=Mixed_Node_and_Link. stop=(substr(record. and node file. start=(substr(record. To specify special characters (.1. LINKO DELIMITER |S| Character used as the delimiter in SDF and TXT files. . var=n./ + * = .1.d to indicate the maximum field width and number of decimal places to preserve.x.distance.lxy.b. but there is no default value for TXT files. stop=(substr(record. May be any of the formats described by the FORMAT subkeyword or may be an MDB/element name. var=a. enclose within quote marks or specify using its decimal equivalent (for example.2)=='XY'). The default value is a comma.1. Optional format codes are usually not appropriate for use on this statement. link file. Usually specified as w.y. Similar to EXCLUDE under NETO. the program will try to adjust the field form within typical database rules to fit the value into the field space. the latest appearance prevails. The same variable may be included multiple times. Specify a variable name with its desired format appended in parenthesis. and separated by a delimiter DBF — Industry-standard database file If there is a ? in the name. Similarly. B(4. VARFORM=A(4.0). the program first determines a default format. INCLUDE variables may have a format appended to their names in a manner similar to VARFORM. Only specify this keyword for variables that require specific formats. If a DBF is written. if the same variable appears with both a VARFORM subkeyword and an INCLUDE subkeyword. Therefore. Sets the format for specific variables. an extension of this value will be appended to the filename. LINKO INCLUDE |SV| Similar to INCLUDE under NETO. and there is no filename extension to the LINKO value.8 Network Program Control statements FILEO keywords (continued) Keyword LINKO Subkeyword FORMAT |S| Description Sets the file format of the LINKO file. When setting a variable’s format. Then.0) sets A and B to be formatted as 4 characters wide with no decimal places. If the file format is SDF. and a designated FORM does not provide adequate width and decimal space for a field value. • LINKO VARFORM |SV| 366 Cube Voyager Reference Guide . the latest FORM prevails for any variables not explicitly named in a VARFORM and/or INCLUDE subkeyword. the program applies the formats as they appear on the statement. 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. For example. NETO |KF| Name of the standard output network that the program writes. the program deletes leading spaces. Specifies the file format for writing the output network. The program also creates two stand-alone feature classes in the MDB file. If the NETO keyword specifies an MDB/element name. the output network only includes the listed variables. To exclude a variable from only the link records. prefix to the variable name. add the LO. add the NO. element_Node and element_Link. If you use this subkeyword. Cube Voyager ignores listed variables that do not exist in any of the input files. To exclude a variable from only the node records. NETO INCLUDE |S| List of variables included in the output network. Specify FORMAT=MINUTP to write a MINUTP network. Listed variables that exist in both node and link records are excluded from both records. and a table.Network Program Control statements 8 FILEO keywords (continued) Keyword NETO Subkeyword EXCLUDE |S| Description List of variables excluded from the output network. The output Cube geodatabase network will contain the additional link and node attribute. NETO FORMAT |S| Cube Voyager Reference Guide 367 . Specify FORMAT=TRIPS TRIPSXY=fname to write a TRIPS network and its associated XY file. MINUTP string variables are truncated to 80 characters. and does not issue a warning. this is not specified. GEOMETRYSOURCE. that contains the indices and values from the internal speed and capacity table. the program writes the output as a Cube geodatabase network in the MDB file under the element name. Do not use with the INCLUDE subkeyword. Do not use with EXCLUDE subkeyword. Normally. prefix to the variable name. element_SPDCAP. 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). the program will write the file as a standard Cube Voyager binary network. The program derives both LINKO and NODEO from the output network.8 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. 368 Cube Voyager Reference Guide . if you specify NETO and exclude a link variable. May be any of the formats described by the FORMAT subkeyword under the LINKO keyword. use that value Else if lowest LINKI contains a LEFTDRIVE value. the program generates an output network first even if NETO is not specified. When writing output files. Use the MERGE statement to specify how to process duplicate records. the link and node files are subsets of the output network. See APPEND under “PRINT” on page 66. The program produces output files by combining data from the input files. Consequently. use that value Else do not set this value Name of a non-Cube Voyager output file in which program writes node records. the output files will contain the fields from all the input files. use that value Else if NETO LEFTDRIVE is specified. Unless you specifically exclude fields with the EXCLUDE subkeyword. then that link variable will not be available for LINKO. 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 may be an MDB/element name. or if PARAMETERS LEFTDRIVE is specified. PRINTO PRINTO APPEND |KF| |?| Name of the file where the program directs output from a PRINT statement using PRINT PRINTO=#. even if you do not merge the files and the output file contains no data from a particular input file. Its subkeywords are the same as those for LINKO. The setting of the NETO value follows the rules: • • • • NODEO |KF| If PARAMETERS LEFTDRIVE is specified. This is primarily for use in JUNCTION modeling in the Network program. NET NETO=DEMOMINU. ELSEIF ..DAT. TEMP2 NODEO=TEXTNODE FORMAT=TXT. Enclose the IF and ELSEIF selections within parenthesis. ELSE . ELSEIF . Code IF condition blocks like standard Cube Voyager specifications. the selections can reference any variables that are valid for the current phase.Linc ...Lend..3. FORMAT=MINUTP. 8-42 && X<3000 || Y=1-500.. ENDIF ENDPROCESS IF (I < (K*3/6 +J) ) DELETE LOOP .. ENDLOOP Controls a general variable loop....Network Program Control statements 8 Example FILEO NETO=MY..800-900) .B.. ENDLOOP where: Cube Voyager Reference Guide 369 . Example PHASE=INPUT. FORM=8. ELSE .3) IF .SPEED..DIST. ENDIF” on page 52 for more details..1 IF (N==5) . ELSEIF (N=1.. LOOP LVAR=Lbeg... ELSE .SPDCAP(2) LINKO=LINK FORMAT=DBF VARFORM=VC(6. EXCLUDE=TEMP1. ENDIF Performs certain operations based on conditions. FILE=NI. .0 INCLUDE=A. See “IF . Lbeg is a numeric expression that initializes LVAR. by Lend and Linc. If Lend is not specified. Lend is a numeric expression that is computed and stored when the LOOP statement is first processed. and other LOOP statements can alter its value. Compute the value for Linc (default to 1 if missing). LOOP initializes a variable(LVAR). • • • NOTE: All variables in a LOOP statement expression (Lbeg. LVAR is incremented by Linc. program. If Linc is not specified. a backwards loop). it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend. The value is added to LVAR before the ENDLOOP comparison is made. • At ENDLOOP: If Lend not specified. Linc) must begin with the underscore character ‘_’ to prevent confusion with record variables. and optionally. Lend.8 Network Program Control statements • LVAR is the name of the loop control variable. ENDLOOP compares the contents of the variable to another value (Lend). computational. Proceed to next statement. it is assumed no comparison is to be made (rather meaningless loop). they may not overlap IF blocks. and compared with Lend when the ENDLOOP statement is processed. The logic is as follows: • At LOOP: Initialize LVAR to Lbeg. LVAR is not protected during the loop. and branches back to the statement following the LOOP statement if the comparison fails. Compute the value for Lend. Linc is a numeric expression that is computed and stored when the LOOP statement is first processed. 370 Cube Voyager Reference Guide . LOOP blocks may be nested. jump to next statement. Use LOOP…ENDLOOP blocks to repeat of a series of statements. LVAR must be followed by Lbeg. _xyz+2.10 . Example LOOP _pass=1. Lbeg._ghi+_jkl. The loop will be processed at least one time regardless of Lend and Linc values. nested LOOP .. This helps to protect against possible endless loops. The Lend and Linc variables are processed somewhat differently than in the other programs. 5. perform 10 passes .. Lend. Either jump back to statement following associated LOOP. perform 3 passes -. RECORD AVE AVEX0 CNT FIRST LAST MAX MIN SUM Cube Voyager Reference Guide 371 .3.10.5.. ENDLOOP ENDLOOP LOOP _jj=10.2 . they are computed at the LOOP statement and can not be modified by other statements. ENDLOOP MERGE Specifies record and variable merging.. ENDLOOP LOOP _xyz=_abc*_def. Most uses will involve constants.-2. and Linc must be separated by commas (standard white-space delimiting cannot be interpreted properly).. If an expression is used.5 ._mno/_pqr LOOP _abc=_xyz. or drop through.Network Program Control statements 8 Add Linc to LVAR.. Because LVAR values can be expressions. it is suggested that it be enclosed in either parentheses or quote marks.0 . Compare LVAR to Lend. 7. True — Default value. 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. MERGE keywords — technique Keyword AVE AVEX0 CNT |SV| |SV| |SV| Description Average of all records. (Duplicate records from the same file may not occur in the MERGE phase. Use the RECORD keyword to indicate whether to merge data in duplicate records when encountering identical keys during the NODEMERGE or LINKMERGE phases. the program uses the FIRST keyword for variables not listed with any keyword. Average of all records. Only list a variable with one keyword. If you input two networks (NETI[1] and NETI[2]) and RECORD=FALSE. Note that merging records and combining variables are independent processes. 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 []. Count of the records that contain the variable.) Each resulting record will have a cell for every variable specified in any input file or any COMP statement.8 Network Program Control statements Use MERGE to specify how to merge records from different files. 372 Cube Voyager Reference Guide . where the value from the file records is not 0. Use the following keywords to indicate how to obtain the value of variables when merging records. Include any unique record included. the program only processes the links that are in NETI[1]. The program only obtains variable values from file records that contain the variable. and how to combine variables in a merged record. LANES FILEI LINKI[2]=FILE2. LAST=LANES.0 Cube Voyager Reference Guide 373 . Maximum value of all the records.6 105 1.VAR=A.B.5 103 12.indicates variable not defined for file): FILEI LINKI[1]=FILE1.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.5 102 -103 -102 11.SPDCLASS. Example MERGE RECORD=TRUE FIRST=CAPCLASS. AVE=DISTANCE.B. Sum of all the records.VAR=A.DISTANCE.VAR=A.SPDCLASS. Directly from the record from the FILEI with the highest index []. SUM=COUNT Illustration for sample input files (-.1 106 12.Network Program Control statements 8 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[].DISTANCE.CAPCLASS. Minimum value from all the records.COUNT FILEI LINKI[3]=FILE3.B. 0 12. 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.5 MERGE RECORD=FALSE .8 Network Program Control statements Order as seen in LINKMERGE.1 101 102 -101 103 11. 374 Cube Voyager Reference Guide . Resulting file: A 101 102 104 105 B 102 103 105 106 DISTANCE 10.6 1.6 104 105 1.8 12. Resulting file: A 101 105 B 102 106 DISTANCE 10. AVEX0=DISTANCE .1 12.0 105 106 12.5 102 103 -102 103 12.5 SPDCLASS 11 12 CAPCLASS 11 12 LANES 1 3 COUNT 1000 0 MERGE RECORD=TRUE FIRST=COUNT.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. after being processed in the INPUT phase. Specifies how many records with data errors are allowed. Default value is 20. Specifies how many records with data errors will be listed before turning off the error listing. the program will terminate with a fatal condition. unless the error is in the key (for example. See FILEO NETO LEFTDRIVE in “FILEO” on page 365 for more details.Network Program Control statements 8 LEFTDRIVE LIST_ERRS MAX_IP_ERRS NODES REPL_DUP ZONES PARAMETERS keywords Keyword LEFTDRIVE |?| Description Used to force a LeftDrive switch into the NETO. If this value is exceeded. The bad fields will be set to 0. unless the error is a limits error. By default. node number). Records with errors are not skipped. LIST_ERRS |KI| MAX_IP_ERRS |KI| Cube Voyager Reference Guide 375 . this value is not set. Default value is 20. the program detects the highest number). By default. but if it is specified.) The MERGE control statement is used to determine how duplicate links from different inputs are to be processed during the MERGE phases. REPL_DUP |K?| All the values on this statement are trigger keys. the program will set it to the highest node number in a monotonic string beginning at 1. the later record will replace any previously read records. Each keyword could begin a new statement. A temporary variable _ZONES is initially set equal to this value. and can be used in COMP and IF expressions. or it is desired to alter the number of zones. Default value is false. The value must be a greater than 0 and less than 999. To obtain a listing of duplicate links. binary files should not have duplicate records. This keyword applies to each NODEI or LINKI file as it is read within any PHASE=INPUT. 376 Cube Voyager Reference Guide . the program detects the value. If ZONES is used in a COMP statement. This need not be specified (by default. any node numbers that exceed this value are considered errors.8 Network Program Control statements PARAMETERS keywords (continued) Keyword NODES |KI| Description Specifies the highest node number to be allowed in the network. Switch that indicates how to process records from an input file with matching node numbers. ZONES |KI| Specifies the number of zones in the network. (Any nonbinary file will automatically be processed within an input phase.999. the PARAMETERS control word need not be specified. it will become a variable in the output network. If this switch is true. If this parameter value is not supplied (or is not available from an input binary network). specify REPORT DUPLICATES=T. This is required only if the number of zones cannot be determined from the LINKI and NODEI files. The value must be greater than 0 and less than 20000. When the A-node is completed. so that node symbols will be prominent on the display. but there is no DRAWLINK value. DRAWA DRAWLINK LINKPOST NODEPOST PLOT statements in the LINKMERGE phase control plotting. Cube Voyager Reference Guide 377 . The situation for nodes is different. If there are no DRAWLINK values present. they are saved until all the links from the current A-node are completed. the LINKPOST value is ignored. a node can be posted without a symbol. If there is a LINKPOST value. it processes the final values for the PLOT keywords that may have been applied to the link.Network Program Control statements 8 Example PARAMETERS repl_dup=n MAX_IP_ERRS=10 nodes=35000 zones=2203 PLOT Selects links/nodes for plotting. After the program completes the LINKMERGE stack for a link. If there are DRAWA and/or NODEPOST values. the link is not processed for plotting. the node values are saved for post processing. Dash. Rectangle. Symbol — Centered on the node.) LINKPOST NODEPOST |S| |S2| Example See “Examples” on page 401. Specifies the color and size of the variables that are to be posted for this Anode. below. DashDotDot. PLOT keywords Keyword DRAWA |S4| Description Specifies the characteristics for drawing a symbol for the A-node of the link. Possible styles are: Solid. can be Circle. Dot. 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). Size — Size of the symbol. (See NODEPOSTVARS under “PLOTTER” on page 378 for information about which variables are to be posted. Possible values are: • • • • DRAWLINK |KS4| Color — A value as described in “PLOTTER” on page 378. If PLOTTER BANDWIDTH is specified and the bandwidth variable has a value. Specifies the color that this link is to be posted with.8 Network Program Control statements A PLOT statement may be specified on a short IF statement. and style. but it must begin with one of the keywords. 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 . or Triangle. size. Fill Specifies the characteristics for drawing this link: color. DashDot. Color is a value as shown in the PLOTTER description. Size and Style are ignored. It is recommended that Size usually be left null. this value should be specified as solid. otherwise the program will not know anything about the printer BANDWIDTH FILL |S| BANDWIDTH TAPER |I| DEVICE |S| Cube Voyager Reference Guide 379 . On raster plotters. PLOTTER keywords Keyword BANDWIDTH Subkeyword |S| Description Specifies the variable that is to be used to control the drawing of bandwidths along drawn links. solid could require excessive time for generating and actually drawing the plot. There must be a DEVICE specified. The name must match the name of the printer as it appears in the Printers dialog box. See “Plotting” on page 398 for some information about getting your printer device installed and its basic configuration established. a temporary variable should be designated. Usually. Any integer value from 0 to 45 (degrees) may be specified. The orientation (portrait or landscape) determines how the plot will be generated. The default is None. a taper of 45 might be more presentable. In grid plots where Fill is not used. The printer driver properties are established by left-clicking the desired printer and then modifying the properties as desired. If the name has spaces in it. and the size determines the plate size of the drawing. or the plot will be unreadable. The variable must be scaled appropriately. Name of the printer driver that is to be selected and written to. Specifies if the band is to be filled in or left empty. Specifies that the ends of the bands are to be tapered towards the nodes rather than being perpendicular to the link.Network Program Control statements 8 The PLOTTER statement specifies the configuration for plotting link and/or node information. The possible values are: Solid and None. but on pen plotters. Case is not essential. the value must be enclosed within quotes so that the spaces can be considered as part of the name. There may be up to nine values following FONT. The tokens and their replacements are: Token [date] [idate] [time] [times] [window] [scale] FOOTER ALIGN Replacement MM/DD/YY MMM DD YYYY HH. FOOTER FONT 380 Cube Voyager Reference Guide . only the first three are used. Specifies lines of text that are to be printed at the bottom of the plot page.SS X=xxxxx-xxxxx Y=yyyyy-yyyyy Scale=xxxxx FOOTER |S16| Specifies how the footers should be aligned on the plot. the FOOTER[]= must be specified. actual printing (or plotting) is performed by copying the file directly to the port that is connected to the device. The program will add one additional footer to identify the software and the licensee after the user footers are printed. This is recommended for devices that are normally not connected directly to the processing computer. The value can be: Left. Specifies the font characteristics of the footers. name. when they are present the token is replaced by a value.8 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. color. but currently. ALIGN must be placed after a FOOTER or FONT value. the output will be written directly to the printer device. If FILE is not specified. Right. If none of the footers has specified a date. The values are (position). size.MM.MM HH. if more headers are to be specified after ALIGN. rather than directly to the printer. There may be up to 16 footers. Tokens may be specified in the footers. If FILE is specified. the date and time will be added included in the identification line. or Center. Since headers most likely have special characters in them. only the first three are used. it is recommended that each header be enclosed within quote marks ("..". ALIGN must be placed after a HEADER or FONT value. color. TR. 3. Each LEGEND may have its own font characteristics. Specifies how the headers should be aligned on the plot. There may be up to nine values following FONT. Legends are primarily for identifying the characteristics of the network drawing. but currently. BL.. The coding rules are similar to those for HEADER and FOOTER. Each LINE can have its own symbol. the HEADER[]= must be specified. and 4. 6 lines will be printed. Specifies the position for additional user text is to be printed on the plot page. The legends are placed within the plot window area. Example: if only one header is specified. or 1. say HEADER[6]=". size. 2. and BR. with the first 5 being blank.. 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. Right. but you can also enter symbols on each line. name.. they will be used for the text for all lines in the legend. or Center. and their areas are not written into by network drawing. Specifies the font characteristics of the headers. if more headers are to be specified after ALIGN. There may be up to 16 headers.").Network Program Control statements 8 PLOTTER keywords (continued) Keyword HEADER Subkeyword |S16| Description Specifies lines of text that are to be printed at the top of the plot page. See “Examples” on page 401. The values are (position). Cube Voyager Reference Guide 381 . The highest index for a header sets the number of header lines that will be printed. The value can be: Left. The value is expressed as coordinate units/inch. the MAPWINDOW will be used mainly to orient the center of the plot. color. If the value is not specified. Note that when a factor is specified. The size of the symbol. the high-to-low node link will overwrite the low-tohigh link. Specifies the symbol that is to precede the LINE text. Standard color designation. and fill color. See HEADER FONT on page 381 for details. If a sample line style is to be drawn. This allows two-way links to be more visually presented. There should be four values specified for the symbol: name. MAPSCALE |R| 382 Cube Voyager Reference Guide . 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. If this keyword is not used. size. Specifies a scale factor to be used to convert coordinate units to inches.8 Network Program Control statements PLOTTER keywords (continued) Keyword LEGEND Subkeyword FONT |S9| Description Specifies the font characteristics for the text in this legend. or the length of the line. Text to be printed at the specified line of the legend. or the value is 0. a scale factor will be computed from known information. Name See DRAWA under “PLOT” on page 377 for valid symbol names. Standard color designation if the symbol is to be filled with a color. see DRAWLINK under “PLOT” on page 377 for valid names. The 4 required values are specified as X1.1.5 inches on the right). If it were desired to leave more space around the plotted window (say 1 inch on the left and 1. X2.75.Y2. the program may adjust one of the dimensions if it is necessary. 1. MARGINS=0. MARGINS[3]=1. You can do this with one keyword: MARGINS = 0.5 x 11 inches). MARGINS |R4| Cube Voyager Reference Guide 383 . The center of the map window will be placed in the center of the plotting window.Y1. The map window is specified in map coordinate units.25 inches.75.5 inches and the bottom margin 2 inches. If no window is specified. If the selected device is a printer that is selected with Letter size (8. By judicial use. the program uses the minimum and maximum coordinates from the network. Specifies the margins that surround the plot window on the printed page. the scale factor will be calculated to fit the window within the page.1.25.25. Any part of the network that exceeds the limits of the window will not be drawn. MAPWINDOW will most likely not directly correlate with the plotting window.25.75 would be used. If MAPSCALE is not specified. The plot will be scaled to fit within the map window. the plot window can be placed anywhere on the page that is desired.1. a normal margins would be 0.25 would be used.1.Network Program Control statements 8 PLOTTER keywords (continued) Keyword MAPWINDOW Subkeyword |R4| Description Specifies two opposite corners of the map window to be selected.75. To make the top margin 1. They are expressed in inches. This keyword is used primarily to make a plate that is smaller than the basic dimensions of the device. Nothing will be printed outside the rectangle defined by this The MARGINS values can be used to position the printed window within the plate. PLATESIZE is not normally used. the PLOT DRAWLINK statements set color. for example. Specifies the variables that are to be posted along links that are drawn and designated for posting by a PLOT LINKPOST value. POSTLINKVAR=VC(3) to post VC ratio with 3 decimal places. The standard font designations are specified. In general. but the color is ignored.8 Network Program Control statements PLOTTER keywords (continued) Keyword PLATESIZE Subkeyword |R2| Description Specifies the maximum plot plate (page) size. The same variables will be posted for all links. POSTLINKVAR |S4| POSTLINKVAR FONT |S4| 384 Cube Voyager Reference Guide . and the height (y dimension). It should not be greater than the dimensions specified in the device properties. Two values must be entered: the width (x dimension). The plate will be oriented at the upper left corner of the printed page. It is not recommended that different variables be posted on different links. this need not be specified. Up to four variables can be selected. it is not possible to vary the variables. the output might be cropped. 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 MARGINS values can be used to establish the dimensions of the plot window. if it is. Specifies the font characteristics for link posting. The number of desired decimal places for the posting of the variable can be appended to the variable name in parentheses. regardless if it overruns the link. and more Cube Voyager Reference Guide 385 . or is too small. a hexadecimal value (very common process). or the printer driver will substitute a font of its choosing.Network Program Control statements 8 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 font name must be recognized (and available). 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. 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. In general. or a numeric value to index color mix. You can create the internal number by specifying an integer number (not too likely). The font size can be overwritten on a node-by-node basis. Same as AutoSize. it doesn’t fit. but the color is ignored. the program will supply a value of 0. changing to a different size printer will not alter the size the text. you can specify the name of the font. and the color. If no size is specified. Three bytes are used to store the intensity of each of the colors. Print it. or by a string of digits preceded by a color indicator. If no font is specified. the program will supply the name “ARIAL. the size. The possible selections are: Fit All AutoSize AutoSize(ss) Omit the text. POSTNODEVAR FONT |S4| Font specifications You can control all text that is to be printed on the plot. Specifies the font characteristics for node posting.01. The color can be specified in various ways: by a standard name. the PLOT NODEPOST statements set color. the values can range from 0 to 255. Colors are processed in Windows by using a number that is a combination of the three colors (red green and blue). in inches. Decrease the font size until it fits. The standard font designations are specified.” The size is always specified as absolute. but the optional (ss) indicates the minimum size to allow. if desired. If there is no color for the font. The order of the strings is irrelevant. To enter the hexadecimal value. The table below indicates the standard colors and their various representations. a color will be chosen by the printer driver. 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 . the driver will translate the color number to a pen number. the string must begin with 0x and be followed by a string of hexadecimal values (0-f ). For pen plotters. The pen color correlation is determined by the properties of the driver.8 Network Program Control statements color strings. You may have to experiment to obtain which pen is selected for each color used. Note: this line is a continuation Cube Voyager Reference Guide 387 . FORM=LRCD. TIME1 .DISTANCE(6.3). 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.B(5). Example PRINT LIST=A(4). LIST=SPEED.2) ABCDE(6.Network Program Control statements 8 Example See “Examples” on page 401. all the stack statements will be executed during the LINKMERGE phase.0CDLR LIST=A.#. Citilabs recommends using PROCESS/ENDPROCESS blocks be used to contain all operational (stack) statements.# or LI. SPDCLASS FILE=PRINTFIL. Y PRINT FORM=6. only DBF and ASCII files are processed in the INPUT phase. PHASE (FILEI (comp)) PROCESS keywords Keyword PHASE Subkeyword |KS| Description Indicates the phase to which the statements which follow it are to be applied. NODEMERGE. the file will be processed in the INPUT phase. and the operations to be performed on the designated file during the phase follow on additional control statements.DISTANCE.002 PROCESS . The value for PHASE must be either INPUT. a PROCESS statement contains only the above keywords and values. That way there is no confusion about what is intended. Used only with PHASE=INPUT. The end of the phase block is established when an ENDPROCESS or another PROCESS statement is encountered.. to indicate a file from NODEI[#]. ENDPROCESS Specifies a PROCESS and ENDPROCESS block. that is more consistent if the PROCESS control is triggered by PHASE=. Normally. but if a FILEI with a different mode is specified.8 Network Program Control statements LIST= N(5). any stack statements that are not explicitly within a PROCESS block. Even if there are PROCESS blocks surrounded by stack statements. or LINKI[#] that was previously specified on a FILEI statement.. and indicates that the block statements are to be applied only when the specified FILEI file is being processed. or SUMMARY. X. PHASE FILEI |F| Normally. The ENDPROCESS statement can alternatively be specified as ENDPHASE. The program will skip over the PROCESS block. will be executed in the LINKMERGE phase. LINKMERGE. If there is no specific PHASE=LINKMERGE statement.B. T0. 388 Cube Voyager Reference Guide . The value must be NI. Network Program Control statements 8 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.DIST) LIST='Distances Differ for link:'. Example 1 . The 2nd PROCESS statement also acts as an ENDPROCESS statement.2. . B = NODECODE(B) ENDPROCESS Example 2 PHASE=LINKMERGE IF (LI.DIST ENDPHASE Cube Voyager Reference Guide 389 .1 N = NODECODE(N). . .1.DIST != LI. A = NODECODE(A). FORM=6. but an ENDPROCESS is required after the 2nd PROCESS. once a LINKMERGE phase has been designated. In other words.DIST. all stack statements must be with an explicitly stated PHASE. PHASE=INPUT FILEI=LI. Re-code node numbers for LINKI[1] and NODEI[1] using a lookup function.1.2.2. there may not be stack statements that are not explicitly within a PROCESS block.1. LIST=A(5) B(6). PHASE=INPUT FILEI=NI. LI. LI. Default value is F. Default value is T. Capacity tables. UNCONNECTED=N REPORT ALL=true. Example REPORT FILEI=Y. List of zones that do not have links into and out of them. The default value is true. Summary statistics following input phases. Default value is F. FILEO=Y. Speed tables. filei=false 390 Cube Voyager Reference Guide . Default value is F. Default value is T. DUPLICATES FILEI FILEO INPUT MERGE SPEED UNCONNECTED |?| |?| |?| |?| |?| |?| |?| All reports must be specified with a logical value of true or false. Duplicate links that are detected during PHASE=INPUT. fileo=false. Internal specifications for the allocation of output variables use for debugging only). 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. Internal specifications for the input files (use for debugging only). Default value is F. REPORT SPEED=Y. Default value is F. Default value is F. Such links cannot be used by any path processing. Links that are missing either an entry or exit link.8 Network Program Control statements REPORT Defines report specifications. Additional file processing may be required. normally not specified. Summary statistics following every phase. Default value is F. VMT=LINKS . BN=LINKS. */ PHASE=SUMMARY SORT ARRAY=-VMT.BN[_K](6). the number of entries will be less than the original number of links.BN.Network Program Control statements 8 SORT Sorts user-defined arrays. Example ARRAY AN=LINKS.VMT[_K](10.30 . 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. only want to see the highest 30 LIST=AN[_K](6). AN.2c) ENDLOOP ENDPHASE Cube Voyager Reference Guide 391 . ARRAY NUMRECS See “SORT” on page 76 for more information about this standard Cube Voyager statement. NUMRECS=_L LOOP _K=1. ). Speed is maintained with one decimal place. and may be indexed to set a specific loading place.3.3.2. inclusive. The speed array is initialized to the index number. LANES=5.Set entire table to 50.88..3. Inappropriate..400..SPEED[15]=15 SPDCAP SPEED=30. SPDCLASS) as the column index to obtain a value for a link.8 SPDCAP CAPACITY=99*50. for all lane stratification (CAPACITY[1]=20.50.8. SPEED=20.7. the program uses the number of lanes (LANES) as the row index.. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement. CAPACITY[2]=40. inclusive. inclusive.4-9. All values must be 1-9. LANES |IV| SPEED |RV*99| A network contains an array of capacity and speed data. and 24 for lanes 1. Each array is dimensioned with ninety-nine values for each of nine lane stratification... Example . The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables. CAPACITY and SPEED are entered as vector data. then revise the values for 20. All values must be 0-3276. CAPACITY LANES SPEED SPDCAP keywords Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour. the LANES will not be used.30.. LANES will be preset to 1-9.. for all lane stratification (SPEED[1.8 Network Program Control statements SPDCAP Revises speed and capacity tables. LANES=1. LANES=2-8.99). . LANES may be interspersed with other keywords and values on the statement. All values must be 0-9999..700 SPDCAP LANES=2.99]=1.21. and contains 891 values.. and may have null fields to skip the revision of certain columns.2.. CAPACITY[20]=300. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES.5. Speed to be applied to the link. 392 Cube Voyager Reference Guide . Lane stratification that any following CAPACITY and/or SPEED values are to apply to. When an array is accessed. The capacity array is initialized to 20 times the index number.6. and the capacity and/or speed classification (CAPCLASS. re-code values from any input files specifically designated. and the order of the blocks in the input is not crucial.Network Program Theory 8 Theory This section describes the theory used by the Network program. 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 . the previous block is terminated. It is suggested that for readability and ease of editing. The basic phases are: • • • INPUT phase — Read ASCII and DBF files. but that appear within a phase block will be recognized as such and will be processed properly. There may be only one block for each phase. In general. However. the phase blocks be defined in the normal process order. they are used only when special processing is to be undertaken. For most applications. the user must code operational statements within a PROCESS PHASE block defined for each phase. If another PROCESS PHASE statement is encountered before an ENDPROCESS statement. the user need not be concerned with process phases. and the new block is begun. A block should be terminated with an ENDPROCESS statement. Only statements that specifically apply to the phase should be coded within the block. statements that are not dynamic operations. Topics include: • • • • Phase descriptions Variable referencing Output variables Plotting Phase descriptions The program processes the input files in separate phases. which are listed below. and saved for subsequent referencing in the LINKMERGE phase. A PROCESS PHASE=LINKMERGE statement may be coded. but it is not mandatory. The records are processed and edited for errors and duplication. If there are no relevant files for an INPUT phase. The resulting record for each unique node is written to the output network. is no longer used in its original format after this phase is completed. and it is not within a PROCESS block. The user may specify selections and computations to be applied to each record as it is processed. the program processes the phases in the order in which they are described below. Any file (or file segment) that passes through 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. 394 Cube Voyager Reference Guide . As the program processes each file record. it applies any phase operations that the user has designated for the phase. because it is anticipated that most applications will be functioning in only this phase. Internally. INPUT phase All ASCII and DBF files must pass through this phase. NODEMERGE phase The node based records from all the NODEI files must pass this phase. The file segment records are sorted in appropriate order (node or link) before being stored in the revised format. it is tagged as being in the LINKMERGE phase. It is not permissible to re-code node numbers in this phase. and processes them. If an operational statement is encountered. it determines the files that must be processed in that phase. the phase is bypassed. the user may specify computations and/or selections to be applied to each node record as it is processed. As it processes each phase.8 Network Program Theory • SUMMARY phase — Report results of LINKMERGE phase There need not be a specific PROCESS PHASE for LINKMERGE. As in the INPUT phase. It is possible to re-code node numbers in this phase. but its data are used in subsequent phases in a revised internal format. If the first character of a name is an underscore (_). SUMMARY phase In this phase. certain post-processing operations can be performed. The first character of the name may not be a digit. Operation statements are generally expressed in the standard IF/ELSEIF/ELSE block and COMP statements. Classification Cube Voyager Reference Guide 395 . the record is processed against the operation statements designated by the user. the variable is only a local working variable.Network Program Theory 8 LINKMERGE phase The link based records from all the LINKI files must pass through this phase. usually to obtain averages. In the NODEMERGE phase. and. This is the phase that most users are mostly interested in. A variable name may be up to 15 characters in length. Tabulated and summarized data is reported at the end of the phase. and extracted to an external device or file. Every record is processed according to the purpose of the current phase. Records can be deleted. the recoded link is included. In the LINKMERGE phase. digits. etc. a link record is processed for each unique link found from the LINKI files. If a node is re-coded in the INPUT phase. These and other operations available to the user are described in “Control statements” on page 347. summarized. This is generally restricted to computations on working variables. passed onto the final phase. and will not be included in the network. in most cases. As in the above phases. If a link is recoded in the INPUT phase. tabulated. Variables are usually classified as either node or link based. and the underscore character. Variable referencing The main logic of the program involves processing variables. a node record is processed for each unique node from the NODEI files. If there are operations to be performed in the phase. the re-coded node number is included. and may consist of only letters. Node based data can be accessed during the link processing. the user may specify selections and computations to each link record as it is processed. the values are all zero. it will be attached as either a node or link variable.name* NI#. the variables are node based.#.#. A node variable is referenced during LINKMERGE as either A.name N#. The program establishes a buffer for a record from each input file for every record in the phase. If it matches a link variable.#. If there is no input record for the current working record.. Working variables are set to zero at the beginning of the application. every variable referenced within the SUMMARY block is a working variable. They are distinguished by their first letter. which must be an underscore. but node variables can be referenced.name L#.name For link records: LI. variables are link based. Working 396 Cube Voyager Reference Guide .). the variables will be associated with the type of file being processed. but the program allows the following variations: For node records: NI..#.name or B. unless it is the same as a link variable.name. For NODEMERGE the prefix is NI. Another type of variable is the working variable.. If a new variable is computed (NEWVAR=. The formal designation for the prefix is LI. If a variable from an input file is to be referenced during NODEMERGE or LINKMERGE. During any INPUT phases.name *The preferred method of designation.name L.#. During the LINKMERGE phase. the associated NODEI or LINKI file number must precede the variable name.8 Network Program Theory depends upon the process phase in which the variable is referenced. Working variables are variables that are to be used for intermediate storage. and will not be part of an output network. If there is a user SUMMARY phase.name N. and the prefix allows access to each of those buffers. and are changed only by user statements.3..name* LI#. During the NODEMERGE phase. the variable from the last link will be processed. For example: LI.#. and for LINKMERGE the prefix is LI.#.ABC references the variable ABC from the LINKI[3] file. . get assignment differences _vcnt = _vcnt + 1 if (_vdiff != 0) _sumsqdiff = _sumsqdiff + _vdiff*_vdiff . get the Node variable named X for Node A _ay = a._ax. To be sure. the variable list can be modified on the FILEO statement. 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).X. If all the variables are not to be included in the output network.y LIST=a. Phase=SUMMARY if (_vcnt > 1) RMSV = sqrt(_sumsqdiff / _vcnt).Network Program Theory 8 variables allow the user to accumulate statistics during link processing._ay EndPhase Output variables During the merge phases. a PRINT LIST variable may not be recognized if it is cross-referenced. NOTE: In some situations. For example: LIST=A.x .vol .) Example _vdiff = L1.B. 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.A.X may not be accepted. (See “Examples” on page 401 for an illustration. node based variables to be listed should be set into temporary variables and then listed with that name. and to then compute and print summaries at the end of processing. RMSV endif Phase=LINKMERGE _ax = a.L2.b. Cube Voyager Reference Guide 397 . The value that is stored for each variable is controlled by the MERGE control statement.vol.B. possibly (_vcnt-1) list = 'RMSV ='. The Network program uses the Windows driver to perform the actual formatting of the network information. if legends are used. 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. but mis-positioned. If standard colors are used (red. If roll size is selected in the device driver. yellow. They do cause some problems. Many default drivers come with Windows and provide considerable capabilities. It is possible to directly fax a network plot to a facsimile machine. This process provides for current and future flexibility. In those cases. faxes. blue. There must be an appropriate printer device driver for the media where the network is to be plotted. color correspondence is not guaranteed. Plotting pens are selected by RGB (RedGreenBlue) standards. the program may not be able to properly scale the plot. etc. the link posting will be oriented properly. there should be no problems. With one driver (WinPlus). the user must specify the desired plate size. green. If esoteric colors are requested. so pen plotters are being left somewhat behind.8 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. Pen plotter problems: The standard Windows drivers for pen plotters do not seem to function properly. as well. 398 Cube Voyager Reference Guide . Typical types of drivers are available for printers. raster plotters.). Windows operating systems are geared towards more recent technology. but deficiencies have been reported in these systems. This release of the program does not address these driver deficiencies. so it becomes the responsibility of the user to ensure that the colors that are selected correspond with the pens on the plotter. There are thirdparty software drivers available that correct this problem. in particular. they do not always write text at the proper location and angle. and pen plotters. perhaps later versions will internally rectify them. If there are PLOT statements. all text that is to be plotted can have its font. if a link is posted. but the size and color is controlled by PLOT statements. the program will fatally terminate. Legends that can be displayed in the corners of the plotting window. or to a file. black. Cube Voyager Reference Guide 399 . Bandwidths and type of fill and end tapers. The optional network window for selection. so that if a different driver is used. its posting will contain the same type of information at the same size and font as any other link that is posted. Node posting (writing text near a node) will always post the same variables. and the margins to place the plate within the driver provided dimensions. All sizes are specified in inches. The default values for each of these are: ARIAL. if different than the driver provided size. The PLOTTER statement contains information about: • • The plotting device name. the opposite is not an error. • • • • • • In general. and whether the output is to be sent directly to the plotting device. and optional scaling. color and size specified by the user. The logical layout of the plot plate on a sheet of the plotter device: the desired size. 0. The user controls the color of link posts.10. individual variables can not be colored differently. The node variables that are to be posted. PLOT statements processed during LINKMERGE determine what will be plotted from the network. the text would still be readable. The headers and footers to be printed on the plot. when a node is selected for posting. The link variables that are to be posted when a link is selected for posting.Network Program Theory 8 A PLOTTER control statement is used to define the plotting system and the parameters for performing the plot. but no PLOTTER statement. Link posting (writing text along a link) can not be varied by link. ) DrawLink=red. If a device is not attached directly to the computer. The following processes are considered: Process DrawLink LinkPost DrawA NodePost Description Draw the link as specified. the values that are current at the end of the link are used for plotting. You can deal with these situations by specifying the fourth value for PLOTTER POSTLINKVAR FONT. 400 Cube Voyager Reference Guide . but then later conditions determine that it should not really be plotted.8 Network Program Theory Before performing a plot. (portrait. If a keyword specifies plotting. it may be placed on a short IF statement. For node processing. In the Printers and Faxes window.. the keyword can be nullified by setting its value to -1. Many times a link posting may be too long for the link. These values can be specified multiple times for each link. landscape) is set in the device. If a PLOT statement is processed in LINKMERGE. the driver should have the file option specified. Files are generally processed by copying them directly to the plotter port. The orientation of the plot. Example: IF (. PLOT statements control actual plotting. Draw a specified symbol for the Anode of the link Post variables at the A node. the device driver must be properly installed. This is done by left clicking the Windows Start button and choosing Printers and Faxes. the values that are current following the last link outbound from a node are used. and the PLOTTER DEVICE FILE value (filename) should be specified. Post variables for the link. click Add a printer and follow standard installation processes. the current link is flagged for processing by the plotting process. If the PLOT statement is invoked by the use of one of these trigger keywords.. Example: NodePost=-1. LinkPost=red. b.Network Program Examples 8 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 .dat.var=n. merge two ASCII files with different links linki[1]=demo07.7. but exclude many variables from input Cube Voyager Reference Guide 401 . v1.4.x.2. v1. v2.var=a. a.35.b endrun Merging link records from multiple ASCII files run pgm=NETWORK .4.a == 0) list=' LI[3] missing link:' a.2.4.1. . b.y merge record=true.2. AVE=dist report all=no zones=19 phase=LINKMERGE if (li. dist2.3. List the links in a network neti=demo20.1.4. rev.b if (li.dat. write DBFs for nodes and links.4.4.2.4 linki[3]=demo07m.net list=a.14. var=a.a == 0) list=' LI[1] missing link:'.4. dist.14.b endphase endrun Dumping link and node records to DBF files excluding select fields run pgm=NETWORK .dat.4 nodei[1]=c:\demo\demoxy. v2.2.7.rev=2.4.2. .a.2)=='XY')..n. stop=(substr(record.dbf nodei=testxy.Hnt neto=test.tsva1. 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.b. EXCLUDE= ESPEEDA ESPEEDP ESPEEDD ESPEEDY COMMENT6 COMMENT1.1.dist.2)=='LD') .ycoor If (a>b && lanes > 4) list=a. EXCLUDE= OCOUNTD OSPEEDA OSPEEDP OSPEEDD. 402 Cube Voyager Reference Guide .var=n3.lxy .capc1.b.lanes endrun Building network from inline data records copy file=3pth.exclude=xcoor. EXCLUDE= SCENARIO STATUS NAME TPCAP1 TPCAP2 TIPRTP CNT.now look at the results from the link DBF linki=testld. pagewidth=80 RUN PGM=NETWORK .tpn.8 Network Program Examples neti=test.spdc1.1.dbf.typ=a. now build a network from the inline data merge record=y nodes=20 zones=2 nodei[3]=3pth.1.x.lane1.lxy.string1. EXCLUDE= FIELDOPT TCNUMBER COUNTY USER DATE OCOUNTA OCOUNTP.y.2)=='LD') linki[2]=3pth. EXCLUDE= OSPEEDX OSPEEDY ECOUNTA ECOUNTP ECOUNTD ECOUNTY.lxy. start=(substr(record.var=n1. start=(substr(record. EXCLUDE= ATYPE nodeo=testxy linko=testld if (STATUS=='D' || ft==15) delete endrun run pgm=NETWORK . SETUP Plotter DEVICE="HP LASERJET 4" POSTLINKVAR=A. "This is header 2".15.plt DRAWLINK=0xffff ENDRUN Complex plot .1.blue.08.1...20.symbol=dashdot. LINE[1]=TL.LINE1.LINE1. Cube Voyager Reference Guide 403 . RUN PGM=NETWORK NETI = C:\DEMO\DEMO20.italics..15.line5. Sample Quickie plot with no parameters: draw links only RUN PGM=NETWORK .2)=='XY') list=a.10. LINE[1]=TR. FONT='COURIER'.15.red LEGEND=3. font='courier' .B.15. font='courier'.. align=center.italics.._AB.DAT PLOTTER { ..BOLD POST=AUTOSIZE(.symbol=triangle.Network Program Examples 8 stop=(substr(record.line5.5.TRne3.LINE1.0. FILE=f:\sample.green FOOTER="Footer 1" FOOTER[3]="Footer 3" FOOTER[5]='Shows various date tokens: [date] [idate]' FOOTER[7]='Shows various time tokens: [time] [times]'.. LINE[1]=BL.This sample illustrates various capabilities of plotting.symbol=circle.01 BANDWIDTH=_BANDWIDTH FILL=SOLID TAPER=45 HEADER= "This is header 1".b.red LINE[5]=BL.05) POSTNODEVAR=A..10.symbol=triangle.YELLOW..italics. font='courier'.italics.15. font='courier'. FOOTER[7]='Shows window and scale tokens: [window] [scale]' align=right font='Courier'.DAT PLOTTER DEVICE = "HP 7475A". sample quick link plot NETI = C:\DEMO\DEMO20.symbol=rectangle.10.0..red LEGEND=BottomRight font='courier'.red.blue._STR FONT='COURIER'.0.10.purple.red LINE[3]=tr.10 LINKOFFSET=0.dist endrun Simple link plot .red LEGEND=TR..red LINE[5]=tl.green LEGEND=TopLeft.symbol=Dash. X || A.RECTANGLE.15. reset the color of these links .CIRCLE. LINKPOST=GREEN IF (A.WHITE NODEPOST=0XFF00FF IF (A>5 && A<=10) DRAWA=RED .DASH ..10.BLACK NODEPOST=R255 ENDRUN 404 Cube Voyager Reference Guide .1 IF (A>=30 && A <40) LINK=GREEN. FLAT|VERTICAL LINES DRAWA=BLUE.0. set node postings and symbols IF (A<=5) DRAWA=RED..LINE2..0.symbol=triangle. Plotting Controls if (a<=19 || b<=19) _BANDWIDTH = lane/10 _AB = A*100 + B _STR = str(_ab/100.Y == B.15.5.SOLID.0.YELLOW NODEPOST=r123b220g100.20.8 Network Program Examples LINE[2]=BR..CIRCLE.2) DRAWLINK=RED.0.X == B.red } .Y) LINKPOST=BLUE.40 CIRCLE NODEPOST=G255 IF (A>10 && A<20) DRAWA=R255. Cube Voyager Reference Guide Cube Voyager Reference Guide 405 . Topics include: • • • Using the Matrix program Control statements Examples 406 Cube Voyager Reference Guide .9 Matrix Program 9 Matrix Program This chapter describes the Matrix program. you must specify what is to be accomplished.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. or DISTRIBUTION. Various file formats for both input and output are supported.Matrix Program Using the Matrix program 9 Using the Matrix program This section provides information for using the Matrix program. 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. Zonal data and matrices can be input. There are no default processes. 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. This program is also used when invoked as a special function via RUN PGM= FRATAR. GENERATION.) Frequency distributions User formatted files Cube Voyager Reference Guide 407 . etc. and matrices and reports can be output. ” for details. Distribution. 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. reporting. in most cases. zonal data files are read and stored. and are. “Distribution Program. the program builds a list of required variables. and have been stored in the control stack. Computational statements are those that cause data to be revised. If any input matrices need to be transposed. It then starts the Iloop. When the end of the stack is reached. Definition statements are those that define the input and out files. any requested reports are printed. I-loops are nested within iteration loops. and other housekeeping is performed. processed outside of the I-loop. and disaggregrating matrices Almost any and all of the above processes can be performed in a single application. and processes the control stack from the beginning. reads the matrices for I. 408 Cube Voyager Reference Guide . and the program exits. and flow control statements (illustrated below). computational. The remainder of this document refers to this loop as the I-loop. they are transformed to a single file and made ready for subsequent retrieval. and writes any matrices requested. When the I-loop completes (or is terminated). the program performs some end-of-zone summaries. and Generation programs). When all control statements have been checked for basic syntax. The input files are opened.9 Matrix Program Using the Matrix program • • • Transposing matrices Generating matrices Renumbering.) The standard input is comprised of definition. The program processes within an overall origin zone loop controlled by the variable named I. (See Chapter 10. aggregating. There are some restrictions when used as a special function (Fratar. Flow control statements provide the capability to iterate through portions and conditionally or unconditionally branch to a different place. within the I-loop. there are certain built-in variables that can be referenced. The iteration number. Holds the number of fields on the input record file.RECERR RECI. Holds the record number of the current record being processed from the input record file. see “COMP” on page 477 for more details. A work matrix. Result of LOWEST(). Under intrastep distributed processing with Cube Cluster. The built-in variable are usually protected. 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.NUMFIELD RECI. usually 1. Stores the last zone number to be processed. this is the first zone number of the zones to be processed on the current Cube Cluster node.Matrix Program Using the Matrix program 9 All variables are initialized to zero (or blank) before the I-loop. I ITERATION J LASTZONE LOWCNT MW[] RECI. Holds the number of records in the input record file. In a normal run this would be the same as ZONES. and varies (1-Zones) for MW[] and LOOPs. In a normal run this is 1. the user is not allowed to alter their values. The current row zone.RECNO Cube Voyager Reference Guide 409 . Under intrastep distributed processing with Cube Cluster. A column index. usually 1.NUMRECORDS RECI. In addition to any variables explicitly specified by the users. this is the highest zone number to be processed on the current Cube Cluster node. and are thereafter altered only by computational statements or internal processing. 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 array’s values. Number of zones.9 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. 410 Cube Voyager Reference Guide . Sum lowest valued cells in a row. Integerize mw (start at column intrazonal + 1) Maximum value in the row.nameT.n. Multiply one matrix by another. Factors the row by fac. Row total Transposed matrices A copy of a transposed input is obtained by referencing a variable with a name of MI. Allow random access to values from MATIs Add matrices. In Matrix program terminology. Average cell value where value!=0 Number of cells whose values != 0 Divide one matrix by another. See “COMP” on page 477 for details. Z ZONES Built-in functions Described in more detail in “COMP” on page 477. a transposed matrix is one that has had its rows and columns switched. Minimum value in the row. ARRAY FILEI and FILEO (which define the input and output data. BSEARCH CALL CHOICE COMP FREQUENCY SET XCHOICE • Reporting statements — Cause values to be accumulated and/or displayed dynamically. GOTO :label Cube Voyager Reference Guide 411 .Matrix Program Using the Matrix program 9 Control statement types in Matrix program There are several types of control statements used in the Matrix program: • Definition statements — Define static processes.) LOOKUP PARAMETERS RENUMBER • Computational statements — Cause variable values to be updated. FREQUENCY PRINT PRINTROW REPORT • Flow control statements — Set which statement is to be performed next. To set the intrazonal element of a matrix row. Special keywords INTRAZONAL or INTRA are provided to assist in this. all elements of the matrix which lie off the diagonal are left unchanged. see “Control statements” on page 451. When such commands are executed.9 Matrix Program Using the Matrix program BREAK CONTINUE LOOP ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For more details about control statements. 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. 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. Note that it is invalid to use the above forms of calculation with a JLOOP (as JLOOP implies varying the J. which are used to select destination zones. or column. 1. As an example: INTRAZONAL mw[10] = 0 INTRAZONAL mw[10] = LOWEST(10. or the row index). Neither can it be used with the INCLUDE or EXCLUDE subkeywords of the M[] statement. whereas INTRAZONAL or INTRA fixes it to I.01. 99999) 412 Cube Voyager Reference Guide . 0. Such commands may be used in conjunction with the LOWEST function set an intrazonal cost based on the cost to the nearest zone(s). given a suitable descriptive name to identify them. industrial zones. Examples are: MW[1] = MW[1][INTRA] which copies the intrazonal (or diagonal) element of the first working matrix into all column positions. but their use is restricted to arithmetic computations. but ignoring destinations with costs less than 0. This keyword is coded in a similar manner to the j (or column) position when a matrix is referenced in an arithmetic expression. or zones corresponding to external cordon points. the suburbs. it is often necessary to apply different treatments to various types of zones. Any of these areas comprises a list of zone numbers. Examples of such zone groupings are the CBD (central business district). and similarly to movement types within matrices. This section outlines two methods: • Working with lists of zones using the INLIST function — Uses the INLIST function to select required zones. lists which are lengthy and used on many occasions in processing could easily be a source of errors in typing or updating.Matrix Program Using the Matrix program 9 sets the intrazonal cost to the cost from the origin to the nearest destination. Working with lists of zones When modeling travel demand.01 or more than 99999. and then used wherever appropriate in the modeling. taken from the current row of the matrix. To avoid such difficulties. such lists of zones may be set up once. The INTRAZONAL or INTRA keywords may be used to access the diagonal element of a matrix during calculations. Cube Voyager Reference Guide 413 . it is simple to define lists. and: var1 = MW[10][INTRAZONAL] which sets a scalar variable var1 to the intrazonal element of working matrix ten. 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. but they may be used in a wider range of contexts. The INLIST function is then used to construct a condition which determines whether its origin and/or destination are in the specified list. it is less easy to define the required lists. origins in suburbs and destinations in CBD .suburbs) = 1) JLOOP IF(INLIST(j.50-57' . ENDIF . zones 1 to 12 and 15 to 20 form the CBD of a study area... JLOOP IF (INLIST (j. commands here processed for destinations in the suburbs ...CBD) = 1) . A list called CBD may be defined..34-41.43. commands are processed for flows which have both .. Working with lists of zones using the INLIST function As an example.. commands here will be processed for origins in the CBD . IF (INLIST(i. The particular zone under consideration is often i (the origin zone) or j (the destination zone)...9 Matrix Program Using the Matrix program • Working with list of zones using the substitution method — Defines lists in the Pilot program.15-20' suburbs='23-30. The list of zones is specified as text data which is enclosed in quotes ('). then uses the substitution facility to work with them. ENDIF ENDJLOOP ENDIF 414 Cube Voyager Reference Guide . using the COMP or computation control statement.. The INLIST function gives a value of 1 when the particular zone (first parameter) is found in the specified list (the second parameter)...CBD)=1) .suburbs) = 1) . ENDIF ENDJLOOP IF (INLIST(i. The following example illustrates the use of this facility: CBD='1-12...47. .. RUN PGM = MATRIX . in place of the list’s name). this form is not accepted by the conditional or IF statement which requires commas. The list of zones is specified as text data which is enclosed in quotes (').. using the COMP or computation control statement. (Although Cube Voyager scripting allows spaces to be used as delimiters between items of a list.Matrix Program Using the Matrix program 9 Working with list of zones using the substitution method As an example. and so use of commas is recommended. . it should be written with commas between items...1. then adds a parking cost of 10 units into the skim (or level of service) matrix for destination zones in that area.05: . This is done in the script before any RUN PGM statements for programs. and forms part of the script of the Pilot program. zones 1 to 12 and 15 to 20 form the CBD of a study area.. A list called CBD may be defined. To ensure that the list is generally acceptable. dividing these matrix cells by 1. ENDRUN defines the list of zones in the CBD. its script contains the name of the list. Cube Voyager Reference Guide 415 . Wherever this list of zones is required by a program. 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 '..... MX[10]=mi.' (comma) between the start and end values.. JLOOP INCLUDE = @CBD@ MX[10] = MX[10] + 10 ENDJLOOP .. which is enclosed by @ symbols (denoting substitution of the list of zone numbers. The example: CBD='1-12.) A further example changes that part of a matrix which corresponds to origins in the suburbs and destinations in the CBD.LOSmatrix .15-20' . .05 endjloop endif or even: if(i = @suburbs@) mw[1]=mw[1]/1.27 .. RUN PGM = MATRIX .....194-224. if(i = @suburbs@) jloop if(j = @CBD@) mw[1]=mw[1]/1.15-20' .. . ENDRUN The calculation may be expressed more concisely as: if(i = @suburbs@) jloop include = @CBD@ mw[1]=mw[1]/1...05 include=@CBD@ The following illustrates the case where the calculation applies to all destination zones for selected origins: ..148-191...227-341' CBD = '1-12.... CordonZones = '540-578' .9 Matrix Program Using the Matrix program suburbs = '100-145. if(i = @CordonZones@)mw[5]=mw[5] * 1. ENDRUN 416 Cube Voyager Reference Guide .05 endif endjloop endif .. RUN PGM = MATRIX . These forms can not be intermixed in the same record processing step of the Matrix program. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi). that sets the format as fixed. script references to RI. New scripts developed after version 3. a practice that we generally do not like to condone.x should reference RECI. All data fields MUST be defined in the same format.NFIELD[] were coded. For backward compatibility. The earlier versions could deal with only numeric data fields.x.0 and beyond Substantial changes have been made in dealing with RECI text (non-DBF) files in versions later than 3. This was inconsistent with most other text file processing where FIELDS was used. with N being the default mode. This has rendered older setups unusable.FLD[] will act the same and be treated as if RECI. If the data field is being defined via the name= format. There are two forms of text records that have to be dealt with: fixed format and delimited.2. If a data field is defined by a single number (field number on the records). All data fields can optionally be defined as character mode (C) or numeric mode (N). To incorporate these changes.Matrix Program Using the Matrix program 9 Working with RECI/RECO processing in v4.2. the entire structure of RECI for text processing had to be completely rewritten. 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. If the data fields are being Cube Voyager Reference Guide 417 . There were several reasons for these changes: Earlier versions had used the keyword FLD to define data fields.NFIELD[].0 can and later versions can deal with both numeric and character data fields. that sets the format as freeform. The way that the program distinguishes between the two is by the way the data fields are defined in the script. so FLD has been decommissioned and replaced with FIELDS. the mode can be appended to the name: ORGZONE(N)= STREET(C)=. but necessary in this situation. v4. the parallel RECI. FIELDS= may be specified multiple times. For fixed format. To define a number of data fields when the user does not wish to have uniquely specified names for all fields. with.CFIELD[1-6] will be blank. FIELDS=22(C3) will cause RI. RI. would define variables 10 variables: RI.6. RI.FIELD1…RI. FIELDS=6(C7) would be the same.24. but those fields would all be character values. Var6(C)=10. 13 respectively.FIELD7 will be obtained from fields 6 through 13 of the data records. If the field is defined as numeric.NFIELD[2] RECI. var5=5.FIELD8 (and RECI.9.2. 9.CFIELD[x]. Optionally. or without multiple definitions. the FIELDS= format is used. They are referenced as RECI.2. FIELDS can specify multiple successive fields with a single specification (providing all are the same mode). FIELDS=11(5) will generate RI. FIELDS=1. FIELDS=21-22(7) would generate RI. for all character variables. FIELDS=1-5(10).FIELD2. its parallel character RECI.9 Matrix Program Using the Matrix program defined via the FIELDS= format. FIELDS=6(7) specifies that RI. the mode can be appended to the end of the field definition: FIELDS=1-3(C) for fixed format. and would cause population of RECI.8.FIELD1…RI.23.CFIELD[1-10].22. 418 Cube Voyager Reference Guide .FIELD1. However. These variables can also be referenced as: RECI.NFIELD[] value will be zero. or FIELDS=1(N). RECI.FIELD1-7 with the values coming from columns 21-22.CFIELD[1-9] will be defined. RECI. FIELDS=1.FIELD1 through RI.25-26… If FIELDS= and name= are intermixed. the monotonic index for FIELDS continues with the next FIELDS value.NFIELD[1-10].NFIELD[3].CFIELD[] value will be blank.xFIELD[1-8]).FIELD10.FIELD2 would be obtained from columns 6-10. 23-24.NFIELD[3] RECI. In addition.7.FIELD9 to be obtained from data fields 1.3. Var4=4.FIELD1… RI.3.13 will define variables RI. Conversely. etc.FIELD3 would be from 11-15. and RECI. FIELDS=6.FIELD3 coming from data fields number 6. RI. FIELDS=15(C10) would establish the RI.6(3).FIELDs as character.NFIELD[x] and RECI.3.NFIELD[7-9] will all be zero. For every FIELD. RI.2.NFIELD[1-9] and RECI. and RECI. there will be two values: a numeric value and a character value. all references to RI.FLD should be changed to RECI.FLD[n].FLD[10] was obtained from column 10.FIELDx. In addition.FLD[1]…RI. RI. Working with logit choice models This section discusses logit choice models.NFIELD[x].NFIELD[x]. The basic revisions required are: If FLD= specification (which indicated fixed format records) was used. In general.0-0.FIELDx.Matrix Program Using the Matrix program 9 Application script running under earlier versions that did not have this capability will have to be revised. FLD[10]=10. Any references to RI.FLD[x] should be revised to RECI. This can usually be done quite easily with any editor with search and replace capabilities. This can not be duplicated in this version. for example: INCOME=3 will have to become INCOME=3-3 If FLD= was not specified (free format) and no name= was specified.0-0.FLD[x] must be revised to RECI. If the old script had FLD[3]=3. Any references to RI. Topics include: • • • • • Introduction to choice modeling Absolute logit model Incremental logit model Hierarchical logit model Destination choice Cube Voyager Reference Guide 419 . the definition will have to be changed to lo-lo. If the highest field to be referenced is 15. the program estimated the number of variables (n) on the record and generated variables RI. then FIELDS=1(15) should be specified. This will have to be revised to FIELDS=0-0. and the definition was a single field (not lo-hi).10-10. several revisions are required.0-0.NFIELD. or to RI.FLD[3] was obtained from column 3 of the data record and RI.0-0.3-3. or to RI.0-0. the user must specify the maximum number of variables to be obtained from any data record (judicious over estimation should not cause any problems).0-0. if name= was specified. but an increase in cost makes the alternative less attractive.1 of Cube Voyager. For detailed changes please refer to “XCHOICE” on page 468. Note that some of the keywords are different with the XCHOICE command statement. whereas the cost has to be multiplied by an appropriate coefficient (or scale parameter) before use in choice models. Existing choice models that use the CHOICE statement will continue to run as scripted. When converting a logit model that uses CHOICE to use XCHOICE. The XCHOICE (CHOICE prior to v4. the other difference is that a utility directly measures the users benefit. However. Costs and utilities are related. As the utility of an alternative increases the alternative becomes more attractive. Citilabs recommends modifying existing models to use the XCHOICE command statement and take advantage of the improvements in run time. The CHOICE command statement continues to function as in prior versions.9 Matrix Program Using the Matrix program • • Mode and destination choice General notes Introduction to choice modeling Beginning with version 4. A choice model implemented with XCHOICE should run significantly faster than the same model implemented with CHOICE.1) command in Cube Voyager scripting provides powerful extensions to the core language designed to allow complex logit choice models to be specified easily. Use the XCHOICE command statement whenever developing new choice models in the Matrix program. you must make additional changes at the keyword level. the XCHOICE control statement replaces the CHOICE control statement for implementing logit choice models. and the model estimates the probability of choosing each particular outcome. XCHOICE implements the same logit model structures as the original CHOICE statement but improves choicemodel run times. Apart from sign. The alternatives are evaluated using either their costs or their utility values. 420 Cube Voyager Reference Guide . Logit choice models have a number of distinct possible outcomes (for example mode of travel). so forming a multinomial model. The choice process may be viewed as initially choosing between sub-nests (representing types of travel). The section uses a number of examples to illustrate use of the CHOICE command and to explain the underlying theory. They are: • • Absolute logit model Incremental logit model Cube Voyager Reference Guide 421 . or car use (which includes through-trip by car and park-and-ride). and may be used in absolute or incremental form. This may be extended by adding further alternatives. the alternatives are not always independent of each other. Alternatives which are similar are grouped together to form sub-nests. An alternative form is the Incremental model (also known as the Pivot Point model) which has a different methodology.Matrix Program Using the Matrix program 9 The simplest choice model splits total travel demand between two alternatives (or modes). It uses data for demand (by alternative) in the base situation together with changes in costs (or utilities) between the base and forecast scenario. but destination zones which the traveler chooses between. and then choice at the sub-nest level which decides the mode used. These sub-nests are then brought together in the main (or toplevel) choice process. Typical examples of sub-nests are public transport (which brings together various transit modes). It may be combined with mode choice to form complex models. The examples start at the simplest level and increase in complexity. To overcome this hierarchic choice models are used which sub-divide the choice process into a sequence of decisions. The simple choice and hierarchic models described above are forms of the “absolute” logit choice model. In practice when several alternatives exist. it is known as the binary choice model. The destination choice model is an extension to the logit choice concept where the alternatives are not modes of travel. in order to re-allocate the demand between the alternatives in response to those cost changes. alternative strategies or more complex variations are also illustrated. Then the method for implementing a solution in the Matrix program is shown. For a detailed description of the demand modeling function syntax see “XCHOICE” on page 468.9 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. any practical issues related to setting up such a model are discussed. For some models. with example scripts. 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. Absolute logit model This section discusses the absolute logit model. supported with the relevant theory. At the end of the section there are some general notes concerning coding of demand models. Suppose that in a transport system there are just two discrete competing modes—car and public transport (PT)— 422 Cube Voyager Reference Guide . Finally. for example the convenience of bus services. Let’s call the cost of travel by car. wait. subscripts relating to the origin and destination zone have been omitted. For the sake of clarity. in-vehicle-time. Cpt. Logit Choice model The process begins by calculating the generalized cost of travel between each origin and destination by either mode. 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. etc. that make such a journey in a given period. There may also be an additive constant to approximate those elements of the cost that cannot be readily quantified.) and time (walk. Cube Voyager Reference Guide 423 . because there are just two alternatives (car and PT). fuel.). or the quality of railway rolling stock. this cost is a linear combination of the monetary cost (fare. Usually.Matrix Program Using the Matrix program 9 between a given set of origins and destinations. Suppose that there is a total demand. A user of such a system is said to have a binary choice. and by PT. Ccar. and in particular how this is implemented in Cube Voyager. etc. interchange. D. are: 424 Cube Voyager Reference Guide . Ppt. Pcar. this simple choice model does not require a distinct scale parameter. The forecast demand for car is given by Dcar and for PT. car and public transport). and PT. Pcar. The model also calculates a composite cost (C) that represents the cost of the combined choice (in this case. where: Where utilities are used instead of costs. and Ppt.9 Matrix Program Using the Matrix program The Absolute Logit Model states that the probabilities of choosing car. of which more later. Dpt. the probabilities of choosing car. Using utilities. as its effects have already been incorporated into the utility values. are given by the equations below. Where λ is the scale parameter. called λ in the equations above.01. 0. Finally. progressively allocating more demand to the choice with the lower cost.) are as given above.04. The graph below illustrates the model sensitivity with different values of λ. as λ approaches infinity. the model will allocate all the demand to the alternative with the lowest cost. Cube Voyager Reference Guide 425 . and demand is shared equally between each of the available choices.Matrix Program Using the Matrix program 9 the composite utility (or logsum) is: and the equations for demand by alternative (Dcar. As λ increases. If λ=0 the model is completely insensitive to cost. the sensitivity of the logit model increases. etc. The figure “Logit model sensitivity” on page 426 shows how the model becomes more responsive to the difference in cost for λ=0. Scale parameter (cost-based models) The behavior of the model is determined by a positive constant known as the scale parameter.02 and 0. Notice that Pcar=½ and Ppt=½ when λ=0. Matrix script for cost-based model This section describes how this example can be implemented using the XCHOICE command. the scale parameter is not required. Logit model sensitivity Where choice models are based on utilities. characteristics of the demand and the units of cost. Variable names have been chosen to match those used in the preceding equations. The examples used here are for illustrative purposes and should not be adopted as default values. Absolute logit model 426 Cube Voyager Reference Guide . . there is no cost coefficient as it has already been combined with the actual cost to form the utility values. 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.9 Matrix Program Using the Matrix program The value of the scale parameter will depend on the nature of the choice. The fragment of script below will run this model. Thus for simple choice models. . Now the output variables are specified. Input costs COSTSMW = 3.16. pt. as matrix MW[4]. Cube Voyager Reference Guide 427 . Forecast demand ODEMANDMW = 15. These specify what alternatives may be chosen. and PT. These are forecast demand for each alternative.02 car pt. and the structure of the logit choice model. . as matrix MW[3]. . 4. the generalized costs are specified for car. the resulting outputs. In this case the choices are car and PT. These should be listed in the same order as the modes in the ALTERNATIVES clause. Model structure SPLIT = TOTAL 0.Matrix Program Using the Matrix program 9 XCHOICE. starting with the total demand which is coded in the DEMANDMW clause. Next. again specified in the same order as the ALTERNATIVES clause. Input total demand DEMANDMW = 10. in which case the output “demand” will be the probabilities associated with each alternative. or it may be set to 1. The block begins with the ALTERNATIVES clause listing of the names of the alternatives. The model inputs are specified. . Forecast composite cost SPLITCOMP = 19. These names will be used later to define the model structure. 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. the inputs to the calculations. . . The specified input may represent a matrix of true demand (in trips). . List choices ALTERNATIVES = car. as shown here using MW[10]. so MW[15] will contain car trips and MW[16] PT trips. pt. List choices ALTERNATIVES = car. but this may be extended to three or more alternatives. . In this example the choice is between two modes.9 Matrix Program Using the Matrix program Finally the structure of the choice model is defined. Variable names match those used in the preceding equations. Matrix script for utility-based model This section describes how this example can be implemented using the XCHOICE command. Where a Matrix program script contains several XCHOICE commands. The SPLIT clause defines the model’s structure in terms of the scale parameter (or coefficient of generalized costs) and the choices given in the ALTERNATIVES clause. Absolute logit model XCHOICE. 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. car and PT. . Input utilities 428 Cube Voyager Reference Guide . and either clause may be omitted from the script.02 (or λ=0. 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 fragment of script below will run this model. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in the script. the same STARTMW value may be used in all instances. In this script. The forecast composite cost is output as MW[19] with the SPLITCOMP keyword. and should not be used elsewhere in the script. Input total demand DEMANDMW = 10. . the scale parameter is given as a numerical value but it is equally valid to use a variable instead. Working matrices from the STARTMW value upwards are used by the XCHOICE command.02 in the above equations) and the choice is between the car and PT alternatives. . Both the forecast demand and composite cost are optional outputs. Matrix Program Using the Matrix program 9 UTILITIESMW = 5. as shown here using MW[10]. starting with the total demand which is coded in the DEMANDMW clause. The SPLIT clause defines the model’s structure in terms of the choices given in the ALTERNATIVES clause. and PT. as working matrix (MW) numbers. the inputs to the calculations. Next. These should be listed in the same order as the modes in the ALTERNATIVES clause. The block begins with the ALTERNATIVES clause listing of the names of the alternatives. as matrix MW[6]. These specify what alternatives may be chosen. Model structure SPLIT = TOTAL car pt. 6. These are forecast demand for each alternative (MW[15] for car trips and MW[16] for PT. here the choice is between the car and PT alternatives. the resulting outputs. or it may be set to 1. as matrix MW[5]. Finally the structure of the choice model is defined.16. These names will be used later to define the model structure. The specified input may represent a matrix of true demand (in trips). the utilities for car. Working matrices STARTMW = 40 . The model inputs are specified. but this may be extended to three or more alternatives. in which case the output “demand” will be the probabilities associated with each alternative. Forecast composite utility SPLITCOMP = 18. car and PT. In this case the choices are car and PT. The word TOTAL indicates that this split divides the entire input demand between the specified Cube Voyager Reference Guide 429 . again specified in the same order as the ALTERNATIVES clause). The XCHOICE command comprises a number of clauses of the form keyword = value(s). Now the output variables are specified. Forecast demand ODEMANDMW = 15. . and the structure of the logit choice model. each of which defines some aspect of the logit choice model. In this example the choice is between two modes. . . 9 Matrix Program Using the Matrix program alternatives. Working matrices from the STARTMW value upwards are used by the XCHOICE command. Where a Matrix script contains several XCHOICE commands. The forecast composite utility is output as MW[18] with the SPLITCOMP keyword. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in the script. and either clause may be omitted from the script. 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 . 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. Incremental logit model This section discusses the incremental logit model. and should not be used elsewhere in the script. Both the forecast demand and composite utility are optional outputs. the same STARTMW value may be used in all instances. both using costs and utilities below. Cpt) and forecast costs by mode (C’car. 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 . but now forecasts the change in demand based on the change in cost from a known base situation. Dpt). The structure of the model shown below in Figure 1. Incremental logit choice model The model inputs are base demand by mode (Dcar. base costs by mode (Ccar. Structure of incremental logit model This model is developed.Matrix Program Using the Matrix program 9 Introduction This example returns to the structure of the absolute choice example. C’pt). This is known as the incremental form of the logit model. D’pt) is: The incremental composite cost (DC) is given by: When working with utilities. the above equations are adapted to reflect the absence of any scale parameter (as this is combined into the utility values). The utility differences are calculated as: 432 Cube Voyager Reference Guide .9 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 (D’car. Matrix Program Using the Matrix program 9 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. . . Working matrices Cube Voyager Reference Guide 433 . Model Structure SPLIT = TOTAL 0. . The output composite cost is the incremental change in composite cost. 21. . Input forecast costs by mode COSTSMW = 30. pt.02 car pt. List choices ALTERNATIVES = car. . 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. Incremental logit model XCHOICE. Forecast incremental composite cost SPLITCOMP = 7. Input base costs by mode BASECOSTSMW = 20. one can see that only the model inputs change to construct an incremental model. . but an absolute logit model). 31. The model requires base demand. base costs and forecast costs for both modes as input. . Input base demand by mode BASEDEMANDMW = 10. . 11. . Forecast demand ODEMANDMW = 2.3. List choices ALTERNATIVES = car. The output composite cost is the incremental change in composite cost.BaseCost) DCOSTSMW = 24. base costs and forecast costs for both modes as input. . one can see that only the model inputs change to construct an incremental model. In this case. Incremental logit model (specifying cost differences) . Input CHANGE in cost (= ForecastCost . DCcar. can be set to zero. 25. . The model requires base demand. Forecast demand ODEMANDMW = 2. Where the cost difference is zero. .3. . Specify scale parameter (or cost coefficient) lambda = 0. Model Structure SPLIT = TOTAL lambda car pt.02 XCHOICE . Input base demand by mode BASEDEMANDMW = 10.9 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. there is no need to calculate the car cost for each test. 11. This variant is particularly useful when the costs do not change for all modes. but an absolute logit model). suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. For example. Instead. the change in car cost. pt. the numeric value may be specified as the cost difference for the alternative (rather than needing to construct a matrix of zero values). . Working matrices STARTMW = 30 Matrix script for utility-based models Comparing the example code below with the first example (same structure. . The example excludes the calculation of incremental composite costs. . Incremental logit model 434 Cube Voyager Reference Guide . Instead. Input base costs by BASEUTILSMW = 20. 25. . pt. 31. Input base demand by BASEDEMANDMW = 10. . Input forecast costs UTILITIESMW = 30. Incremental logit model (specifying cost differences) XCHOICE . Car Utilities are unchanged. DCcar. . . This variant is particularly useful when the costs do not change for all modes. suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. the change in car utility. Input base demand by mode BASEDEMANDMW = 10. . 21. 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. . Model Structure SPLIT = TOTAL car pt. Forecast demand ODEMANDMW = 2. 11. . For example. . . . . . List choices ALTERNATIVES = car. In this case. Model Structure SPLIT = TOTAL car pt. pt.3. so are specified as '0' DUTILSMW = 24. The example excludes the calculation of incremental composite costs. Cube Voyager Reference Guide 435 . there is no need to calculate the car utility for each test. . Forecast incremental SPLITCOMP = 7. can be set to zero.BaseCost) . Forecast demand ODEMANDMW = 2. 11.3.Matrix Program Using the Matrix program 9 XCHOICE. Input CHANGE in cost (= ForecastCost . List choices ALTERNATIVES = car. bus and train are members of the public transport nest that is considered to be distinct from the (private) car mode. This is an example of a Hierarchical Logit Model.9 Matrix Program Using the Matrix program . 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. the choice probabilities are calculated by starting at the bottom of the tree and moving up the hierarchy. bus and train. Structure of hierarchical logit model Hierarchic models group related choices together in nests (or hierarchies). 436 Cube Voyager Reference Guide . which can be implemented in Absolute or Incremental form. In this model the process begins in the PT nest. In this example. calculating the choice probabilities and the composite costs in each nest. In an absolute model. Working matrices STARTMW = 100 Hierarchical logit model This section describes the hierarchical logit model. Matrix script Cube Voyager Reference Guide 437 . That is to say. the resulting probabilities are calculated. The first pass calculates conditional probabilities and composite costs working up the tree structure. A scale parameter must be associated each nest. 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. Cost-based examples of hierarchic logit models As before the total demand is specified together with generalized costs for each choice (car. the model’s sensitivity to cost increases down the hierarchy. 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. using the equations of the Incremental Logit Choice Model. bus and train). then in the second pass working down the tree.02 in the upper nest (consistent with the previous example) and μ=0. The composite PT cost will be used next to represent the cost associated with the combined PT choice.Matrix Program Using the Matrix program 9 Firstly. the scale parameters are λ=0. so that: For incremental models. It is now possible to move back down the hierarchy forecasting demand for each mode with the information derived above. the calculations are again performed in two stages. The choice probabilities for car (Pcar) and all PT (Ppt) can now be calculated using the technique described in the first example.03 in the lower nest. In this example. . Model Structure . Top level nest SPLIT = TOTAL lambda car pt. Forecast composite cost PT level SPLITCOMP = 20. The hierarchical structure is specified by moving down the tree describing each nest.03 XCHOICE. . Input costs COSTSMW = 4.16.02. Notice that PT is not declared as an alternative. 5. . Then the model inputs and outputs are specified. . . bus and train) are declared with the ALTERNATIVES clause. the first split command divides TOTAL (the total demand) into car and (all) PT with scale parameter λ=0.15. Working matrices STARTMW =70 First the modes (car.9 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: .02 mu = 0. Forecast demand ODEMANDMW = 14. Notice that a scalar variable called lambda has been used to 438 Cube Voyager Reference Guide . List choices ALTERNATIVES = car bus train. The input total demand and costs for the three distinct modes are given first. . Forecast composite cost top level SPLITCOMP = 19. 6. PT nest SPLIT = PT mu bus train . . followed by the output forecast demand by mode. Beginning at the top of the tree. Input demand DEMANDMW = 1. this is the name given to the combined choice of bus and train. Absolute hierarchical logit model . Specify scale parameters lambda = 0. . Cube Voyager Reference Guide 439 .Matrix Program Using the Matrix program 9 represent the scale parameter in this case. park and ride. and metro. and heavy rail as hrail: .03. PT is not considered as an individual mode now. The second split command sub-divides PT trips between the bus and train alternatives using a scale parameter μ=0. and this acts as a link to the next level up the tree (where total demand was divided between car and PT). in this case the top level. List choices ALTERNATIVES = car pandr bus hrail lrt metro. For example. . heavy rail. a large absolute hierarchical logit model structure might have six choices: car. with park and ride abbreviated as pandr. More complex absolute hierarchical models The hierarchy can be extended with additional nests on either side of the tree. light rapid transit (LRT). Extract from a large absolute logit model XCHOICE. Input demand DEMANDMW = 1. The SPLITCOMP keyword computes the composite costs for the nest associated with this SPLIT. . 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. bus. but as a link with the lower nest. Another SPLITCOMP keyword for this SPLIT keyword computes the composite costs specific to the PT nest. The name pt is used as the first value in the SPLIT clause. Where a scale parameter applies to two or more sub-nests.0 there is no need to specify its value as this the assumed default. Input costs COSTSMW = 11.04 hrail lrt metro. 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.03 bus train. and must not exceed 1. the scale parameter must be greater than 0. In the estimation of the utility equations used in the choice model coefficients are estimated for individual cost-terms (such as travel time. Forecast demand ODEMANDMW = 21. Thus. .02 allcar allpt. 12.24.22. . Top level nest SPLIT = TOTAL 0. the scale parameters of utility-based models are viewed as part of the specification of the output of a split process. it may be specified once and brackets used to group the relevant sub-nests. Where the scale parameter for a sub-nest is 1. To meet the sensitivity requirements noted above. . there is a requirement that higher level nests are less sensitive to cost differences than any sub-nests which lie below them. Train nest SPLIT = train 0. . Model Structure . All PT nest SPLIT = allpt 0.25.0. As with cost-based models.9 Matrix Program Using the Matrix program .05 car pandr. 16. and different values may apply to each sub-nest in a choice nest. 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 fare) and for scale parameters. and a number of sub-nests. .23. . 14. Matrix script illustrating two-level hierarchy 440 Cube Voyager Reference Guide . 13.26. 15. so avoiding repetition of the parameter. All car nest SPLIT = allcar 0. 5.6 SPLIT = TOTAL 1.Matrix Program Using the Matrix program 9 Using the tree structure shown in “Structure of hierarchical logit model” on page 436 as the basis of an absolute choice model. followed by the output forecast demand by mode. PT sub-nest has scale parameter 0. this is the name given to the combined choice of bus and train. . Forecast composite cost for the top level SPLITCOMP = 19. Notice that PT is not declared as an alternative. . Forecast demand ODEMANDMW = 14. Working matrices STARTMW =70 First the modes (car. Absolute hierarchical logit model XCHOICE. . List choices ALTERNATIVES = car bus train. . . Input demand DEMANDMW = 1. Input costs UTILITIESMW = 4. A scale parameter of 0. 6. PT nest SPLIT = PT bus train . Top level nest. Forecast composite cost for the PT nest SPLITCOMP = 20. Model Structure .0 car 0. . Cube Voyager Reference Guide 441 . the total demand is specified together with the utility of each choice (car.15. . Then the model inputs and outputs are specified.6 pt.6 is applied to the PT sub-nest when its composite (or logsum) utility is used in the calculations of the higher-level nest. bus and train) are declared with the ALTERNATIVES clause. The hierarchical structure is specified by moving down the tree describing each nest. . bus and train). . The input total demand and utilities for the three distinct modes are given first.16. The second split command sub-divides PT trips between the bus and train alternatives. 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. 2. Utility differences DUTILSMW = 11. . 4.25. 16. 15. but no scaling parameters are used. The composite costs for this SPLIT are output with SLITCOMP. The example below is coded below in incremental form using utility differences: . Top level nest SPLIT = TOTAL 0.667 allpt.23. Forecast demand ODEMANDMW = 21. .4 allcar 0. . . The composite cost for this SLIT are output with another SPLITCOMP keyword. . . List choices ALTERNATIVES = car pandr bus hrail lrt metro.26. All PT nest SPLIT = allpt 1. and this acts as a link to the next level up the tree (where total demand was divided between car and PT). Extract from a large absolute logit model XCHOICE. 5. PT is not considered as an individual mode now. All car nest SPLIT = allcar car pandr. . 14. 13. The name pt is used as the first value in the SPLIT clause. Working matrices STARTMW = 45 442 Cube Voyager Reference Guide . 12. . . Base demand BASEDEMANDMW = 1. the first split command divides TOTAL (the total demand) into car and (all) PT. Train nest SPLIT = train hrail lrt metro.6 which applies to the PT sub-nest.0 bus 0.75 train. but as a link with the lower nest. Model Structure . 3.24.9 Matrix Program Using the Matrix program Beginning at the top of the tree.22. and specifies a scale parameter of 0. 6. . denote the choice of destination 1. Structure of destination choice model For the absolute choice model. where d1. Suppose that an aggregate demand model has 100 zones. Destination choice This section describes the destination-choice model.667 to the all-PT sub-nest and 0.75 to the train sub-nest. destination 2 and so on.4 is applied to the all-car subnest. Topics include: • • Introduction Matrix script Introduction This section shows how a logit model can be used to forecast destination choice. The figure “Structure of destination choice model” illustrates the structure. 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.Matrix Program Using the Matrix program 9 In this example a scale parameter of 0. also 0. d2.. the probability of choosing destination zone j from origin zone i is given by Pij: Cube Voyager Reference Guide 443 .. In this case. The incremental logit model is also supported.01 XCHOICE. . but with alternative modes replaced by destination zones. for examples UTILITIESMW (utilities) and DUTILSMW (differences in utilities). . 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. Its underlying theory is similar to the equations in the incremental logit model. 444 Cube Voyager Reference Guide . Alternatives (only one. For absolute utility-based models. The clauses defining data input reflect the data required by the model. . as doing destination choice) ALTERNATIVES = all . the choices are destination zones. Matrix script The destination choice model described above is coded in the script below.Specify choice parameter lambda = 0.9 Matrix Program Using the Matrix program Where λ is the scale parameter. Input demand from each origin DEMAND = TripsFromI[i]. and uses the incremental choice equations with alternative modes replaced by different destination zones.Simple destination choice model . In this model. the base situation matrices of demand and cost (or cost differences) are also input rather than total travel demand. the destination choice model takes the form: The incremental forms of logit choice model is also supported. The incremental model is more widely used in studies than the absolute formulation. Input cost matrix COSTSMW = 3. and no use of lambda. Cube Voyager Reference Guide 445 . . The outputs are a forecast demand matrix. Forecast demand from each origin to each destination ODEMANDMW = 7 . Model Structure DESTSPLIT = TOTAL lambda all. The output from the split clause is the alternative “all.Matrix Program Using the Matrix program 9 . Mode and destination choice This section discusses the mode-and-destination-choice model. Working matrices STARTMW = 20 The extract begins with the specification of alternatives. which comprises just one alternative as we have no choice between modes. the scale parameter. MW[7]. so that the DESTSPLIT clause now becomes DESTSPLIT = TOTAL all. The structure of this model is defined by the DESTSPLIT clause which defines a destination choice process. The main differences for utility-based scripts are use of utility keywords (UTILITIESMW being used in place of COSTSMW ). A scale parameter of λ=0. 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 is followed by the model inputs.01 has been chosen for this example. then destination followed by mode choice. This section considers first mode followed by destination choice.” as listed on the ALTERNATIVES keyword. in this case the demand is an array of trips from each zone and the generalized cost is matrix MW[3]. 01. and 100 destination zones (labelled d1.02 theta = 0. The parameters for destination choice are μ=0.. car and PT.01 mu = 0.03 for car and PT respectively.02 and θ=0. then across destinations for each mode individually. The model structure specification splits the total demand by mode first with scale parameter λ=0.. Mode followed by destination choice Consider first an example of mode followed by destination choice. which reflect sensitivity to cost differences. . 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). The figure illustrates a system with two modes. d100). 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. d2. Mode choice above destination choice model .03 XCHOICE..9 Matrix Program Using the Matrix program Which form of model is appropriate for a study is determined during model calibration. 446 Cube Voyager Reference Guide . Specify choice parameters lambda = 0. determine which form is used.. The values of scale parameter for the various choice nests. .. .. Working matrices STARTMW=110 Destination followed by mode choice Now consider the case of destination followed by mode choice. Destination followed by mode choice The total input demand is first by destination (into a matrix). d2. . Forecast demand matrices by mode ODEMANDMW = 31.2. which is then split by mode (giving two matrices representing car and PT demand).32. . car and PT. Cube Voyager Reference Guide 447 . Base Costs BASECOSTSMW = 11.22. . . . Base Demand BASEDEMANDMW = 1. List choices ALTERNATIVES = car pt. . and 100 destination zones (labelled d1. The figure illustrates such a system with two modes..12.. d100). .Matrix Program Using the Matrix program 9 . PT destination choice DESTSPLIT = destpt theta pt. Forecast costs COSTSMW = 21. Model Structure Mode choice SPLIT = TOTAL lambda destcar destpt Car destination choice DESTSPLIT = destcar mu car. . For example. Forecast demand matrices by mode ODEMANDMW = 21. .5 distribution. DUTILSMW = 16. .5. . Mode choice SPLIT = distribution car pt.22. is then used as the link (or input) to the lower choice nest. it is often useful to make certain choices unavailable. . Model Structure . Destination choice DESTSPLIT = TOTAL 0. and the intermediate matrix is identified by the name “distribution. distribution. 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.17. a rail mode might not be a practical alternative for travel between all zones in the study area.12. . Large in this context is 448 Cube Voyager Reference Guide . To make a choice unavailable you should give that choice a large positive generalized cost (or large negative utility).” This name. The mode-choice sub-nests has scale parameters of 0. List choices ALTERNATIVES = car pt. the model structure specification splits the total demand by destination. Input base demand and utility-difference matrices BASEDEMANDMW = 11.9 Matrix Program Using the Matrix program Matrix script Starting from the top. Destination followed by mode choice model XCHOICE. . endif For simple choices between alternative modes.. to select particular rows and columns of the matrix where the choice model is applied: . but the sensitivity (and so cost-coefficient) varies between segments. When a XCHOICE control statement occurs in the Matrix program it will typically be applied to all cells (or origin-destination pairs). . . try using a cost of 40000 minutes to make a particular choice unavailable. the following provides guidance on techniques used.... as needed . this may be extended. the cost coefficient may be specified as a matrix (such as MW[5].Matrix Program Using the Matrix program 9 100 times greater than typical costs.). subsequent clauses of XCHOICE statement. In some instances the model structure is common to all segments. if costs are up to 400 generalized minutes. These typically arise when matrices can be broken down into distinct segments (such as trips entirely within study area. or mi.apply the model to trips from zones 1-45 to zones 46-53 if (i < 45) JLOOP INCLUDE = 46-53 XCHOICE. test to see if model applies to this origin zone if (i < 45) . . or the user wishes to apply the choice model separately for each segment. Where the model structure varies between segments.coefficient) rather than a scalar value. Under these conditions. by use of the JLOOP command. . then apply the model XCHOICE. The XCHOICE control statement may be coded inside a conditional test which selects the origin zones it is applied to: . rather than the entire matrix. subsequent clauses of XCHOICE statement. as needed . through trips etc. Cube Voyager Reference Guide 449 .1. if so. 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. and different choice models apply to these different segments. For example. if the base demand for a choice is zero. this cannot be coded inside a JLOOP construct. . That is to say. if so.distance > 50) . Where these conditions are not met. . an error message will be output. 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. the forecast demand for that choice will always be zero.. but is determined by some other matrix attribute (such as distance from origin to destination). as needed . if Pcar=0 then P’car=0 whatever costs are given.. test to see if O-D meets selection criteria for the segment if (mi. Practical considerations: Incremental models In an incremental model.9 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. This is made clear if one examines the equation in the “Incremental logit model” on page 430. If this effect is a problem. then the modelling approach should be reviewed. subsequent clauses of XCHOICE statement. 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. then apply the model XCHOICE. endif ENDJLOOP Where a model seeks to use destination choice. 450 Cube Voyager Reference Guide . a script may be coded as follows: .1. the model’s sensitivity to cost increases down the hierarchy.start a JLOOP to process each origin-destination pair in turn JLOOP . Practical considerations: Scale parameters For models calibrated in terms of generalized costs to give sensible results. where. 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. ENDIF JLOOP .....” for details) Set zone renumber specifications Select standard reports Set multiple variables/arrays to same value Cube Voyager Reference Guide 451 . Control word ABORT ARRAY BREAK BSEARCH CALL CHOICE COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FREQUENCY GOTO IF ..Matrix Program Control statements 9 Control statements The following control words are available in the Matrix program. Call user’s dll (external process) Implement logit choice models (prior to v4... “General Syntax. ELSEIF .. “General Syntax”) Define user controlled loop Set static parameters Print variable values Print a row of a matrix (see Chapter 3. ENDJLOOP LOOKUP LOOP .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. ELSE .. n3]. Matrix Declares user single and multi-dimension arrays. You can create a test to find this and abort if it occurs. ARRAYNAME=n. I ABORT ENDIF ARRAY Programs: Distribution. the program detects walk access and drive access between the same zone pair. Example IF (MW[1][I] != 0) ABORT . TYPE= t.]]] 452 Cube Voyager Reference Guide . but you know that this should not occur..9 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. Matrix Aborts the entire run. For example. Generation. Fratar. Though not normally used. ARRAYNAME=n1[. MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager. Fratar. Intrazonal present in MW[1] INTRA = MW[1][I] IF (! INTRA) LIST='No intrazonal value for MW[1] at Zone '.. suppose that during a mode-split process. you can use this statement to terminate processing due to some detectable conditions. Generation. Keyword MSG |S| Description Optional message that can be printed when the program terminates.n2[.1) ABORT Programs: Distribution. When an array is referenced in an expression.| Description Name of the array that is to be allocated according to the specified size: n. and if any index exceeds its corresponding size. they are allocated prior to any stack operations. multi-dimension arrays can take up a significant amount of memory so their usage must be carefully planned. For example. An array is different from a variable in that it represents vectored data. When a single dimensioned array appears in a SET statement. Cube Voyager Reference Guide 453 . Arrays are cleared when they are allocated. Values stored to arrays in this program can be numeric or string. but the use of those arrays is somewhat different. The preceding TYPE= keyword sets the size of the individual cells of the array. ARRAY keyword Keyword ARRAYNAME |I. 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. and the mode (numeric or string) for the cells.. the program will fatally terminate. Use ARRAY to allocate user arrays.1. a double precision array of 1000x1000x100 will take up 800 MB of memory. Multi-dimension arrays provide considerably more capability – the user can specify up to 9 dimensions for a single array. it must include all the indices [ ].. multi-dimension arrays can be specified. The keyword TYPE is used to specify the size and mode of the array elements for the arrays that follow it. or ZONES. However. Arrays can be useful for different processes. The values must be either a numeric constant. Multi-dimensioned arrays can also be specified with the AUTOMDARRAY keyword on the FILEI MATI|DBI statements.Matrix Program Control statements 9 Beginning in version 5. ARRAYNAME must be a unique name. all the cells in the array are set to the same value. a common use may be to store information for specific zones. ARRAY statements are not dynamic (stack oriented). The values following the keyword represent the highest indexes possible for the array. 2 or 4 will automatically be cast as string. Additional system variables are available so the properties of an array can be accessed in the script: arrayname.a string that is the same as in the TYPE keyword arrayname.dimension .the number of dimensions arrayname.1. or the letter F or D. 454 Cube Voyager Reference Guide . 2 or 4 to indicate 1-byte (range -128 to +127). The values are simply truncated or modulated to fit the array element size. no indices for both arraynames. 2-byte (range 32768 to +32767) or 4-byte (range -2147483648 to +2147483647) integer data. COMP MDARRAY1=MDARRAY2. 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.5.0 x 10^-324 to 1. but any numeric value other than 1.an array of integers for the size of each dimension When multi-dimension arrays are referenced in COMP statements.5 x 10^-45 to 3. the value may be the number 1. If the array is to contain string data. no indices supplied indicate that the entire array (all cells) is to be populated with value.size[] . The default TYPE is D (double). the value should be preceded by the letter C follows by the maximum string size. to indicate single (+. If the array is to be numeric. several deviations from the standard COMP syntax rules are available to the user.type .9 Matrix Program Control statements ARRAY keyword Keyword TYPE S Description TYPE specifies the size of each array cell.7 x 10^308 with 15-16 significant digits) real data. For example: COMP MDARRAY=value. Storing bigger values in smaller size arrays will not cause errors or warnings.4 x 10^38 with 7-8 significant digits) or double precision (+. The user must choose the correct data type for the array that are big enough to hold the anticipated data but minimize memory usage. they will simply be ignored. But. with the added keywords. In this COMP statement (without the added sub keywords). a #n in the expression that does not appear as a subscript in the result will cause a fatal error. #2=20-max. the user can cause a filter to be invoked within the loop. The values for #n sub-keys can be integers. = expression will cause an automatic internal loop for the indexes that have #n specified. #1 would loop from 1-10. This is done by using #n keywords with ranges following the expression. #1=1.8-10. The loop will begin at 1 and continue until to the number of cells declared for that index is reached... By default. Cube Voyager Reference Guide 455 .50. or the word MAX. these variables are actually place holders. COMP MDARRAY[#n][#n]. COMP array1[#1][#2] = expression. any #n index in the result will cause an internal loop from 1 to the upper limit of that index.the number of indexes for the array. However. 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. and 8-10.) If the expression does not contain any reference to any of the #n's in the result array. but it is recommended to code any pair as low-high.Matrix Program Control statements 9 Such a statement will cause all the elements from MDARRAY2 to be copied to MDARRAY1. the elements will be converted during the copy. the smallest dimension will be used as the upper limit. simple variable names. The #n can be #1 up to #9. If a pair of values is specified. which may be used to specify the upper limit for that dimension. so the first subscript could actually be [#9]. and #2 would loop from 20 to 50. However. if the same #n is specified for more than one index. If the element sizes of the arrays are different.. and would be applied only for values of 1. But. Filter values outside of the valid range for the dimension will not cause an error.. 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. (array[#3][2][#3] would be valid for a 3 dimensioned array. Eg. ARRAY array1=15.3.. 3. Any #n subscript for the result can be used as a subscript or as a variable in the expression. The n in #n may be 1 . #1 would normally loop from 1 to 15 and #2 would loop from 1-50. 3 IF (condition) statements ELSE BREAK .9 Matrix Program Control statements Although all the above computations could be completed with standard scripts using loops.63.K2.. control immediately passes to the stack statement after the associated end of loop.. BREAK Programs: Distribution.3. #1=1.88 456 Cube Voyager Reference Guide . defines a string array with size of 1000 and a character width of 5. #2=20-max. the short-cut methods shown above can reduce user coded script. Fratar. jump to IF statement ENDIF ENDLOOP IF (condition) BREAK ..KINC JLOOP EXCLUDE=25-50. Example LOOP L1=1. example of defining a string array ARRAY TYPE=C5 StrArray=1000. cbd2ext=500 IF (M <= 10) sum_mat[M] = sum_mat[M] + rowsum(M) IF (I=1-10. Generation. and can drastically improve execution times. control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J will be reset to 1). no more processing for this origin zone LOOP L2=K1.50. Array1 is a double precision (8 byte) array dimensioned [zones][50] COMP array1[#1][#2] = expression. Matrix Use BREAK to break out of a loop. Otherwise. When encountered.51-58.96) cbd2ext[I] = cbd2ext[i] + MW[1] include=501-535 ARRAY row_total=zones . stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed.8-10. ARRAY array1=zones. If BREAK is within a LOOP or JLOOP block. Example ARRAY sum_mat=10. . If there are multiple arrays specified. The format is: BSEARCH ARRAY=value.. ..Matrix Program Control statements 9 IF (condition) BREAK . BSEARCH stores results in the variable _BSEARCH. 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. jump to LOOP L3= ENDJLOOP LOOP L3=L2. the nth location is higher than the key. 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. If the array is a string (C) array. and the n-1 location is lower than the key). the result of the expression must be a string. 0 — Indicates that the key is greater than the value in the highest location in the array.. The routine will do a binary search to expedite the search for the key. jump to ABC= ENDLOOP ABC=. ARRAY |N| is the name of a user array that is in ascending sort. YOURARRAY=100 Cube Voyager Reference Guide 457 . any constant value must be placed within quotes. If the value is an expression. • Example ARRAY MYARRAY=100.L2+5 IF (condition) BREAK. but the nth location is where one would insert the key (that is. ARRAY=value. 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. and address of a routine 458 Cube Voyager Reference Guide . Keyword DLL |S| Description Single string that contains the DLL file name. Fratar. The “DLL” extension is appended by the program. J. the file name may be case sensitive. To use this statement. there must be an external file that is a dynamic link library (DLL). address of MW. Matrix Executes an external routine. address of a routine to obtain address of any variables. The routine is called with one argument: the address of a structure that contains: I.FIELD1='875' CALL Programs: Distribution. and they can all be accessed by this run of the Matrix program. this depends upon the compiler/linker system used to develop the DLL. The DLL file may have multiple entry points. YOURARRAY=(MYARRAY[j]*3) Example FILEI ARRAY BSEARCH DBI[1]=MYDBF. In some operating systems. Zones.1. which contains the entry point that is desired to be used at this location. Iteration. DLL Use CALL to execute an external process. The routine name is usually case sensitive.YOURARRAY BSEARCH MYARRAY=32. AUTOARRAY=FIELD1 SORT=FIELD1 MYARRAY=100. followed by the name of the routine entry point enclosed within parentheses. 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. YOURARRAY=100 DBA. Generation. without extension.9 Matrix Program Control statements some code to populate the arrays SORT ARRAY=MYARRAY. 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. The C structure is illustrated in the sample code section below. the address of each MW would have to be obtained individually. Indirect referencing is not quite as efficient as direct addressing. an efficient way if MWs need not be allocated. Zones. and Cube Voyager Reference Guide 459 . Saving the address returned from pfVarFind (”MW”. the access to MW[1][1] would NOT be the typical MW(1. and there are many references to MWs. The routine would probably declare the array as: DOUBLE PRECISION MW1(0:*). J. MWs are allocated individually. the returned addresses can be stored in static cells so that pfFfindVar need not be called on every entry. and passed through an interface to a separate routine for actual use of the MW.. MW[1][1] would be the correct notation to address the cell for zone 1 in MW[1]. 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]. This can be done by calling pFfindVar for MW. pfFindVar will return NULL if the routine tries to obtain their addresses. The Matrix program allocates MW arrays only when it is necessary. but there is minimal difference. but because these variables must be protected. Indirect referencing to MW from the passed structure. In Fortran (without pointers)..1). Calls to pfFindVar need to be made only during the first entry into the procedure. The calling process adheres to standard “C” notation. Note that this is the cell for column 0. Instead. and Iteration are passed as integers. All variables (with a few isolated exceptions) are stored as double precision values. The addresses of these variables could be found by using the pfFindVar routine.): the required way if MWs need to be allocated. so the routine has to make sure that any MWs that it wishes to use are allocated. rather than as a single block. I.Matrix Program Control statements 9 to print messages. and there are not many references to MWs. • • The pfFindVar routine is used to obtain the pointer to any variables that are to be made available to the external process. NOT column 1. • sMmessage — The message string (ASCIIZ) to be printed. void* (*pfPrnLine)(int. /* * At first entry (when MW==NULL).9 Matrix Program Control statements appending the integer numbers of the MWs that the procedure will use. pfFindVar need not be used at all. 460 Cube Voyager Reference Guide .user function*/ #include <stdio.j. the routine will access a dummy array. it may contain any normal printer characters. } CallStack.2=Message. If this is not done.2.3.. int _export User1 (CallStack* Stack) { char message[100]. J..). \r. char*).4. N is the number of new lines to print before printing the message. Iteration.1. static double** MW=NULL. and the routine accesses an MW that has not been allocated.h> typedef struct { int I. Fatal). The pfPrnLine function is called. It has the format SFEN where.5).\f. /* store the address of MW array */ int m.dll // Sample of user function code in C /*TITLE: User1 -. * establish MW and insure that MW[1-5] have been allocated */ if (MW == NULL) { MW = (*Stack->pfFindVar)("MW".1. void* (*pfFindVar)(char*.. Zones. If the user is sure that all the desired MWs have been previously allocated by the Matrix program. Example CALL DLL=user(_User1) . with two arguments. double** MW. Warning. F is a 1 if the message is to be written to the error file E is the level of the message (0. to print a message: • nCtl — The control word for print the message. including \n. call the following code in user.\t etc. NOTE: XCHOICE is the preferred command statement for implementing logit-choice models. m<=5. Zones=%i". /* Stack->MW[m][j] is a similar way to reference MW[m][j] */ return 0. Stack->I. J=%i. Stack->J. j++) MW[m][j] = Stack->I*100 + m*10 + j. ALTERNATIVES BASECOSTS BASEDEMAND BASEUTILS COSTS DCOSTS DEMAND DESTSPLIT (COEFF. SPLITINTO. INCLUDE."User1 Call I=%i.Matrix Program Control statements 9 /* Example of forming a message */ sprintf(message. } CHOICE Program: Matrix Implements a logit-choice model. EXCLUDE) DUTILS OCOMPCOST OCOMPUTIL ODEMAND Cube Voyager Reference Guide 461 . Stack->Zones).message). /* Example of printing a message */ (*Stack->pfPrnLine)(1. } /* Sample to fill in MW[1-5] */ for (m=1. j<=Stack->Zones. m++) for (j=1. This clause is only used in incremental models which specify base and forecast costs (as opposed to cost differences). 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. the COSTS clause is not used in conjunction with the latter.9 Matrix Program Control statements SPLIT (COEFF. or numeric values such as 0. the change in cost for each choice can be given instead of the base and forecast costs. The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT commands which define the structure of the logit choice model. the order must match that in the ALTERNATIVES clause. The corresponding forecast costs are specified using the COSTS clause. which can be based either on generalized costs or utilities. Supplies the names of the base-cost variables. BASEDEMAND Supplies the names of the base-demand variables for incremental models only. For lists of two or more variables. and also determine the order that input or output data are specified. BASECOSTS COSTS 462 Cube Voyager Reference Guide . If there is more than one cost specified. SPLITINTO) STARTMW UTILITIES Use the CHOICE command to implement logit-choice models. then the alternatives list comprises just one item (representing the demand matrix). the order must match the list of choices given in the ALTERNATIVES clause. Specifies forecast costs. These cost-differences may be specified as matrices. See also BASECOSTS and DCOSTS (cost-differences) for incremental models.0. their order must be the same as that used in the ALTERNATIVES clause. For lists of two or more variables. DCOSTS For incremental models only. ODEMAND Cube Voyager Reference Guide 463 . a demand of 100. This clause is not supported for destination-choice models. COEFF = 0. INCLUDE = 1-57. which specifies the working matrix (MW) that stores the result. then the list must be in the same order as used in the ALTERNATIVES clause. allTrips. and this form of logit model may not be used inside a JLOOP construct. representing either a distinct choice from the ALTERNATIVES clause or an output which links to a subnest. Specifies the working matrices (MWs) used to store the forecast demand. The output list must comprise just one item. Outputs the composite cost of all choices for an absolute model. and may be omitted if only the composite costs are required. which are specified by the EXCLUDE subkeyword: DESTSPLIT = TOTAL. 0. The DESTSPLIT clause is used when the nest in the hierarchy corresponds to a destination choice model.0 will give output demand corresponding to the percentages which choose each alternative. the list comprises a list of working matrix numbers. By using the INCLUDE or EXCLUDE clauses the choice process may be restricted to a subset of all zones. SPLITINTO. The following example shows destination choice over zones 1 to 57: DESTSPLIT = TOTAL. SPLITINTO = allTrips.3. SPLITINTO = allTrips. The list contains a numeric value.3. If there is more than one cost variable. Note that certain restrictions apply to the use of destination choice models. It divides the travel demand between destination zones. OCOMPCOST Optional. rather than alternatives.Matrix Program Control statements 9 CHOICE keywords: Cost-based models (continued) Keyword DEMAND Description Specifies total demand for an absolute model. EXCLUDE) and DESTSPLIT = TOTAL. This command is optional. This shows destination choice over zones except for 88 to 100. COEFF = 0.3. For example. INCLUDE. although numeric values may be specified. EXCLUDE = 88-100. Demand is typically a matrix. DESTSPLIT (COEFF. the composite cost for the highest level nest may be saved. as the composite costs are zonal values rather than matrices.3. By default the destination choice model works over all zones. it may be specified in one clause or divided into constituent parts by use of the COEFF and SPLITINTO clauses. 0. Where the choice model has a hierarchic structure. allTrips. Examples are: DESTSPLIT = TOTAL. Like the SPLIT command. The composite costs may not be saved. a scale parameter (or coefficient of cost). these are typically specified starting at the top-level and working down the structure. SPLITINTO) Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT clauses. COEFF = 0. 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. and should not be used elsewhere in the script. trips from cordon into study area. Rail. or links to subnests which are given unique meaningful names and used as inputs to lower splits. 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. Rail. Bus. a variable.3 to divide between bus and rail alternatives. the same STARTMW value may be used in all instances. and through traffic) and these segments respond differently to cost differences. Where a Matrix script contains several CHOICE commands. One of these clauses is required for each nest (or subnest) in the model hierarchy. or the SPLITINTO clause define the output list. Specified as a SPLIT clause it takes the form: SPLIT = AllPT. SPLITINTO = Bus. Working matrices from the STARTMW value upwards are used by the CHOICE command. Each SPLIT clause specifies an input. and one or more outputs.9 Matrix Program Control statements CHOICE keywords: Cost-based models (continued) Keyword SPLIT (COEFF. 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.3. or even a matrix with differing values between origindestination pairs. The coefficient is specified as the second item in the SPLIT clause. and using subkeywords it is: SPLIT = AllPT. The latter is appropriate when the demand matrix comprises distinct segments (such as travel within study area. 464 Cube Voyager Reference Guide . It may be specified as a numeric value. The items represent either distinct choices (from the ALTERNATIVES clause). The coefficient and outputs may both be specified in the SPLIT clause or specified using the COEFF and SPLITINTO subkeyword clauses. or using the COEFF subclause. The remainder of the SPLIT clause. 0. For a hierarchic model.3. The following examples shows a subnest taking AllPT as an input and using a scale parameter of 0. Cube Voyager Reference Guide 465 . a demand of 100. rather than alternatives. and also determine the order that input or output data are specified.Matrix Program Control statements 9 CHOICE keywords: Utility-based models Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario. Supplies the names of the base-demand variables. It divides the travel demand between destination zones. The composite utilities cannot be saved. INCLUDE = 1-23. Use the DESTSPLIT clause when the nest in the hierarchy corresponds to a destination-choice model. The output list must comprise just one item. The following example applies a scaling factor to the ModeSplit logsum utility. For example.9 ModeSplit. The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT commands which define the structure of the logit-choice model. The corresponding forecast costs are specified using the UTILITIES clause. representing either a distinct choice from the ALTERNATIVES clause or an output which links to a subnest. allTrips. This output item may be preceded by a scale parameter. EXCLUDE) By default the destination-choice model works over all zones. the order must match that in the ALTERNATIVES clause. For lists of two or more variables. The following example restricts destination choice to zones 1 to 23: SPLIT = TOTAL. Demand is typically a matrix. For incremental models only. Supplies the names of the base utilities for the various alternatives. although numeric values may be specified. DEMAND Specifies the total demand for an absolute model.0 will give output demand corresponding to the percentages which choose each alternative. and this form of logit model may not be used inside a JLOOP. If the model is confined to destination choice. This clause is only used in incremental models which specify base and forecast utilities (as opposed to utility differences). BASEDEMAND BASEUTILS DESTSPLIT (INCLUDE. then the alternatives list comprises just one item (representing the demand matrix). NOTE: Certain restrictions apply to the use of destination-choice models. the order must match that given in the ALTERNATIVES clause. For lists of two or more variables. By using the INCLUDE or EXCLUDE subkeyword clauses the choice process may be restricted to a sub-set of all zones. and performs a destination choice dividing the total trips across all destinations: DESTSPLIT = TOTAL 0. Specifies the working matrices (MWs) used to store the forecast demand. then the list must be in the same order as used in the ALTERNATIVES clause. Outputs the composite utility (or logsum value) of all choices for an absolute model. Where the choice model has a hierarchic structure.9 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. Optional. For incremental models only.0. This command may be omitted if only the composite costs are required. as the composite costs are zonal values rather than matrices. Optional. This clause is not supported for destination-choice models. These utility-differences may be specified as matrices. If there is more than one cost variable. the list comprises a list of working matrix numbers. OCOMPUTIL ODEMAND 466 Cube Voyager Reference Guide . The list contains a numeric value which specifies which working matrix (MW) is used to store the result. or numeric values such as 0. the composite utility for the highest level nest may be saved. Each SPLIT clause specifies an input. The main items in the output list represent either distinct choices (from the ALTERNATIVES clause). these are typically specified starting at the top-level and working down the structure. and must not exceed 1. where scale parameters are applied to the PT and walk/cycle subnests. where the bus and rail subnests share the same scale parameter. For a hierarchic model.4 Car 0. An example is: SPLIT = AllPT Bus Rail. One of these clauses is required for each nest (or subnest) in the model hierarchy. The scale parameter should be greater than 0. or a subnest with a default scale parameter of 1. Subnests in the output list may be preceded by a scale parameter. and one or more outputs which may have their own scale parameters. as this is the assumed default. The remainder of the SPLIT clause define the output list. and any scale parameters which apply to subnests. Where the same scale parameter applies to several subnests. Car either is a distinct alternative. or links to sub-nests which are given unique meaningful names and used as inputs to lower splits. (A choice with only one output may be specified to apply a scaling factor to a sub-nest logsum utility. the scale parameter may be specified once followed by the list of relevant subnests grouped together by use of brackets. Cube Voyager Reference Guide 467 . An example is: SPLIT = TOTAL.0. The scale parameter may be omitted where its value is 1.5 (Bus Rail).5 PT 0.0. which is applied to the composite (or logsum) utility of the subnest before evaluating this choice nest.4 WalkCycle.Matrix Program Control statements 9 CHOICE keywords: Utility-based models (continued) Keyword SPLIT Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT clauses. and so achieve consistent scaling at all equivalent levels in a complex hierarchic structure.0. and a different value applies to the car subnest. Examples are: SPLIT = TOTAL Car 0. 0.) 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. but there are some differences in keyword usage and in value formats for keywords. ALTERNATIVES COSTSMW BASECOSTSMW DCOSTSMW UTILITIESMW BASEUTILSMW DUTILSMW 468 Cube Voyager Reference Guide . and should not be used elsewhere in the script. 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. the same STARTMW value may be used in all instances. Where a Matrix script contains several CHOICE commands. Citilabs recommends using the XCHOICE command statement for logit choice models. Usage is similar with XCHOICE. resulting in improved run times. Though you can continue to use CHOICE. See “Summary of syntax usage differences between XCHOICE and CHOICE” on page 475. Working matrices from the STARTMW value upwards are used by the CHOICE command. their order must be the same as that used in the ALTERNATIVES clause. Specifies forecast utilities. If there is more than one utility. XCHOICE replaces the CHOICE command statement. 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.9 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. and also determine the order that input or output data are specified. the order must match the list of choices given in the ALTERNATIVES keyword. The corresponding forecast costs are specified using the COSTSMW keyword. the order must match that in the ALTERNATIVES keyword. BASECOSTSMW Cube Voyager Reference Guide 469 . For lists of two or more matrices. SPLITINTO SPLITCOMP) DESTSPLIT (COEFF.Matrix Program Control statements 9 DEMANDMW DEMAND BASEDEMANDMW ODEMANDMW SPLITCOMP SPLIT (COEFF. 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. BASEDEMANDMW Supplies the names of the base demand matrices. The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT keywords which define the structure of the logit choice model. For incremental models only. based on either generalized costs or utilities. INCLUDE. For lists of two or more matrices. then the alternatives list comprises just one item (representing the demand matrix). This keyword is only used in incremental models which specify base and forecast costs (as opposed to cost differences). If the model is confined to destination choice. Supplies the names of the base cost matrices. EXCLUDE) STARTMW Use the XCHOICE command to implement logit choice models. SPLITINTO. NOTE: Certain restrictions apply to the use of destination-choice models. the list comprises a list of working matrix numbers. Use the DESTSPLIT keyword when the nest in the hierarchy corresponds to a destination-choice model. COEFF EXCLUDE = 88-100. rather than alternatives. These cost-differences may be specified as matrices. which are specified by the EXCLUDE subkeyword: DESTSPLIT = TOTAL. INCLUDE = 1-57. The composite costs may not be saved.3. allTrips. then the list must be in the same order as used in the ALTERNATIVES keyword. By using the INCLUDE or EXCLUDE subkeywords the choice process may be restricted to a subset of all zones. See also BASECOSTSMW and DCOSTSMW (cost-differences) for incremental models.3. DCOSTSMW Gives the change in cost for each choice rather than the base and forecast costs. 0.9 Matrix Program Control statements XCHOICE keywords: Cost-based models (continued) Keyword COSTSMW Description Specifies forecast costs matrices. ODEMANDMW Specifies which working matrices (MWs) store the forecast demand. It divides the travel demand between destination zones. = 0. The demand value for a destination-choice or mode. DEMAND DEMANDMW DESTSPLIT (COEFF. or numeric values such as 0. SPLITINTO. The output list must comprise just one item. Examples are: DESTSPLIT = TOTAL. For incremental models only. If there is more than one cost matrix. The following example shows destination choice over zones 1 to 57: DESTSPLIT = TOTAL. allTrips. INCLUDE. If there is more than one cost specified. SPLITINTO = allTrips.3.3. 0. SPLITINTO = allTrips.and destination-choice model. and this form of logit model may not be used inside a JLOOP construct.0. and this shows destination choice over zones except for 88 to 100. EXCLUDE) and DESTSPLIT = TOTAL. COEFF = 0. The demand matrix for a pure mode-choice model. Like the SPLIT command. 470 Cube Voyager Reference Guide . representing either a distinct choice from the ALTERNATIVES keyword or an output which links to a subnest. By default the destination choice model works over all zones. their order must be the same as that used in the ALTERNATIVES keyword. it may be specified in one keyword or divided into constituent parts by use of the COEFF and SPLITINTO subkeywords. the COSTSMW keyword is not used in conjunction with DCOSTSMW. or even a matrix with differing values between origin-destination pairs. and using subkeywords it is: SPLIT = AllPT. trips from cordon into study area. The SPLITCOMP subkeyword specifies the working matrix to store the composite costs or composite utilities for the nest defined by its parent SPLIT keyword. a variable. or the SPLITINTO subkeyword define the output list. The latter is appropriate when the demand matrix comprises distinct segments (such as travel within study area. Rail. For a hierarchic model. these are typically specified starting at the top level and working down the structure. The coefficient and outputs may both be specified in the SPLIT keyword or specified using the COEFF and SPLITINTO subkeyword clauses. Specified as a SPLIT keyword it takes the form: SPLIT = AllPT. Each SPLIT keyword specifies an input. Cube Voyager Reference Guide 471 . and through traffic) and these segments respond differently to cost differences. It may be specified as a numeric value.3.Matrix Program Control statements 9 XCHOICE keywords: Cost-based models (continued) Keyword SPLIT (COEFF. Rail. 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. Bus. COEFF = 0. or links to sub-nests which are given unique meaningful names and used as inputs to lower splits. SPLITCOMP) Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT keywords. and one or more outputs. The items represent either distinct choices (from the ALTERNATIVES keyword). 0. SPLITINTO. or using the COEFF subkeyword. a scale parameter (or coefficient of cost).3 to divide between bus and rail alternatives. The remainder of the SPLIT keyword. The coefficient is specified as the second item in the SPLIT keyword. One of these keywords is required for each nest (or subnest) in the model hierarchy. SPLITINTO = Bus. The following examples shows a subnest taking AllPT as an input and using a scale parameter of 0.3. 1.4.c. XCHOICE keywords: Utility-based models Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario.2 B C. destpt. SPLIT= pt 0. baseCOSTSmw = 2. For incremental models only. destSPLIT= destpt 0. 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.8. If the model is confined to destination choice.3. the same STARTMW value may be used in all instances.9 Matrix Program Control statements XCHOICE keywords: Cost-based models (continued) Keyword SPLIT (continued) Description Example: XCHOICE ALTERNATIVES = A. Supplies the names of the base demand matrices. SPLITCOMP=21. basedemandmw=1. 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. Working matrices from the STARTMW value upwards are used by the XCHOICE command. For lists of two or more matrices. SPLIT= Total 0.1. BASEDEMANDMW 472 Cube Voyager Reference Guide .1 desta.5.3. SPLITCOMP=20. and also determine the order that input or output data are specified. and should not be used elsewhere in the script.15 a. ODEMANDmw=6. COSTSmw = 2.15 pt. Where a Matrix script contains several XCHOICE commands. destSPLIT= desta 0.7. the order must match that in the ALTERNATIVES keyword. 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.b. The corresponding forecast costs are specified using the UTILITIESMW keyword. and this form of logit model may not be used inside a JLOOP.Matrix Program Control statements 9 XCHOICE keywords: Utility-based models (continued) Keyword BASEUTILSMW Description Supplies the names of the base utility matrices for the various alternatives.9 ModeSplit. Use when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand between destination zones. The composite utilities cannot be saved. the order must match that given in the ALTERNATIVES keyword. DEMAND DEMANDMW DESTSPLIT (INCLUDE. If there is more than one cost matrix. This output item may be preceded by a scale parameter. This keyword is only used in incremental models which specify base and forecast utilities (as opposed to utility differences). The following example restricts destination choice to zones 1 to 23: SPLIT = TOTAL. rather than alternatives. By default the destination choice model works over all zones. For incremental models only. DUTILSMW Gives the change in utility for each choice rather than the base and forecast utilities. The following example applies a scaling factor to the ModeSplit logsum utility. Specifies working matrices (MWs) used to store the forecast demand. By using the INCLUDE or EXCLUDE subkeywords the choice process may be restricted to a subset of all zones. This command is optional. allTrips. These utility-differences may be specified as matrices. and performs a destination choice dividing the total trips across all destinations: DESTSPLIT = TOTAL 0. and may be omitted if only the composite costs are required.0. the list comprises a list of working matrix numbers. For lists of two or more matrices. representing either a distinct choice from the ALTERNATIVES keyword or an output which links to a subnest. The output list must comprise just one item. EXCLUDE) The demand value for a destination-choice or mode. ODEMANDMW Cube Voyager Reference Guide 473 . NOTE: Certain restrictions apply to the use of destination choice models. or numeric values such as 0. The demand matrix for a pure mode-choice model. then the list must be in the same order as used in the ALTERNATIVES keyword.and destination-choice model. INCLUDE = 1-23. One of these keywords is required for each nest (or subnest) in the model hierarchy. and so achieve consistent scaling at all equivalent levels in a complex hierarchic structure.4 Car 0. or links to subnests which are given unique meaningful names and used as inputs to lower splits.0. For a hierarchic model. Each SPLIT keyword specifies an input. and any scale parameters which apply to subnests. and must not exceed 1. the scale parameter may be specified once followed by the list of relevant subnests grouped together by use of brackets. where the bus and rail subnests share the same scale parameter. Examples are: SPLIT = TOTAL 1.5 (Bus Rail). 0.0 cannot be omitted in XCHOICE. An example is: SPLIT = TOTAL. For example: split=total.pt. Subnests in the output list may be preceded by a scale parameter.9 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.0. An example is: SPLIT = AllPT Bus Rail.4 WalkCycle. 474 Cube Voyager Reference Guide . where scale parameters are applied to the PT and walk/cycle subnests. (A choice with only one output may be specified to apply a scaling factor to a subnest logsum utility.5 PT 0.1.5. which is applied to the composite (or logsum) utility of the subnest before evaluating this choice nest. and one or more outputs which may have their own scale parameters. Scalars of 1. The remainder of the SPLIT keyword define the output list.0 Car 0.0.0. Where the same scale parameter applies to several sub-nests. or a subnest with a scale parameter of 1. these are typically specified starting at the top level and working down the structure.auto. The scale parameter should be greater than 0. For utility-based models.) 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. and a different value applies to the car subnest. if one alternative has a scalar. Car either is a distinct alternative. The main items in the output list represent either distinct choices (from the ALTERNATIVES keyword). all others must also have scalars. 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 . If there is more than one utility. the UTILITIESMW keyword is not used in conjunction with DUTILSMW. their order must be the same as that used in the ALTERNATIVES keyword. the same STARTMW value may be used in all instances. 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. Specifies forecast utilities. use DEMAND instead. 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. there must be one and only one case-insensitive “Total” in a SPLIT clause. and should not be used elsewhere in the script. In destination-choice or mixed modeand destination-choice models.Matrix Program Control statements 9 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. Working matrices from the STARTMW value upwards are used by the XCHOICE command. See also BASEUTILSMW and DUTILSMW (utility-differences) for incremental models. All matrix valued keywords must end with MW. “Total” is the starting node for mode split. Where a Matrix script contains several XCHOICE commands. UTILITIESMW Summary of syntax usage differences between XCHOICE and CHOICE In each XCHOICE. DEMAND =tripsfromi[1]. . both of these two following cases work: SPLIT = TOTAL 0. DEMAND =tripsfromi. DESTSPLIT must start with alternatives prefixed with “dest” (for example.01 destcar destpt. all others must also have scalars. . DESTSPLIT = destcar 0.03 pt.OR.OR.01 car pt. For utility-based model. . Both “x” or “destx” are acceptable in the higher level SPLIT clause.OR. and end with corresponding alternative name.and destination-choice models. example: 476 Cube Voyager Reference Guide .. For mixed mode. DEMAND =myvar. .” Here is an example: ALTERNATIVES=car b c. DEMAND =100.OR.. 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 . DESTSPLIT = destpt 0.9 Matrix Program Control statements For example: . destx).. SPLIT = TOTAL 0. if one alternative has a scalar..02 car. Or SPLIT = TOTAL 0. DEMAND =tripsfromi[myindex].. for example “x.01 destcar destpt. In previous example. pt.0 can be omitted in CHOICE.Matrix Program Control statements 9 split=total. Matrix Computes a variable. COMP Programs: Distribution. OCOMPCOST and OCOMPUTIL in CHOICE are replaced by a new keyword SPLITCOMP in XCHOICE. Generation.0. Fratar. Unlike OCOMPCOST and OCOMPUTIL.5. VAR=expression MW[]=expression (INCLUDE EXCLUDE) Cube Voyager Reference Guide 477 . Scalar 1. matrix. or matrix element.0. but it cannot be omitted in XCHOICE.auto.1. 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. 478 Cube Voyager Reference Guide . MW EXCLUDE |IP| Optional. 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). Specified values can range from 1 to the highest zone number. Not permitted if COMP statement within JLOOP . 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.. the program only solves the expression one time only. Set the keyword equal to an expression you want to solve and store in a working matrix. By default no zones are excluded. Always processed after INCLUDE subkeyword. d. must be between one and ZONES. ENDJLOOP block. The Matrix program stores the values in working matrix n. • MW[n][d] — For the current origin zone (I). You may define up to MAXMW working matrices. the program does not evaluate or store the expression for that J. defines the expression solved for all destination zones (all values of J). defines the expression to solve at destination zone d. Filter applies to all MW[n] values on the COMP statement. with J being the value of the loop’s current J.. You may specify the index n using a constant or a variable name. The Matrix program stores the computed value in working matrix n. The Matrix program’s internal I-loop specifies I. If the current J is on the list. Values of J excluded when computing the MW[n] expression. It is used to compute variable and work matrix values. The second index.9 Matrix Program Control statements The COMP statement is probably the most important of all the statements in the program. As the program internally loops on J. You can specify working matrix expressions per origin zone or per origin zone and destination zone: • MW[n] — For the current origin zone (I). the program compares J to the values in the EXCLUDE list. Within a JLOOP statement. valid abc = abc+def .Matrix Program Control statements 9 COMP keywords (continued) Keyword MW Subkeyword INCLUDE |IP| Description Optional. All variables are assumed to be numeric variables. and special matrix functions on the statement. The expression is solved one time for each encounter. In the above examples. invalid: abc has been declared a string abc = abc+'456' . Not permitted if COMP statement within JLOOP . INCLUDE and EXCLUDE may not be specified within a JLOOP block. the statements with jkl= might never be executed. xyz is declared a string The program does not always bother computing expressions for variables that are not used as input to some process.. As the program internally loops on J. jkl is declared numeric jkl = xyz . with J being either one (not in JLOOP). Specified values can range from 1 to the highest zone number. the filters apply to all MW[]= values. Values of J included when computing the MW[n] expression. If the current J is not on the list. 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). EXCLUDE is processed after INCLUDE.don’t mix types jkl = 1 . or the value of the JLOOP J. messy -. By default all zones are included.. the variable must be a character string variable. unless their first appearance as a result in a COMP statement is with an expression that results in a character string. If expression results in a character string. the program does not evaluate or store the expression for that J. Filter applies to all MW[n] values on the COMP statement. If a COMP statement includes any INCLUDE or EXCLUDE filters. invalid: xyz is declared a string (later) xyz = 'xyz' . ENDJLOOP block. Examples: abc = '123' def = 123 abc = def . Cube Voyager Reference Guide 479 . the program compares J to the values in the INCLUDE list. no matter where they appear on the statement. because jkl is never used. MI.name.n. If a column index is used. For example: MW[1]="MI.T MI.T The expression is a standard Cube Voyager numeric expression.9 Matrix Program Control statements Supported expressions Special Matrix variables: MW[] MI. the zone index is computed.matnum.n. Rexpression may contain nested MW[].n. instead of the I-J value.T ZI. the column index (not explicitly expressed) will be supplied as J. the zone index (not explicitly expressed) will be supplied as I.matnum.name MI. The row index [n]. and underscores (_).name matrix.n.name 480 Cube Voyager Reference Guide . This triggers a preprocessor program that will transpose the matrix. MI.name[Cexpression] is a variation.matnum matrix.n. MI. then you must include the entire MI matrix reference in double quotes to recognize the name.1HBW TRIPS" MI. The row index [n] and the matnum must be constants.n.T MI. the retrieved cell represents the J-I value. the retrieved cell will represent the value of the cell for the index to I.matnum Value from the MI[n]. but there are also certain special variables names that may be used within it.T” indicates to use the transposed values for the matrix. Valid matrix names contain only alphanumeric characters. the column index (not explicitly expressed) will be supplied as J.n. Variable MW[Rexpression] Description Value from any work matrix. The appended “.name.n. Value from the MATI[n]. must be a constant.n. spaces.name matrix. Special cases for the above two MI formats. Transpose operation can only be applied to binary data.n.n. the column index is computed. Value from the ZDATI[n].n.matnum MI. Thus.name[Cexpression] is a variation. the column index (not explicitly expressed) will be supplied as J. ZI.matnum[Cexpression] is a variation. If matrix names have spaces. the column index is computed. be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression.name MI. 01. Combining functions on a single statement is permissible. hi will be set to lo. Lo and hi are inclusive values.5. if it is 0. the first argument (mw) indicates the work matrix to process. In the following matrix function descriptions. Example: DUMMY = ROWFAC(3. round.1. The function format has two advantages: coding is much easier. and should not be used within JLOOP blocks and MW[]= expressions. max.Matrix Program Control statements 9 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. In some cases. and lo is supplied.4. ln. min. log. and processing is more efficient. sqrt—see “Expressions” on page 33 for more details). and hi is not. the function will return a zero. Stores actual number of cells used in LOWEST. The matrix oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists). without any diagnostics. and must be specified. If an invalid argument is detected by a function. Warning: Dividing by LOWCNT. int.LOWCNT)/ 2 Cube Voyager Reference Guide 481 . some special purpose functions are available. you can use the max function to prevent this.I) /max(1. If “lo.. will cause a program error message. exp.hi” is allowed. Matrix function descriptions Function1 ARRAYSUM(array_name) LOWCNT Description Returns sum of an array (see “Examples” on page 555). they will be processed in appropriate order.5) + ROWFIX(3) will factor matrix 3 and then integerize it. Most of these functions could be duplicated with a combination of MW[]= statements. For example: W[mw][I] = LOWEST(mw. the intrazonal cell (I) would be excluded.lo.J. use caution when applying LOWEST with no range specified. variable.. F = MATI[#] M = Matrix # I=I J=J E = the value to return if the request for the cell is invalid. the program can not pre-edit the values. J [. Since this is direct access. E]) Returns random access values from MATIs (see “Examples” on page 555). I.9 Matrix Program Control statements Matrix function descriptions (continued) Function1 LOWEST (mw.#. normally. Each of the arguments can be an expression. the more efficient the access will be. For example: K = matval(3.-1) indicates to get the value from I to J from matrix 1 on MATI[3]. Use lo and hi to exclude possible dummy zones that appear as zero in the row. MATVAL (F. 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.) 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. Since all MWs are initialized to zeros.z. Use z to exclude specific zones.hi. or constant.. However. M. some types of processing will not be helped much by the use of the cache.lo. Because the arguments are dynamically set.z. This exclusion is in addition to any on an EXCLUDE list. 482 Cube Voyager Reference Guide . The range of arguments accommodates most situations.I.1. The cache size is specified by the PARAMETERS MATVALCACHE.#.#) LOWEST(mw.hi) LOWEST(mw. In general the larger the cache.. NOTE: LOWEST treats zeros as regular numbers. with rounding factor = 0).lo.fac) Factors the row by fac.Matrix Program Control statements 9 Matrix function descriptions (continued) Function1 ROWADD(d.s) ROWFAC (mw. w/ rounding factor = 0) Cube Voyager Reference Guide 483 .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. Integerize mw (start at column n.hi) Average cell value for nonzero values Average cell value for nonzero values. Same as: MW[mw] = MW[mw] * fac ROWFIX(mw) ROWFIX(mw..hi) ROWCNT(mw) ROWCNT(mw. but include only cells where: lo>=value<=hi (this can include 0)..s1. Divide MW[d] by MW[s] making all divided-byzero cells equal to 0.n) Integerize mw (start at column intrazonal + 1.lo. including only cells where: lo>=value<=hi Number of cells with nonzero values Number of cells with nonzero values. Same as: JLOOP IF (MW[s] == 0) MW[d] = 0 ELSE MW[d] = MW[d] / MW[s] ENDIF ENDJLOOP ROWDIV(d. 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. With a rounding factor of 0. the default condition starts at the cell after the intrazonal cell and wraps around until the intrazonal cell is the last cell processed.n. using specified rounding factor.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 . With a rounding factor of 0. To eliminate this bias. ROWFIX ensures the integer total is consistent with the original total.9 Matrix Program Control statements Matrix function descriptions (continued) Function1 ROWFIX(mw. ROWMAX(mw) ROWMIN(mw) ROWMPY(d. each cell is truncated and its fractional remainder is carried to the next cell. It integerizes each cell after adding the rounding factor and the accumulated fractional portions from the previously treated cells.5.rnd) Description Integerize mw (start at column n. the lowest numbered zones never gets their fair share of the fractions. rnd) ROWFIX integerizes the values in each cell of the matrix (that is. The optional second argument specifies which cell the process is to end with. drops all fractional portions of the number). read row for the . external user program FILEO MATO[1]=Fixed_trips00.Matrix Program Control statements 9 Matrix function descriptions (continued) Function1 ROWREAD(MW#. Allows for processing input matrix data not in I zone ascending sort order.m) .mat . dec=20*8 . loop over the 20 matrices .mo=1-20. 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. Matrix automatically runs an ILOOP . from I=1 to I=ZONES loop m=1. in the input file x=ROWREAD(m. with random I zone order from .I. MATI#. but include only cells where: lo>=value<=hi 1.mat. I. mw is a working matrix number (that is. M) Description Reads a random row from the input matrix and places it in the current row of the referenced working matrix. input matrix .hi) Row total Row total.1. current value of I and places it . in the work matrix endloop endrun ROWSUM(mw) ROWSUM(mw. defaults to lo if not specified Cube Voyager Reference Guide 485 .lo.20 . MW[1]) lo is the lo end of a range hi is the hi end of a range. stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed.1.1. MW[22]=MI.1.8. Generation.2. clear variables lookup name=f1.1) sumaf1=ROWSUM(2) CONTINUE Programs: Distribution. B=2. Otherwise. sum A*F endjloop . store only at intrazonal column ENDJLOOP set var=sumaf1.KINC 486 Cube Voyager Reference Guide . Example LOOP L1=1. bypassing all stack statements between it and its associated end of loop. Fratar.2. INCLUDE=1-100. will apply to all MW[]s= ABC=LOOKUP(DEF)*3 . If it is within a LOOP or JLOOP block.1) .1.K2. MW[K][I%10+1]=ODD.3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE .rowsum1 . control passes to the appropriate ENDLOOP or ENDJLOOP statement.1. no more processing for this origin zone LOOP L2=K1.401-500. MW[23]=MI.47-93 MW[3]=5*A. MW[4]=MW[3]*2.attr[j]*f1(MI.attr[j] * f1(mi.1. get total for mw[1] mw[2] = zi. MW[A]=A+B INCLUDE=1-5. Matrix Jumps to end of loop.9 Matrix Program Control statements Example MW[2]=J MW[K]=MW[2] * MW[5] / SQRT(A*MW[3][MW[22]]) A=1. MW[12]=MI. Next line is same process done with functions: rowsum1=ROWSUM(1) mw[2]=zi. EXCLUDE=90.3 JLOOP J=I MW[6]=J . A * F's sumaf1 = sumaf1 + mw[2] .93.12.12.452.1.txt JLOOP rowsum1 = rowsum1 + mw[1] . MW[13]=MI.2. file=f1. move input matrices to work areas MW[11]=MI. Use CONTINUE to immediately jump to the end of a loop.3 MW[21]=MI.2.1. Matrix Selects input data files. jump to ENDJLOOP . Fratar. Example IF (expression) EXIT FILEI NOTE: See “FILEI” on page 48 for general information about FILEI and for important limitations when using Application Manager. Generation. Generation.88 IF (condition) CONTINUE . 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 . Fratar.Matrix Program Control statements 9 JLOOP EXCLUDE=25-50. Matrix Exit the program before the end of zone processing Upon encountering EXIT.L2+5 IF (condition) CONTINUE . ENDLOOP ENDLOOP EXIT Programs: Distribution. and goes to the end of I-loop processing. Programs: Distribution. jump to ENDLOOP for L3 . the program immediately terminates stack processing. ENDJLOOP LOOP L3=L2. name5 sets up MATI[3]. name designates the matrix name or number..1. Data from these files is accessed via COMP statements. FILEI input data is normally entered in either matrix format or zonal vector format. If running scripts developed under v3.x series. and MATI[3]=name3. Refer to the descriptions below for the updated coding and comments on the processing. and are identified as MI.n.2. whereas zonal data is read prior to the initiation of the I-loop. Example: MI. Zonal data can be viewed as having zones rows with one column per zone. spaces. and need not be in any specified order. and must be in origin zone (I) order.name.3 indicates matrix number 3 on the MATI[1] file. The n designates subscript of the file..1HBW TRIPS" On the FILEI statement the subscript is either explicitly. defaults to MATI[1]. If matrix names have spaces. Matrix data is read dynamically (at the start of each Iloop).) will be treated as an error.x or earlier and using the RECI/RECO keywords you may need to make some slight modification to your scripts for proper processing. MATI=.0 and later: Significant changes in RECI/RECO processing have been made from v3.9 Matrix Program Control statements ZDATI (Z SELECT name (DEFAULT) AVE AVEX0 CNT FIRST LAST MAX MIN SUM) Note for v4. or implicitly. Cube Voyager matrices can have names and/or numbers. then you must include the entire MI matrix reference in double quotes to recognize the name. For example: MW[1]="MI. specified. it may have an additional subscript appended to it to specify a zone number. other matrices have only numbers. and underscores (_).6. Since it is required that ZDATI files have variables explicitly defined for them. the subscript references the column within a row. and zonal data files have names only. MATI[4]. Valid matrix names contain only alphanumeric characters.POP indicates the POP variable from ZDATI[6] file. When an input file is used in an expression.n. or as 488 Cube Voyager Reference Guide ..name and ZI. it references the nth item in the vector.. and MATI[5]. and for zonal data. ZI. For matrices.name4. file2.2. the vector form of ZDATI (ZDATI=file1. If MATI specifies an EMME/2 data bank file. ASCII type records are more subject to variation (empty fields.3[I] accesses the intrazonal cell. In this case. etc. or as data on ASCII or DBF type records. cause a fatal termination. then the file name must be emme2ban with no file extension. If there is no subscript specified. the values for the field are ignored. and further processing of the record is terminated. 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. To specify an EMME/2 data bank file.). On the other hand. each record containing all the variables in the element. those definitions are ignored. the current value of J is used.1. respectively. If ZDATI specifies an EMME/2 data bank file.TRMTIME[J] reference the origin and destination terminal times. The FILEI file keywords ZDATI. The Matrix program will not recognize any other file name as an EMME/2 data bank file. you can specify a definition for Z to indicate which MDB element represents the zone number. If a J or M is out of range. it is treated as an error. RECI. or in some cases.Matrix Program Control statements 9 one row having zones columns (user’s choice. Z= is not necessary if one of the element variables has an appropriate name for the zone number (see description of ZDATI for details). the Matrix program can read the scalar and vector matrices stored in the EMME/2 data bank file as zonal data records. On a ZDATI file name. The Matrix program will not recognize any other file name as an EMME/2 data bank file. and the program is a bit more tolerant with them. EMME/2 matrices stored in an EMME/2 data bank file. Cube Voyager Reference Guide 489 . PATTERN and FIELDS must be specified. and DBI can point to elements in a multidatabase (MDB) file by designating the filename followed by a backslash and the element name. Example: MI. it doesn’t matter). the file name must be emme2ban with no file extension. In the latter case. Matrices can be input as either binary matrices.TRMTIME[I] and ZI. invalid values. ZI. J will always be in the range 1-zones. If the FILEI file keyword value is followed by variable definitions. if the field contains non-numeric data. The program will generate a temporary file of records.6.1. #. Indicate fixed format fields by using name=lo[-hi] or field=lo[-hi] syntax. If you specify an ASCII record file. If you specify a DBF file.name) in the DBI statement.9 Matrix Program Control statements FILEI keywords Keyword DBI Subkeyword |KF9| Description Name of a DBF file.) Define a field as a character variable by appending “(C)” to the name. You must indicate which format is used in the definition of each field. 490 Cube Voyager Reference Guide . Reference the field names in the MDB data element directly in the script as DI. where lo is the first column number of the field and hi is the last column. If you specify an MDB\element file and name. MDB data element. ASCII record files are either a fixed format text file (fixed field locations and lengths). (Indicate a singlecolumn character with the hi column number the same as the lo column number. Reference the field names in the DBF header directly in the script as DI. Do not explicitly define the variables in the DBI statement. or free format.TITLE as a character variable. the program recognizes the file and the fields. TITLE(C)=1 would define the variable named DI. the program recognizes the file and the fields.fieldname.fieldname. 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. For example. using the appropriate keywords.#. Indicate free format with field definitions containing a single number. define all variables that you want the program to recognize (DBI. Do not explicitly define the variables in the DBI statement.#.#. 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. See “More on DBI” on page 510.#.TYPE=’C’) DBI. Cube Voyager Reference Guide 491 .TYPE=’N’) DBI.name[0] is used.1. If Index is less than 0 or greater than NUMRECORDS. the value at ARRAY[0] will be 0 for numeric fields and NULL for character fields.name[Index].#.CFIELD — String value for the field (Null if DBI.#. All the values (except Name and Type) are updated each time the record is processed.RECNO — Number of the currently processed record Different arrays are available.#.FIELDERR — 1 if the field had a format conversion error DBI.Matrix Program Control statements 9 FILEI keywords (continued) Keyword DBI (continued) Subkeyword Description The following special variables are available for all file formats: DBI.Name[0] = 'ERROR' or DBA. because the SORT routine uses that cell for temporary storage.1. DBI AUTOARRAY |S| Designates the name(s) of the field(s) that are to be stored in arrays with the specified name.NUMFIELDS]. The arrays are: DBI.NFIELD — Numeric value for the field (0 if DBI. An array for each named field will be generated and populated with values from the DBI records.#.NUMRECORDS.#.#. You can reference each array as DBA.#.TYPE — Type of field (either ‘N’ for numeric or ‘C’ for character DBI.NAME — Name of the field DBI. Note that if the name is included in a SORT. such as DBA.FIELDERRCNT — Cumulative count of errors for this field.#.#. the value in DBA.#.#. Each array is dimensioned as [DBI. If you enter a value of “ALLFIELDS. You can provide a substitute value for invalid Index processes.# — String variable containing the full data record DBI.NUMRECORDS — Number of data records in file DBI.#.#. By default.Name[0]=999999. [0] will be revised during the SORT.NUMFIELDS — Number of defined data fields DBI.” all the fields will be placed into arrays (no other names need be supplied). where Index may be 0-DBI.#. RECNO values will go into 4th dimension.fld-size. With no Indexes or ArrayFields specified.DBI. string to numeric). fld2 and fld3 determines the indexes for the first 3 dimensions and the fld4.fld5. the first dimension is the record number and the second dimension is the field number.fld3-30. Any records with an index value large than the stated size will not be loaded into the array.fld2-20. then the second dimension will have a size of 2. AutoMDArray=. A size value must be specified for each Indexes field and it should be large enough to accommodate the largest index value. All AutoMDArray defined after the TYPE keyword will have the same type as specified by the TYPE keyword. the values in fld1. This is very similar to the current AutoArray capability but can be used to load data into multi dimension arrays. ArrayFields=fld. the DBI file is loaded into a 2-dimension array. The TYPE keyword is the same as the TYPE keyword in the ARRAY statement for declaring the data type/size of the array.RECNO In this case. some of the fields in the record can be used as array indexes to populate the array. If there are 2 ArrayFields.g. selected fields can be loaded into the array. TYPE=. With the Indexes keyword. The special field name DBI. 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. AutoMDArray=name3. Indexes=fld-size. If the field values in record 3 are: 492 Cube Voyager Reference Guide .fldsize. ArrayFields=fld4.fld. Indexes=fld110.RECNO can be included to add a field that contains the record number of the DBI record. Data from the DBI record will be converted to a form that is compatible with the array type (e. This feature can be used to load only selected records into the array. If the data file has only one field or if only one field is specified in the ArrayFields keyword. name3 will have 4 dimensions (10x20x30x4).9 Matrix Program Control statements FILEI keywords (continued) Keyword DBI Subkeyword AUTOMDARRAY |S| Description FILEI DBI[]=.fld6. With the ArrayFields keyword. The AutoMDArray keyword is used to define the array name.fld This will load database or text file data into arrays before any script processing. fld5. For example: FILEI DBI[x]=xxx. fld6 and DBI. name3 will have 2 dimensions. ArrayFields=fld1. name3[3][3]=13 This form can be used to replace multi-key discrete lookup tables. Cube Voyager Reference Guide 493 . AutoMDArray=name3.Matrix Program Control statements 9 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.fld3 In this case. It will be easier and faster.fld2. the record number is the index for the 1st dimension and the fld1 value will go into index 1 of the 2nd dimension. name3[11][12][13][3]=16. If the field values in record 3 are: fld1=11 fld2=12 fld3=13 then: name3[3][1]=11. name3[11][12][13][4]=3 Another example: FILEI DBI[x]=xxx. name3[3][2]=12. name3[11][12][13][2]=15. brackets. unless the field is enclosed in an escape-character sequence and DELIMITER[2] does not contain a space as its last character.” and “USA. even if it encounters a field-separator character. CA". where t is used to designate a tab: DELIMITER[1]=" . The default values are “ . the character that marks the start of an escape sequence along with the character that marks the end of an escape sequence.t" DELIMITER[2] specifies escape-character sequences that permit field-separator characters in free-format records. Cube Voyager automatically removes leading spaces from all fields. Specify characters in pairs.9 Matrix Program Control statements FILEI keywords (continued) Keyword DBI Subkeyword DELIMITER |S2| Description Use to specify two different controls for free-format records. CA. Example Suppose you set a comma as field-separator and double quotes as an escape sequence: DELIMITER='.” “Oakland. USA Cube Voyager reads three fields: “ John Smith. double quotes. Cube Voyager treats all subsequent data as part of the same record until it encounters the ending escape-sequence character. and braces as escape character sequences: DELIMITER[2]="""''()[]{}" NOTE: You must enclose the entire value in double quotes or single quotes.' '""' When reading the following input data: John Smith. The default value specifies single quotes. The starting escape-sequence character in DELIMITER[2] cannot be a field-separator character in DELIMITER[1]. parenthesis.” 494 Cube Voyager Reference Guide . Cube Voyager will remove the leading and trailing character from any string it reads. DELIMITER[1] specifies the field-separator characters. If you include a single space as the last character in DELIMITER[2]. 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. Upon encountering the starting escape-sequence character. "Oakland.t”. that sets the format as freeform. DBI JOINTODBI |I| Specifies the number of the input DBI file to join this DBI file to.NFIELD[3] comes from field number 13.NFIELD[1] comes from field number 6.CFIELD[#] or as DI.NFIELD[2] is in columns 6-10.#. and DBI. If this keyword is present.13 Specifies that the data is in free format and defines DBI. Cube Voyager Reference Guide 495 . FIELDS can specify multiple successive fields with a single specification (providing all fields are the same type. FIELDS=6(C7) Specifies the same. If a data field is defined by a single number (field number on the records).#. only the fields specified will be extracted.#. You must also specify the JOINTOFIELDS subkeyword. The values specify the columns or fields of the DBI file records where a desired field is located. that sets the format as fixed.#.21-25 Specifies that the data is fixed format and DBI.NFIELD[2] comes from field number 9. FIELDS=6. All data fields must be defined in the same format.NFIELD[#]. DBI.NFIELD[3] is in 21-25. Used only when the DBI records are fixed or free format. The field names referenced by the SORT keyword define the join key.#.6-10.#. and DBI.#.NFIELD[1] is in columns 1-5. but those fields would all be character values.Matrix Program Control statements 9 FILEI keywords (continued) Keyword DBI Subkeyword FIELDS |IPV| Description An optional method for defining data fields in the input file. DBI. then the SORT keyword must also be specified.#. For example: FIELDS=6(7) Specifies that DBI.9.#. N or C).NFIELD[7] will be obtained from fields 6 through 13 of the data records.FIELD# in script statements. DBI. If JOINTODBI is specified for a DBI file. Optionally. You can reference these field values as DBI.NFIELD[1]…DBI. For example: FIELDS=1-5.#. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi).#. DBF". deleted records (flagged with a “*”) are not counted as records. 496 Cube Voyager Reference Guide . which uniquely identify each person-trip record.PERSNO In this example. script statements that process a trip record are linked to the corresponding person-level data file. This keyword can have fewer referenced field names than the SORT keyword but cannot have more than the number of sort keys. If the DBI is not a DBF file.PERSNO TRIPNO FILEI DBI[2] = "PERSON. along with other household and person-level demographic data fields. Note that the key field name on which the join is performed does not need to match in the two files. DBI file 2 is a person-level survey record file. PERNO. This file contains the fields HHID and PERSID. SORT=HHNO. enabling trip-based computations to directly reference the household and person-level characteristics in the joined file. along with other trip-related data fields.DBF". If the file is a DBF file. This file contains the fields HHNO. For example: FILEI DBI[1] = "TRIPRECORDS.PERSID JOINTODBI=1 JOINTOFIELDS=HHNO. DBI MAXRECS |I| Limits the number of records read from the DBI file. which uniquely identify the person record. the program treats both zero length and blank records as legitimate records. SORT=HHID. and TRIPNO.9 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. DBI file 1 contains the person-level trip records from a travel survey. With the files joined. You must index LOOKUPI. If the records are in free format. the variable type is numeric. it must be designated as lo-hi. or a pair of integers (separated by a dash). that field is to be sorted in descending order. The value must be either a single integer. the value will be lo-hi. There may be up to nine sort keys. Name of file containing records for a lookup function implemented with the LOOKUP control statement. the variable type is character.. If a sort name is preceded by a minus (-) sign. LOOKUPI |FKV999| Cube Voyager Reference Guide 497 . Equivalent to the FILE keyword of the LOOKUP control statement. You can reference the variable in other parts of the script as DI. If the input records in fixed format. where lo=hi=the column number of the data field.Matrix Program Control statements 9 FILEI keywords (continued) Keyword DBI Subkeyword NAME |IP| Description Name of a variable to extract from a text format record. If the name has nothing—or “(N)”— appended. DBI SORT |S9| Designates that the input records are to be processed in a specified sorted order. If the name has “(C)” appended to it.#. the values must be single integers indicating the field number in the data record.name. or there is a preceding plus (+) sign. If there is no leading sign. The value contains the location of that variable on the data record. The values are the names of the variables that the sort is based upon. if the field is a single column. that field is to be sorted in ascending order. For example: FILEI MATI[x]=xxx. MI=4. MI=6-8. If multiple tables are selected. The list of input table numbers do not need to be in order (e. TP+. If it is not detected as one of those. If it is not a binary matrix file. Selected tables can be loaded into arrays. matrix file table 6 to array name1[2][i][j] etc. For example if FILEI MATI[1]=’emme2ban’. MI=. See “Example of FILEI statements” on page 515 for an example of MATI usage when accessing an EMME/2 data bank file. then they will be loaded into a 3 dimension array with the first index being the table number. The same table number can be specified multiple times to load the same table into different part of the array. If the file specifies a Cube Voyager. then the Matrix program will recognize the file as an EMME/2 data bank file. or Tranplan binary matrix file. MATI AUTOMDARRAY |S| FILEI MATI[]=. it is assumed to be an ASCII text file. You can reference input matrices from an EMME/2 data bank file in the script by matrix number. the program will automatically detect it.9 Matrix Program Control statements FILEI keywords (continued) Keyword MATI Subkeyword |KFV20| Description Specifies the input files with matrix data.6-8 will load the matrix file table 4 to array name1[1][i][j].1. it will be loaded into a 2 dimension array.g.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. I=. RESTRICTION= This will load matrix data into multi-dimensional arrays before any script processing. AutoMDArray=name1. If the input file name is specified as emme2ban with no file extension. PATTERN and FIELDS must be associated with the MATI. If only one table is selected. AutoMDArray=. MINUTP.4) but a range pair must be specified in low-high order. J=. 498 Cube Voyager Reference Guide . or a standard data base (DBF) file. then MW[1]=mi. For example: FILEI MATI=xxx.g. J=31-35. I=6-8. Additional restrictions can be applied when loading the matrix data. The same I/J number can be specified multiple times to load the same I/J into different part of the array. name2[10][10] = matrix[25][45] etc. MI=4.2125. The list of input I/J numbers do not need to be in order (e. AutoMDArray=name2. 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. and DIAGONAL filter based on the original IJ number from the input matrix table Cube Voyager Reference Guide 499 . name2[6][7] = matrix[21][42]. I=11-15.4) but a range pair must be specified in low-high order. UPPER.Matrix Program Control statements 9 FILEI keywords (continued) Keyword MATI Subkeyword AUTOMDARRAY (continued) |S| Description Selected I's and J's can be loaded into a smaller array.41-45 will load parts of the matrix file table 4 to a 10x10 array with name2[1][1] = matrix[11][31]. (Note: When reading with fixed format. the field values define the positions on the record where a data field is located. For example. Any one (and only one) format may be used to specify the fields. With variable format. the first field definition establishes the format.11-20-8. and eight data fields (each 10 characters wide) are in columns 11-20. For a PATTERN=IJM:V. 6-8. and the matrix number always starts at one for each record. A leading # is recommended for variable format. leading non-digits are ignored. if it begins with a letter (not a digit). 10. Example: FIELDS=1-3. The program extracts the number from the right end of the definition. A range of names (name-name) may be used to specify a string of consecutive fields.9 Matrix Program Control statements FILEI keywords (continued) Keyword MATI Subkeyword FIELDS |S| Description Specifies the data fields to be read from an input record. FIELDS=1-10-204 is OK. If the MATI file is a database file. or as a group of three (beg-endnumflds) to indicate a series of equal length fields. for a record longer than 2047 bytes. the values in FIELDS must be names found in the dbf dictionary. pairs of numbers (beg-end). J is in columns 6-8. 500 Cube Voyager Reference Guide .10. This limit is not applicable to variable format files. 21-30. this example would indicate that I is in columns 1-3. the format will be variable. The specification of FIELDS with implied matrix number will be shown in the example in the next section.2. its format may be either fixed or variable. For example: #4-6. while FIELDS=1-10-205 will get a warning because the program is unable to read in the last field. hence. With fixed format. the format will be fixed. it indicates that the starting matrix number is not included in the input data. If the first field value is a number.) When the field value of M is set to zero. If the file is not a DBF.etc. every field value must end with a number (only the first field value is required to have a leading non-digit).13. The field values may be entered as single values (single column). although any character string is acceptable. the highest begin column number may not exceed 2047. Ranges of variable format fields may be specified. M is in column 10. implied. . • • Valid combinations are: IJ:V — I J values for J. matrix 1 is assumed. The pattern has two portions separated by a colon: a base portion and a repeating portion. the last character in the base portion indicates which variable is incremented for each repeating set.Matrix Program Control statements 9 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. and J I:VJM — I sets of V..J+1..M+2. and M I:VMJ — I sets of V.J+2.M+1. IJM:V — I J M values for M. J. and M I:JMV — I sets of J. and V I:MJV — I sets of M.. The highest M that the program recognizes is 255. There may be one M to specify the starting matrix number. I must be the first letter in the base portion. and V I:MVJ — I sets of M. V. IMJ:V — I M J values for J.J+2. and V. M. V. J... and J Cube Voyager Reference Guide 501 . In the pattern definition: • There must be a single I. J. 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. and V must be in the repeating portion. If there is no M. M.J+1. If there are multiple characters in the base portion. See “More on MATI PATTERN” on page 511. If the FIELDS list is exhausted before the end of the PATTERN. a warning message is issued. When reading a data record.9 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. The above examples assumed that the FIELDS values implied variable format and that there was an appropriate number of FIELDS values specified. This continues until the FIELDS list is exhausted. When the PATTERN is exhausted. Note that the data values need not be read in sequential order from the input records. 502 Cube Voyager Reference Guide . the reading continues from the beginning of the repeating portion of the PATTERN. It is necessary to have FIELDS specified in conjunction with PATTERN. If the values specified in FIELDS do not align correctly with the PATTERN. the program aligns the next FIELDS value with the next letter in the PATTERN. reading is terminated without storing the last repeat value. The FIELDS values can be used to specify any order. and extracts the data. use the first variable to indicate the file 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). If there are any RECO statements. You can reference these fields directly in the script as RI. To define a variable as a character variable. the program recognizes field names in the DBF or MDB header. For text files. all RECI variables (RI. For example. you must designate the hi column as the same as the lo column. separated by commas or spaces) or fixed format.name) in the FILEI RECI statement using the appropriate subkeywords.name) on the input file are automatically copied into equivalent RO. For DBF or MDB files. TITLE(C)=#1 would define the variable named TITLE as a character variable. either delimited (free format. Cube Voyager Reference Guide 503 .prefix can be written to the RECO file. the program consider data read from the first data field on the input file to be character data. Only variables with the RO.fieldname.variables. The RI. NOTE: Cube Voyager may not properly process database files larger than 2 GB. or an ASCII record file with either delimited or fixed format records. append “(C)” to the name. You can also specify the delimiters for delimited records with the DELIMITER keyword.Matrix Program Control statements 9 FILEI keywords (continued) Keyword RECI Subkeyword |KF| Description Name of a DBF file. For single-column characters. For text files (files other than DBF or MDB files).variable attributes are ported to the corresponding RO. do not explicitly define the variables in the FILEI RECI statement. an element in a multidatabase file.name variables immediately when a record is read. you must define all variables that the program will recognize (RI. Define the first field as a single number to indicate delimited format. To test on end of file the IF (I=0) condition can be used. see DELIMITER description under DBI keyword on page 494. it is processed against the script statement stack. MATIs are not read unless a MATVAL function is used. See “More on RECI” on page 513 for some examples. Thus. Usage of DELIMITER is the same under both keywords. If a RECI statement is present. For details.CFIELD — String value for the field (Null if RECI. The arrays are: RECI.NUMFIELDS — Number of defined data fields RECI. the program enters a record processing loop instead of the traditional I-loop.NUMFIELDS].TYPE=’N’) The NFIELD and CFIELD values are updated to the values from each record as the record is read. Each array is dimensioned as [RECI.TYPE — Type of field (either ‘N’ for numeric or ‘C’ for character RECI.NFIELD — Numeric value for the field (0 if RECI. 504 Cube Voyager Reference Guide .9 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.RECNO — Number of the current record being processed The program also makes four different arrays available to the user.NAME — Name of the field RECI.NUMRECORDS — Number of data records on the RECI file RECI. As each RECI record is read. RECI DELIMITER |S2| Use to specify two different controls for free-format records. The PRINT statement allows the user to write out any portion of the input record plus any computed variables. and FILEO MATO keywords should not be used. The record processing loop sets I=1 and reads records until the end of file is found where it sets I=0.TYPE=’C’) RECI. Matrix Program Control statements 9 FILEI keywords (continued) Keyword RECI Subkeyword FIELDS |IPV| Description Only available in v4. that sets the format as freeform. 13 respectively. but those fields would all be character values. Places a limit on the number of records to be read in from the RECI file. For example: FIELDS=1-5. FIELDS=6(7) specifies that RECI.6-10. RECI. Default value is no limit. Maximum number of errors allowed in reading the RECI records before a fatal error message is returned.FIELD# in stack statements.13 specifies that the data is in free format and will define RECI.NFIELD[1]…RECI.NFIELD[1] is in columns 15. Default value is no limit.0 and beyond. that sets the format as fixed. FIELDS=6(C7) would be the same.9. Optionally. Default value is F.NFIELD[1] RECI. This is to prevent excessive listing of error messages to the run print file.NFIELD[2] RECI. and RECI.NFIELD[3] is in 21-25. If LISTERRS=T then MAXERRS automatically defaults to MAXERRS=1000. only the fields specified will be extracted.21-25 specifies that the data is fixed format and RECI. FIELDS can specify multiple successive fields with a single specification (providing all are the same TYPE. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi). RECI. 9.NFIELD[7] will be obtained from fields 6 through 13 of the data records. If this keyword is present. 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. All data fields must be defined in the same format. 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. The values specify the columns or fields of the RECI file where a field is located. RECI LISTERRS |?| RECI MAXERRS |I| RECI MAXRECS |I| Cube Voyager Reference Guide 505 .NFIELD[3] coming from data fields number 6. If a data field is defined by a single number (field number on the records).NFIELD[#]. Flag that indicates if errors should be listed to the run print file. N or C).CFIELD[#] or as RI. These fields can either be reference as RECI.NFIELD[2] is in columns 6-10. FIELDS=6. The default setting will not return a fatal error message no matter how many errors are detected. name. If the user is certain that all the records are the same length. If the name has “(C)” appended to it. the number of records.9 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 values must be single integers indicating the field number on the data record. the variable will be considered as character. 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. Aside from the zone number. the variable will be considered numeric. Designates that the input records are to be processed in a specified sorted order. Specifies the input files containing zonal data. appended. the maximum length of each field. where lo=hi=the column number of the data field. and there is no SORT specified. This control should not generally be used and was added primarily for internal Citilabs use. the use of this keyword can reduce front end time. If there is no leading sign. etc. Every zonal record must include a field that identifies the zone to which the record data applies. RECI NAME |IP| RECI SORT |S5| ZDATI |KFV10| 506 Cube Voyager Reference Guide . If a sort name is preceded by a minus (-) sign. This value will be used only if the format is fixed. There can be up to 10 zonal data files. the value will be lo-hi. or a pair of integers (separated by a dash). If the records are read in free format. if specified. If the input records are read in fixed format. It can be referenced in all other parts of the script as RI. The value must be >= 10. or there is a preceding plus (+) sign. There may be up to five sort keys. Zonal data is data which is specific for each zone. that field is to be sorted in ascending order. If it has nothing. or “(N)”. and not really productive for very large files such as the census files. any fields from the record can be extracted and used by the program. The values are the names of the variables that the sort is based upon. it must be designated as lo-hi. if the field is a single column. I maybe save time if processing very large data files. The program normally scans the entire file to obtain the longest record. to designate where the variable will be obtained from each record. The value must be either a single integer. that field is to be sorted in descending order. That could be quite time consuming. MDB. MDB. The program will try to detect what type of file it is. Cube Voyager Reference Guide 507 . the program will try to determine the zone number field based on file type. the program will go through all field names to find a match with one of the following possible zone field names. MDB. the fields to be extracted must be named and identified on the ZDATI statement by either relative field number. When the program detects a Cube Voyager network file. referenced as MS#. it is not necessary to name the fields to be extracted. For DBF or MDB files. referred to as either an origin-based matrix (MO#) or a destination-based matrix (MD#) where # is the reference matrix number. See “Example of FILEI statements” on page 515 for an example of ZDATI usage when accessing an EMME/2 data bank file.) For Cube Voyager network files. I. EMME/2 data bank.#. EMME/2 data bank files store zonal data as a vector matrix. or scalar matrix. The field that contains zone number must be specified using 'Z=' keyword. the specified field will be used to extract zone number. where name is the EMME/2 bank matrix name for the origin. or a Cube Voyager network. The program will not recognize any other file name as an EMME/2 data bank file. it will assume ASCII. (Note: For files with more than one possible zone field from the list above.Matrix Program Control statements 9 FILEI keywords (continued) Keyword ZDATI (continued) Subkeyword Description The file format can be: ASCII. node numbers (N) will be used as zone numbers by default.name convention. it opens the node database portion of the file as zonal data. or a Cube Voyager network. in the script. To reference zonal data from an input Emme2 data bank file in the script. ZONA. If the file is an EMME/2 data bank file. If it cannot identify the file as a DBF. or a Cube Voyager binary network. by existing field names from the input file. DBF. then the file name must be emme2ban with no file extension. The first matched name will be used to extract zone number. If the file is a DBF. The specification of zone number field is optional for those two file formats. TAZ}. it is recommended to specify zone number field explicitly to ensure the correct field is used. Bank files store scalar data (or constants) as a scalar matrix. destination. All fields will be extracted and can be referenced. If the file is of ASCII format. J. If 'Z=' is present. Otherwise. or by exact column positions on the records. use the standard zi. ZONE. in the given order: {Z. EMME/2 data bank. Count of the records that contain the variable. Maximum value of all the records. 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 []. or the field is blank on a record. any variables that are not in any list will be set to LAST. Value with which to initialize the array for the named variable. if there are no records for a zone. 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. ZI fields that have string values are valid but only up to 7 characters in length. where the value from the file records is not 0. Average of all records. The values for the variables will be obtained only from file records that contain the variable.9 Matrix Program Control statements FILEI keywords (continued) Keyword ZDATI (continued) Subkeyword Description In general. this value will be used. string valued arrays are not supported at this time. Minimum value from all the records. A variable may appear in only one keyword list. ZDATI is the one exception to this rule with some limitations. ZDATI ZDATI ZDATI ZDATI 508 Cube Voyager Reference Guide . Then. AVE AVEX0 CNT DEFAULT |SV| |SV| |SV| |R| Average of all records. SELECT[2] specifies the input record field whose value is to be compared with the value of SELECT[1]. If the file is a dbf. or the columns (fixed format) where the variable is located on the record. If SELECT[2] is a number. SELECT[3] is ignored if SELECT[2] is a free field definition. Used to cause selective reading of zonal data records from ASCII files. because Z specified triggered delimited format. If the first value is a number. AREA=3. it is assumed that the value indicates a relative field number on the data record. the first name value (including Z) establishes the format. The program will compare a field from each record with the string specified in SELECT[1]. and SELECT[3] can be optionally specified to designate the ending column.6-8 select only if columns 6-8=abc SELECT=1. These are all be valid. All names must be specified with the same format. fixed format is assumed. SALES=xxx4. For text files. the record is bypassed. It doesn’t matter what string precedes the number (the value need not be prefixed with a string). If delimited format is specified. the value assigned to name is either a field number (delimited format). SELECT=abc. Only the variables named will be extracted. it designates the beginning column of the comparison field on the input record. Z=1-5. Example: Z=#1.Matrix Program Control statements 9 FILEI keywords (continued) Keyword ZDATI Subkeyword name |S| Description Identifies a data variables that is to be extracted from each record. each name value MUST end in a number. That field is the comparison string. name=name would be the standard.POP=#2 would be invalid because Z specifies fixed format. This selection is not used if SELECT is not specified. but it is not necessary to keep the same names. ZDATI SELECT |S3| Cube Voyager Reference Guide 509 .POP=#2. if`SELECT[2] is not numeric. otherwise. Alternatively.#2 select only if a 1 in field no. In most DBF cases. the value for each name is the name from the DBF dictionary. and if the comparison fails. delimited format is assumed. SELECT[2] and [3] must both be numeric and should be separated by a dash. 2 ZDATI SUM |SV| Sum of all the records. but ends with a number (first example). You must check the return code. specified relative to the current record. The functions are: • DBIReadNext(#. J. A return value of 0 indicates a successful operation.R) where R indicates the record to read.).. R<1. I. though DBIReadNext(#) is also allowed. and a positive R means after the current record. DBIReadRecord(#.#. For delimited files.1). A negative R means prior to the current record. A return code of 1 indicates any of the following errors: bad #. TAZ} is NOT in the DBF file. DBI# must always be the first argument.NUMRECORDS. With DBFs and fixed format records. but with delimited format.. a dummy variable with a high field number can be specified to generate a larger record length.NUMRECORDS. R must be 1 – DBI. Use these functions in a COMP statement with the form: N=DBIfunc(DBI#.R) where R indicates the record to read. or the return code will be 1. ZONE. Z is required for ASCII files and also if a DBF file is being used and one of the special field names : {Z. the record length is estimated by multiplying the highest field number by 10. More on DBI DBI files are not automatically processed. the required length is known. All the functions return a value to indicate the success of the operation.9 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. If the estimated length is inadequate. Several functions are available to read the records. You must write scripts to read the records. It has to know how long a buffer is required. 'Z=' is a special case for 'name='.#. Caveat: The program establishes a buffer to read file records into. ZONA. • 510 Cube Voyager Reference Guide . or R>DBI.. Write sequential reads as DBIReadNext(#. the required length can not be estimated exactly. any other value indicates the read was not 100% successful.. 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. NOTE: You can create and populate arrays with just a FILEI DBI statement. the PATTERN IJM:V.RECNO is set to the record that is above the R selections.Matrix Program Control statements 9 • DBISeek(#. This function searches for the record that matches all the specified R values. 3… In this case. you do not need DBIRead functions. with the FIELD value of M set to Cube Voyager Reference Guide 511 .RECNO.) where R is a value to search for in the field specified as SORT[1]. then multiple values to represent matrix 1.6[18-20] 100.24 IMJ:V 1 6 18 100 101 105 I=1 MI.22.RECNO is set to the last record. See “Example 5” on page 559 and “Example 6” on page 560 for examples of DBI processing.23.1. In order to use this function.field values are extracted from the record indicated by DBI.1. 2 — A match was not found. the DI.6[12] 90 The above PATTERNS do not provide for the situation where the record contains I.1[12] 8 I=5 MI. but not more. R. and DBI.5[12] 2 I=5 MI. and the record pointer points to that record. There may be fewer R values than there are SORT fields..1.1.1[15-18] 21.#. The return values are: 0 — A match was found.#. 3 — The R values are greater than the last record and DBI.105 I:JMV 5 12 1 8 14 2 90 I=5 MI.1.1.4[12] 14 I=5 MI.2[14] 90 IJM:V 5 12 3 8 14 2 90 I=5 MI.. there must be at least as many SORT values as there are R arguments.1. 2. In all cases.#.1.101. J. 1 — An error in setup occurred.3[12] 8 I=5 MI.. 0.V2..V3.3-4. MI. FIELDS=1-2.1213 54.dbf. The matrix number is implied and always starts with 1 on each record.txt. 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.1..V1.0612 31. can be used to describe the input data.V2. FIELDS=I.8514 12.3815 512 Cube Voyager Reference Guide .1.2813 6.1. DBF format . pattern=IJM:V.6512 54. PATTERN=IJM:V.0.5413 269.txt.9 Matrix Program Control statements zero.5-7-4 .V4 (results) I=1.V4. then multiple values to represent J values 1. MI.1612 13.2=22.J. fixed format or MATI[1]=input.5015 75. with the FIELDS value of J set to zero.0.V3.2513 22.2914 14. variable format or MATI[1]=input. The input dbf in this example would have the named .3912 167. 3. for a single matrix (implied matrix number M=1). J=15.4=24 The above PATTERNs also do not provide for the situation where the record contains I.1215 10. MI.V1. can be used to describe the input data. 2.2. FIELDS=#1. MI.6815 31. the PATTERN IJ:V.8414 35.3-6 .1=21. The J value is implied and always starts with 1 on each record.5314 4.J. PATTERN=IJM:V. 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.3=23. fields I.1. In this case. SORT=key2.txt.2-5 More on RECI Example RECI statements: FILEI RECI=myfile. nvar1=1.txt. '//() ' SORT=-nvar1.0. cvar3(c)=3.dbf. SORT=nvar2.TYPE[K] = 'N' && substr(RECI. cvar2(C)=2.mat PAR ZONES=4 MW[1]=mi.NUMRECORDS PRINT LIST=RECI. nvar1=1.NAME[k].DAT FILEO MATO=temp1. nvar2=5-8. The script example below will build a binary matrix using the implied J values. nvar1=1-3.1. SORT=key2. cvar3 FILEI RECI=myfree.+cvar3 Example of usage: to sum all the housing units in a record (even if the exact names are not known.Matrix Program Control statements 9 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. cvar3(C)=3.VAR1AVG ENDIF Cube Voyager Reference Guide 513 .txt.1 ENDRUN PATTERN=IJ:V MO=1 FIELDS=#1.NUMFIELDS If (RECI.txt. nvar1=1.RECI. +key6 FILEI RECI=myfile.3. -key1.VAR1TOTAL. -key1. but we do know that all units fields are named xxUNITS): TotUnits=0 Loop k=1.NUMRECORDS. DELIMITER[2]='""'' ' FILEI RECI=myfree.. cvar3(c)=1010. RUN PGM=MATRIX FILEI MATI=temp1. +key6 FILEI RECI=myfile. cvar2(C)=2.5) = 'UNITS') TotUnits = TotUnits + RECI.t' . cvar3(C)=3.mdb\mytable.NFIELD[K] EndLoop Example: In a record processing run of matrix VAR1TOTAL=VAR1TOTAL+VAR1 IF (I=0) VAR1AVG=VAR1TOTAL/RECI. DELIMITER[2]='//' FILEI RECI=myfree. cvar2(C)=2. DELIMITER=' . ROAD_TYPE..'.NUMRECORDS file=tmp2..A.\nnfield[6-9] ='.reci.prn write reco=1 print printo=1 form=5lr.'.cfield[5].lng print printo=1 form=5lr.dbf PARAMETERS MAXSTRING=100 if (RI.' lng='.'. reci.'.'.'.'.reci.reci.'.'.'\ncfield[1-5] ='.PICTUREFIL file=tmp1.ri. reci.reci.'.txt.'.IMPORTANCE. ri.'.reci.'.reci. 514 Cube Voyager Reference Guide .'.allfields FILEO PRINTO[1]=junkprn.reci.reci.cfield[2].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 .'.B.fields.A>25 & RI.cfield[3].ROAD_NAME.'.ri.cfield[1].'.nfield[7].get 1st 5 data fields as numeric fields and also as character fields FILEI RECI = junk.'. reci.'.dat endif ENDRUN Example: copy file = junk. ri.'.reci.'.. the total of VAR1 and the average of VAR1 Example: RUN PGM=MATRIX FILEI RECI=network_link.CLASS.9 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.dbf FIELDS=reci. RECI.B>25) print.' NumFields='.Fields=1(c5).nfield[6].cfield[4]..'.'..'. list=ri.nfield[8]..list=reci.'. ri..1(n5) FILEO RECO[1]=junkout. ' highest field='.recno.SPEED.'.ri..'.csv endif if (I=0) print list='Number of link records='.'.list='\nRecno='.'.numfields.ri. 44..Z=1-5..'..55.field10.'..'. Z=#1.. ri.'.'.MAT..field7.dd.txt..dat.mat .'..field6..field6.10='.'.33....dat ...55.'.22..DEST. Example of FILEI statements These statements show various examples of FILEI usage: FILEI MATI=test11...44.var.56.22.txt. ri. ri.. ri.\nri.56.' 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..'..field3.0.0. 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 .txt .. nfield[6-9] =11.'.5 =aa..5 =11..DU1=#2. LAST=DUPLEX ZDATI[4]=pop.field4.cc.reci.field1.'.'.0. ri.TRIPS ZDATI[1]=housing..'.55.'.MULTI_FAMILY=4..field1.10=0.dd. nfield[6-9] =0.field6.. Recno=2 NumFields=10 highest field=5 lng=23 aa bb cc dd 56 78 90 12 cfield[1-5] =aa..44...Matrix Program Control statements 9 reci. CONDO=5.\nri..44.nfield[10].ri.field9...poptotal=6-15.ri.cc.'. popyouth=36-45.field6.10=11.'.56.txt.DUPLEX=3..11-10-20 MATI[6]=external..6-8.'.nfield[9]. PATTERN=IJ:V.. ri.test12.popsr=56-65 These statements show an example of simple record processing: copy file=reci_in.0.bb.56... MINUTP binary matrix files MATI[4]=tppltrips. ri...dbf..field8.'.bb. TPP or MINUT matrix file MATI[5]=external.33.33.'. ri.popfemale=26-35....field1..22. FIELDS=1-4..field5..RETIREMENT=6 SELECT=abc-1-3 FIRST=DU1...ri.5 ='..field1.popmale=16-25... PATTERN=IJM:V FIELDS=#1-30 MATI[7]=external..33...0..ri.ri..ri...pop19-65=46-55.0.22. PATTERN=I:JMV FIELDS=ORG.'.'.field2.55. 0) Dist = matval(1.1). dest=2 MATI[1] = mymat.1.1. dist(8.9 Matrix Program Control statements reci=reci_in.1.ORG. dist=0 Endif print file=outfile.mat" mo=1-8 DEC=8*9 . contains time and distance matrices in 1 and 2 If (RI. I is the end-of-file indicator print list=i(3. s3.1.RI.1.11. time(6. 1.104 MW[2]=MI.txt.107 MW[5]=MI. file=out_reci. s2.111 ENDRUN 516 Cube Voyager Reference Guide . 0.0) Else Time=0.110 MW[8]=MI.txt.Z endrun These statements show an example of getting I-J values from a delimited file: RUN PGM=MATRIX RECI = myfile.ORG > 0 && RI. ' '.1. get matrices mf104 to mf111 from emme2ban .2.0 A 1 2 3 4 5 6 7 8 9 10.1)=='A') s3='B' . switch to record processing mode . list=reci. reci(10).1.1.RI.12) s3='Z' if (substr(reci.RI.0 B 1 2 3 4 5 6 7 8 9 10. org=1.B . '.1.DEST. each data record is stored in a string variable ”reci” s2=substr(reci.ORG.106 MW[4]=MI.2LR). FIELDS=1-3 . 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.105 MW[3]=MI. will result in .108 MW[6]=MI.RI. and put into work matrices 1 to 8 MW[1]=MI. print=y .'.DEST>0) Time = matval(1.109 MW[7]=MI.DEST.1.2LR) . Cube Voyager Reference Guide 517 .md23=zi.3).md82(6) report zdat=t zones=900 ro.3). Matrix Outputs data files.3). Cube Voyager writes matrix type output files at the end of each I zone.md82 write reco=1 ENDRUN FILEO Programs: Distribution.1.md22 ro.1.md23(6).mo20 ro.md22=zi.1.mo22=zi.mo21=zi.md25=zi.dbf" FIELDS=ms10(5.1.md80(6).mo21(6.mo20(6.1. mo22(6.1.3).3).mo23=zi. Fratar.md22(6.mo23 ro.md81=zi. 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.3).md81 ro.ms10=zi.md25 ro.md81=zi.md80 ro.mo22 ro.1.mo23(6.mo20=zi.1.md80=zi.ms10 ro.2).md25(6.3).1.1.Matrix Program Control statements 9 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. md81(6).mo21 ro.1.mo25(6.mo25=zi.1.mo25 ro.md23 ro. The program can write output matrices in various formats. Indices need not be monotonic or sequential. The program will overwrite an EMME/2 data bank file in the format specified by FORMAT if the name is not emme2ban. 518 Cube Voyager Reference Guide . the program will not create the data bank file. which you can use with other software. If you do not specify an index. May have an index [x] appended. If it does not exist. the program assumes the index is 1. The data bank file must exist already. EMME/2 data bank files must be named emme2ban. MATO may reference an existing EMME/2 data bank file in order to store matrix data into the existing data bank. 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.9 Matrix Program Control statements PRINT statements write formatted print files to the PRINTO file. Cube Voyager Reference Guide 519 . for a cell computed as 10/3. and requires two bytes to store.147. Certain matrices might require more precision. NOTE: Cube Voyager stores fixed-point format as a decimal-coded integer.33.. S — Writes output matrix cells in single-precision floating-point format (4 bytes). Cube Voyager processes all matrices in double-precision floating-point format to accommodate a wider range of values and to maintain accuracy and precision. and requires four bytes to store. This is the traditional format for transportation planning matrices.Matrix Program Control statements 9 FILEO keywords (continued) Keyword MATO Subkeyword DEC |SV*| Description Specifies numeric format of values in the output matrix. which translates to 1. the result is 3. the default value is 2.258. to sixteen digits. preserving the indicated number of digits following the decimal. Additional digits may change from their original value when a program reads them. Valid entries vary by file format: • Cube Voyager files Valid entries include: 0 through 9 — Writes output matrix cells in fixedpoint format. If stored as fixed-point with DEC=2. If the cell value exceeds the maximum integer value (2. However. In most cases. If stored as single precision with DEC=S. Specify a separate DEC for each MO. This format provides seven to eight significant digits. writing double-precision numbers to the matrix files might produce very large files. the result is accurate to about seven digits. If stored as fixed-point with DEC=0. then Cube Voyager reduces the number of digits stored after the decimal. the result requires eight bytes to store. For example.337. However.258. If you do not specify DEC. the result is 3.756.756. If stored as double precision with DEC=D. a few decimal places for each cell value are adequate. For example.483. with DEC=5..647). and requires one byte to store. the result is 3.756. this result might not be precise enough for the subsequent uses.33333333.337.258. Cube Voyager stores 1. D — Writes output matrix cells in double-precision floating-point format (8 bytes). This format provides 15 to 16 significant digits.33715 as the integer 1. If you specify DELIMITER. However. the program treats as DEC=0. cost. If a number’s integer value with implied decimal exceeds the maximum integer value (2.483. the program writes variable-length values and truncates trailing zeros. and so on). Storing numbers larger than the maximum integer value (2. 520 Cube Voyager Reference Guide . • TRIPS files Set DEC to the number of digits after the decimal point (0 to 9).5) . bucket rounding Optionally. LOS rounding COMP MW[2]=MW[2]*100. otherwise the program writes fixed field lengths. distance. The program ignores the DEC setting and automatically writes 4-byte values.483.147. Total=ROWFIX(2) . PATTERN=IJM:V ). • Text files Set DEC to the number of decimal places to format in text records. COMP MW[1]=INT(MW[1]*100+. usually integer numbers. NOTE: Normally. the program substitutes the maximum integer value for that number. the program uses the default value of 2. • DBF files Set DEC as for Cub Voyager files.647).9 Matrix Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword DEC (continued) Description • MINUTP or Tranplan files Do not set DEC. the program uses DEC[#] appropriately. the program uses the DEC[1] value for all the matrix data fields unless “M” immediately precedes the colon in PATTERN (for example.147.647) will result in erroneous values. The program stores numbers as integers with implied decimal. set DEC=S to write a single-precision matrix. If you do not code DEC. However. You must set the included work matrices to the desired external format before the program writes the matrices. and “bucket round” matrices that represent trips to ensure row totals. you round matrices that represent levelof-service (time. based on the values of FIELDS. you cannot use such a matrix as input to Cube Voyager. If you set DEC to S or D. If you set PATTERN such that M varies in a record’s matrix data values. the program writes data values in variable length and separates values with this character. Cube Voyager Reference Guide 521 . Usually. will result in an overflow condition. When you code this subkeyword. Character that separates data values. Cube Voyager can never store matrix values smaller than 10-300 or larger than 10300. NOTE: Regardless of file format and value format. If you do not specify DELIMITER. In addition. calculations that result in values outside the doubleprecision number range. based on the values of FIELDS. The program stores values in singleprecision floating-point format in the data bank file. you delimit data with a comma or space. the program writes fixed field lengths.Matrix Program Control statements 9 FILEO keywords (continued) Keyword MATO Subkeyword DEC (continued) Description • EMME/2 data bank files Do not set DEC. ' '. Cube Voyager will cap values outside this range. To use a comma or space. enclose with quotes. MATO DELIMITER |S| For text files only (FORMAT=TXT ). After exhausting the list of FIELDS values.4. With PATTERN set.9 Matrix Program Control statements FILEO keywords (continued) Keyword MATO Subkeyword FIELDS |IV4| Description Field width for data values when DELIMITER is not specified. I will always be in columns 1-4 J will be in 5-8.15-20. unless you set PATTERN. Ignored if MATO is set to emme2ban.0. the default value is TXT.6. and the “repeating” portion follows the colon). 522 Cube Voyager Reference Guide .. The number of values specified with FIELDS must match the number of letters in PATTERN (the “base” portion precedes the colon.17-24. 39-40 ... M will be in 15-16... 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.25-32 .. 17-20. V will be in 9-14. 29-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. the program reverts to the FIELDS value that corresponds to the repeating portion of PATTERN.6 • • • • • • • • • • • MATO FORMAT |S| • • • • • • I will always be in 1-4 J will always be in 5-8 V will be in 9-14. If the FIELDS value that corresponds to a base portion of PATTERN is set to 0.2 PATTERN=IJM:V FIELDS=4..8 Type of file written: Default value is TPP... In that case. 21-26.21-26 . the program updates an EMME/2 data bank file. 27-29.. The first FIELDS value always sets the length for I. Examples: PATTERN=IJ:V FIELDS=4. 33-38 .4. the program omits the corresponding data.4. 6. for a maximum of 20 fields. The results might be confusing. If the repeating portion of PATTERN is more than V (contains a J or M. DEC=6*0.IXI.NHB.TXT. FORMAT=MINUTP. with IJ:V.XX MATO[3]=DEMO12. A “value set” is the group of values that follow the colon in PATTERN.TXT.4. If not set. MAXFIELDS=10. PATTERN=I:JMV. the program will split a logical data record into multiple records.5-7. NAME[3]=PURP_5 MATO[4]=TEST4. the program does not write the value set. the program writes at most 10 V values on a record. the program does not limit the size of a data record (there is a limit of 255 fields in a DBF record). MO=3-7. PATTERN=IJ:MV. DEC[3]=2 Cube Voyager Reference Guide 523 .DAT. For example. MAXFIELDS=1000. MO=1-5.MAT. Citilabs recommends that you always set MAXFIELDS. With IJ:VM. If MAXFIELDS is less than the number of matrices specified with MO. FIELDS=4. MAXFIELDS=10.Matrix Program Control statements 9 FILEO keywords (continued) Keyword MATO Subkeyword MAXFIELDS |I| Description Maximum number of value sets written on a single record.42.3. or both). The program tests MAXFIELDS before writing a value set. Use care with DBF files. DELIMITER='. Example FILEO MATO=TPPTEST. the program will start a new record if starting a new record requires less space.2. the program would write at most 10 sets of VM values on a record. If the repeating portion of PATTERN (the “repeating” portion follows the colon) is only V and the program encounters a string of zero values. MO=1-8. and V is zero.' MATO[15]=TEST15.HBOTHER. MO=1. The new record will begin with the next J containing a value. NAME=HBWORK. 8.9 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. specifying matrix numbers and names. For DBF output files. specifies user names for the record variables.. MF2.n] will refer to the beginning n record fields. NAME[n+1] refers to the first actual data field that corresponds with the first character following the ”:” in PATTERN. Tranplan. The highest implicit or explicit index determines the number of matrices included in the output file. MO[6]=31 the program will write 20. the program stores the first four characters of NAME into the bank short name and the entire name into the bank long description. NAMES[1-3] refers to those fields. the program ignores NAME. For EMME/2 data bank output files. specifies names of output matrices. You may write the same working matrix more than one time. with MO=1-5. the program will write MF1. MATO NAME |SV| For TP+. 524 Cube Voyager Reference Guide . but including a name helps document the file. For example. MO[200]=7. the program starts output matrices at 1 and writes through the highest MO index. When writing output matrices to an EMME/2 data bank file. If there are three characters prior to the colon in PATTERN. Nine of the matrices (11-19) will be empty because no data was entered for them. For such files. You may index MO. spaces. and TRIPS output files. NAME[1. specifies the names for the matrices. The program numbers output matrices monotonically beginning with 1. MO[20]=1. Note that missing MO index values are acceptable when writing binary files but not when writing text files. most set to 0. the program only writes the specified matrices. Valid matrix names contain only alphanumeric characters. If writing to an EMME/2 data bank output file. and MF200. Cube Voyager programs reading the file can reference the matrices by name and/or number. and underscores (_). For other formats. which will align with PATTERN. See “Example: FILEO MATO for EMME/2 file” on page 528 for an example of writing matrices to an EMME/2 data bank file.11-15. with MO=1. Each output matrix (specified by MO) does not require a name. For example. the program will write 200 matrices. Cube Voyager. For MINUTP and text output files. which you can use for internal documentation. If it does not exist. Each RECO must have an index [x] appended to it. Used to exclude selected fields when using the RECI. Currently. the index is assumed to be 1. If specifying an EMME/2 data bank file. NOTE: Citilabs recommends producing database files no larger than 2 GB. 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 APPEND under “PRINT” on page 66. The indices need not be monotonic or sequential. RECO CFORM |I| Length of field for all character variables that follow it on the statement. The allowed range is 1-255. See “WRITE” on page 553. RECO EXCLUDERECI |S| Cube Voyager Reference Guide 525 . Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=#. 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). and do not have a specific format associated with it. MDB and EMME/2 data bank files are the only file formats supported for this record file. The bank file must exist already. The program will write any other file name to binary PRINTO PRINTO RECO APPEND |KF| |?| |KF20| format and not in bank-file format. A later occurrence of CFORM will reset the value for character variables following it.Matrix Program Control statements 9 FILEO keywords (continued) Keyword MATO Subkeyword PATTERN |S| Description Sequence of characters that indicates the order the program writes values to the output records. the program will not create the bank file. the default is 15. the largest size that Cube Voyager and Cube Base can properly process. File name for the RECO specified. If there is no index. DBF.ALLFIELDS include macro described under FIELDS above. Valid values of PATTERN are listed and described under FILEI MATI PATTERN on page 501. the file name must be emme2ban. You can use RECO to write scalar or vector matrices into an EMME/2 data bank file. If a RECO variable name matches a variable in the RECI record. the program ignores any FIELDS not named with this format (Mx#). For backward compatibility to version 3. Cube Voyager usually refers to these as constants and zonal arrays. it is strongly recommended that the RO. 526 Cube Voyager Reference Guide . where x=S. variable. For RECO fields that are not assigned a value in the script or do not have a matching RI. the field values are NOT initialized when a new RECI record is read. variables (with or without matching RI. specifying fields and field names. the current variable values are written to these fields in the RECO DBF file when the WRITE statement is executed.name variables in the script. prefix anywhere in the script (a 3. For RECO fields that have no matching RECI fields. If you specify MO or MD. and # is a valid number for the data bank. However. 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.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. they will be left empty in the output record. Care should be taken to ensure that the other names in the FIELDS list do not conflict with the names on the RECI file. prefix be used at all times to avoid confusion. When the output file is an EMME/2 data bank. origin matrices as MO#.2. the RO. O. These variables are referenced as RO. you must also specify a Z=variable to indicate for which zone to store the data. or D. If specifying an EMME/2 data bank file with RECO.name variable each time a new RECI record is read. The RECI fields will be inserted on the RECO file at the location where this macro is found. 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. EMME/2 references scalar matrices as MS#. a logical variable for Z would be I (Z=I) if there is one RECO per zone.name variable will take on the same value as the matching RI. and destination matrices as MD#. If using RECO in conjunction with matrix processing. All RO.2 script would never have an RO. the RO. Prefix in the first place).9 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. variables) can be modified in the script. The include macro RECI. the format is: RECO=emme2ban FIELDS=Mx#. FIELDS=A. (i. and that do not have a variable.var file . For output to EMME/2 data bank files. Default value is F. specifies name in the data bank for scalar and vector matrices.d) for all numeric variables that follow it on the statement. RUN PGM=MATRIX FILEI RECI = " LINK_DATA. mode. fields=MS1 MO1 MD1 name=ms1 mo1 'md1 term time' For this example. writes the number of links to CNT. RECO Z |S| Example: FILEO These statements demonstrate FILEO. number of records (links) in the input file LOG PREFIX=CNT VAR=NUMLINKS .rank_bas NUMLINKS=RECI. decimals) as they will appear in the DBF. specifies zone for which the program stores the data. For output to EMME/2 data bank files.SORT = -VULNERABIL FILEO RECO[1] = "PRESCEENED_LINKS... The maximum value of w (the field width) is 20 and the maximum value for d (digits after the decimal) is 9—but d must be at least 2 less than w.MD1.NUMLINKS .DBF". PrescreenType and PRESCREEN value set in SM with KEYS IF ({PrescreenType}=1) .2. the program would update the data bank.specific format. Optional. Used in conjunction with the FIELDS subkeyword.MS1. and RO. but d must still be at least 2 less than w. screen based on a fixed number of links . NOTE: Variable-specific formats can specify larger values of d—up to 18. Used in conjunction with the FIELDS subkeyword.\emme2\emme2ban Z=I. Upon encountering each WRITE RECO=1 statement in the script.MD2. the default is 10.e.NUMRECORDS . the script must set the variables . A later occurrence of FORM will reset the value for numeric variables following it.Matrix Program Control statements 9 FILEO keywords (continued) Keyword RECO Subkeyword FORM |R| Description Format specification (w. RECO REPORT |?| Can be specified to have the program print a listing of the fields (name. in the *.DBF". RECO NAME |S| Optional. Required when writing MO or MD matrices. Example: reco[1] =. length. RO. top N based on Vulnerability) PRESCREEN={PRESCREEN} Cube Voyager Reference Guide 527 . changing the names as defined.B. 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. get mf01-mf04.B If (RO. NAME=mf17. prevents any centroid links .mf40. in the input network (i.mf18.mf192.23. on Vulnerability) PRESCREEN=ROUND(NUMLINKS*{PRESCREEN}/100) ENDIF LOG PREFIX=CNT VAR=PRESCREEN RO.mf02.1.2.3.MO[171]=221-240.mf13.1(40) 528 Cube Voyager Reference Guide . of links to be analyzed RO.get mf23-mf42. get mf17-mf22 FILLMW MW[101]=mi.mf08.mf35.mf05-mf13 FILLMW MW[1]=mi.mf06.9 Matrix Program Control statements ELSE . top N% of links based .1.mf18.mf07.1(9) MW[10]=mi.MAT" FILEI MATI[2] = "HWY_SKIMS. NAME[191]=mf191.mf33.mf36.mf03.mf38.mf22.. MO=1-4.mf28.mf12.A Bnode=RI.11.rank_bas+1 Anode=RI.rank_bas=RO.MO[206]=8. RUN PGM=MATRIX FILEI MATI[1] = "Purpose_Trips.mf39.9-17.21.mf41.mf34.mf24.MO[191]=5-7.mf193.mf26.RANK_BAS=RO.mf206. mf171-mf190 FILLMW MW[201]=mi.mf31.MAT" FILEI MATI[3] = "PT_SKIMS.mf23.e.mf09.mf27.MAT" FILEO MATO[1] = " EMME2BAN". NAME=mf01.mf05.4(6) .27 . mf30.mf191-mf193. from being included in set .mf29.mf04.mf42.mf11.mf25.mf10.rank_bas<=PRESCREEN) If (Anode <={Zones} | Bnode <= {Zones}) . screen based on a percentage of number of links .15.MO[17]=101-106.201-220.mf21.mf20.NAME[206]=mf206 .25.19.mf32.22.mf37. get mo20.1.1. Z=I FIELDS=ms02.1.ms02=8 .MAT" .md81=zi.md80.mo23=MW[3][I] ro.MD22 ro.md23.scalar WRITE RECO=1 ENDIF ENDJLOOP ENDRUN Cube Voyager Reference Guide 529 .mo22.Matrix Program Control statements 9 ENDRUN Example: FILEO RECO for EMME/2 file These statements demonstrate FILEO RECO to an EMME/2 data bank file. mo23 FILLMW MW[1]=mi.mo20.scalar ro.mo21.1.1. mo21.DBF" FILEI MATI[1] = "HWY_SKIMS.md82=zi.mo21=MW[2][I] ro.mo22=zi.1.md81.ms10=34.1(3) JLOOP IF (I=J) ro.MD23 ro.MD25 ro.ms10.1.MO22 ro.MD81 ro.1.md80=zi.mo25=zi.md25=zi.mo25.md23=zi. md25.mo20=MW[1][I] ro.mo23.md22=zi. RUN PGM=MATRIX FILEO RECO[1] = " EMME2BAN".MD82 ro.MO25 ro.7 .md82 FILEI ZDATI[1] = "VECTORDATA.MD80 ro.md22.1.z=I ro. PATH FILET is used to specify where various temporary files are to be written. Up to two files are required for this process. When transposing is required. Assume a 1000 zone system. The number of chunks would be 40 (80 Mb / 2 Mb). and if it is. use current directory. 530 Cube Voyager Reference Guide . and PATH[2] is not. The index file would require 800. Fratar. and opening the files is: • • • • If the PATH=' '. The first file is the actual transposed data. it could be none. In most cases. it will be relatively small. If PATH[1] is specified. The values for PATH are entered as standard operating system paths. and the second file is an index to the data file. or vice-versa. FILET keyword Keyword PATH |KS| Description Specifies the path(s) to the disk area where any temporary files are to be written. If neither is specified. If not specified. If there is a ram disk installed. The index file size will be zones * chunks * transposes * 4 bytes. 20 matrices to be transposed. Matrix Sets temporary file paths. use the PATH.9 Matrix Program Control statements FILET Programs: Distribution. then the index file might fit on it. The actual RAM requirement would be 1000 * 1000 * 20 * 4.) If the open fails. It may speed retrieval somewhat if the two files are on different physical drives. If the PATH is specified. the transposed matrices are written to a temporary file and then recalled during stack processing. The index file may not be necessary. Fatal. or TEMP. the compressed data would require about 30 Mb. and TMP is specified in the Operating System environment. (Same logic for TEMP.setting. Chunks depends upon the amount of RAM that is available for the transposing processing. they both will default to the path in the environment variable named TMP. The logic for determining the appropriate path. or 80 Mb. and 2 Mb of RAM available. the non-specified path is set equal to the specified one.000 bytes of RAM. The amount required for the data would be something less than 80 Mb. depending upon how well it compresses. use the TMP. 2.2. Example .1. matrices can be very easily moved from input matrices to work matrices or from work matrices to other work matrices.1(3) FILLMW MW[1]=mi.3 FILLMW MW[1]=mi.1. Because of its structure.Matrix Program Control statements 9 Example PATH=' ' .time.1.1.mi. Multiple matrices can be easily filled on one specification. Matrix Fill work matrices MW This statement is used to speed up the process of filling matrices with values from other matrices.1.distance.distance.3 FILLMW MW[1]=mi.1. root of c: for data. the following values may be unqualified (they do not have to have MI. prefixed to their names/numbers).cost Cube Voyager Reference Guide 531 . use current directory for both PATH=.1. After the first value.R: . current directory on d: for index FILLMW Programs: Distribution. The following five statements all do the same thing FILLMW MW[1]=mi. This is also true for MW sources. 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. but FILLMW sets up very fast moves in contrast to internal computational solutions performed by COMP statements.#.1. Fratar.cost FILLMW MW[1]=mi.mi.time. drive R: for index PATH=c:\ d ..mi. Everything that can be done on a FILLMW statement can be accomplished by COMP statements. The beginning MW target is the keyword and the values are the matrices that are to be moved into the target matrices.mi. up a directory for data.1.1.1.\. 2.3] FREQUENCY Program: Distribution. The next two statements illustrate the simplicity of FILLMW vs.MW[1. BASEMW RANGE REPORT TITLE VALUEMW Use FREQUENCY to obtain a frequency of occurrence of the values of a work matrix. Fratar.1.2.1. MW[1](3) . mw[12]=mw[2].3.2.9.1(5). A typical use is for a trip length distribution. mw[14]=mw[9].2.3.1-5. where the number of trips in a matrix is stratified according to the times from a time or distance matrix. MW[4]=mi. 532 Cube Voyager Reference Guide . Matrix Stratifies one matrix’s values based upon the values of another.1. mw[15]=mw[6] .2.will fill MW[101-108] with MI. COMP FILLMW MW[11]=mw[1].3.9 Matrix Program Control statements . The final results are reported at the end of all zone processing.6 COMP MW[11]=mw[1].4 FILLMW MW[101]=mi. 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).1. mw[13]=mw[3]. An example of multiple keywords FILLMW MW[1]=mi. VALUEMW=2. Matrix Use GOTO to jump to statement named :label.5. The first number (RANGE[1]) is the lowest value for which there is to be a stratification. if the value from BASEMW is less than RANGE[1]. the report will be printed for the last iteration. REPORT IP| TITLE VALUEMW |S| |I| Example FREQUENCY BASEMW=1. Minutes' FREQUENCY BASEMW=1. Cube Voyager Reference Guide 533 .VALUEMW=2.Matrix Program Control statements 9 FREQUENCY keywords (continued) Keyword RANGE |RP| Description Set of two. the value from VALUEMW is accumulated into an out-of-range bucket. Generation. Title for identifying the final report at the end of the application. If this keyword is not specified. REPORT=99 GOTO Program: Distribution. the default will be 1.RANGE=0-100-0. The third. but care should be taken if this is to be done. During accumulation. flow immediately branches to the statement named label. or if any of the values exceed the last iteration. number (RANGE[3]) is an increment for stratification. TITLE='Work Trips vs.RANGE=1-100. The numbers are separated by a dash. Label can be within IF and LOOP blocks. Fratar. optional. Iterations for which the report will be printed. or higher than RANGE[2]. or three. The second number (RANGE[2]) is the highest value for stratification. Work matrix number ( MW[ ] ) whose values will be accumulated according to the values of BASEMW (the trip matrix for a trip length distribution). REPORT is used primarily only when the Matrix program is invoked as a process that runs in a multiple iteration mode (Distribution program). numbers that establishes the valid values for stratification. If there is no increment. When GOTO is processed. the same rules for indexing in a COMP statement are applied. It is permissible to go backwards.n. Matrix IF (expression) ELSEIF (expression) ELSE (expression) ENDIF IF/ENDIF blocks are used to determine if certain operations are to be performed. ENDIF Program: Distribution. Example GOTO buildhwy GOTO :buildhwy A statement that begins with : is a label statement. The leading ”:” is ignored. it is suggested that they be used judiciously. . ELSEIF .n.name or MW[] should realistically only be used within a JLOOP. This prevents using GOTO from jumping into a JLOOP.. IF . Fratar. but they may not overlap LOOP. If a variable in the expression is MI... :buildhwy IF (expression) GOTO :buildhwy . A label statement can be within IF and LOOP blocks.n. IF blocks may be nested. that has meaning with only GOTO statements.9 Matrix Program Control statements label is a character string that must have a matching LABEL statement.. or MW[]. Generation. The leading colon ”:” is removed from label when determining the qualified name of the statement to branch to.. care should be taken if this is done. MI..name. or other IF blocks. NOTE: The placement of a :label inside a JLOOP is not allowed. ELSE . ZI. Although IF expressions can be quite powerful for 534 Cube Voyager Reference Guide . Lengthy IF expression solutions could be time consuming. 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.name. Example GOTO buildhwy . ELSE . The following illustrates a more efficient process for using IF for .. statement ENDJLOOP ENDIF JLOOP . . && J=j_ranges. lengthy zonal selections within JLOOPs .57 & k=(2*j-4) ) || ((J*k) = 14-20. and probably can not be aided by a filter. but that might have caused . Fratar. 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 .. The J selection could have been filtered... conflicts with the use of J in other parts of the expression.. .single IF with process IF (expression) EXIT IF ( ( j=3-5. Generation. ELSEIF (loop_cntr > 10) .Matrix Program Control statements 9 zonal selection.....time < 32) . The above IF example is rather esoteric. ENDJLOOP Programs: Distribution. Cube Voyager Reference Guide 535 .6-30. ELSEIF (loop_cntr > 5 && diff. . ***** Inefficient ***** JLOOP IF (I=i_ranges. ***** More efficient ***** IF (I=i_ranges. Matrix Control a J loop for processing matrices.) JLOOP INCLUDE=j_ranges. sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples in this section)..) statement ENDJLOOP . ENDIF .56) ) . Jinc=1. 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 . All statements between the JLOOP and ENDJLOOP statements are processed with the current value of J. If (J < 1 or J > Zones or Jend <1 or Jend > Zones) fatal termination. Jend. 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. and J fails INCLUDE) go to ENDJLOOP. and J meets EXCLUDE) go to ENDJLOOP. and J meets EXCLUDE) go to ENDLOOP. If (EXCLUDE. • at ENDJLOOP: Add Jinc to J. If (INCLUDE. If (INCLUDE. and J fails INCLUDE) go to ENDJLOOP. LOOP or IF blocks. The logic for JLOOP and ENDJLOOP processing is: • at JLOOP: If J is specified. If (EXCLUDE. COMP MW[]= statements are processed only for the current value of J. Else set J=1. and may not overlap other JLOOP. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. establish values for J. Jend=Zones. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. and Jinc. Next statement. JLOOP blocks may not be nested.9 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. Zones. If there is no Jend. Expression that establishes the Jend for the loop. if an expression contains any commas. the value may not be less than 1 nor greater than Zones. the value may not be less than 1. depending upon the direction from Jbeg to Jend. Jinc If Jbeg is not specified.1 are used. it is set to 1 ( -1. JLOOP and ENDJLOOP keywords Keyword J Jbeg Jend |I| Description Sets Jbeg. Jinc is set to 1 or -1. it must be enclosed within (). Jend and Jinc. Jinc can not be. nor greater than Zones. If Jinc is not specified. Expression to initialize J.Matrix Program Control statements 9 PRINT REPORT SET NOTE: The placement of a :label inside a JLOOP is not allowed. Expression that establishes the Jinc for the loop. they must be separated by commas. Example JLOOP J=I EXCLUDE=500-535 . and Jinc is set to 1. and the values 1. 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. if Jbeg > Jend). Jend is set to Jbeg. 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 . . This prevents using GOTO from jumping into a JLOOP. If Jinc is not specified. and the values Jbeg and 1 are used. Because all these values can be expressions. If Jend is not specified.process only intra zonal values . Jend and Jinc can not be. Generation. jump to next statement. they may not overlap IF blocks. Compute Lend. Lend. Compare LVAR to Lend. Linc LOOP ENDLOOP blocks are used to repeat of a series of statements. Fratar. Matrix Control a general variable loop. and branches back to the statement following the LOOP statement if the comparison fails. The logic is as follows: • at LOOP: Initialize LVAR to Lbeg. LOOP blocks may be nested. Add Linc to LVAR. • at ENDLOOP: If Lend not specified. LOOP initializes a variable. 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 .. LVAR = Lbeg.9 Matrix Program Control statements LOOP .. and Lbeg > Lend) Else compute Linc. Proceed to next statement. ENDLOOP Programs: Distribution. ENDLOOP compares the contents of the variable to another value. The process differs considerably from JLOOP. If Linc not specified: Set Linc to 1 or -1 (if Lbeg and Lend are constants. and other LOOP statements can alter its value.0 ENDLOOP PARAMETERS Program: Matrix Cube Voyager Reference Guide 539 .Matrix Program Control statements 9 Because of the flexibility of this logic. program.2 . Lbeg Lend Linc Example LOOP iter=1. LOOP and ENDLOOP keywords Keyword LVAR Description Name of the loop control variable.3. Numeric expression that LVAR is to be compared with when the ENDLOOP statement is processed. LVAR is not protected during the loop. and optionally. 7. Because LVAR values can be expressions. and Linc must be separated by commas (standard white space delimiting can not be interpreted properly). ENDLOOP LOOP xyz=abc*def.10 . The loop will be processed at least one time regardless of Lend and Linc values. it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend.-2. Numeric expression that is to be added to LVAR before the ENDLOOP comparison is made. it is assumed no comparison is to be made (rather meaningless loop). If it is not specified. Most uses will involve constants. LVAR must be followed by Lbeg. Numeric expression to initialize LVAR. Lbeg. On the other hand.ghi+jkl.mno/pqr LOOP abc=xyz.5. This would only happen if the Lend and/or Linc values are expressions that contain variables which could be altered during the loop. the flexibility provides for powerful control. unpredictable results and/or endless loops can occur if care is not taken.xyz+2. If Linc is not specified.5 . computational. Lend and Linc. 10. 5. perform 10 iterations . nested LOOP ENDLOOP ENDLOOP LOOP jj=10. Lend. a backwards loop). Each matval call requires a direct access lookup on the designated MATI. Maximum index for work matrices (MWs). Normally. If too large a value is used. the value must be defined. the larger the number. which could possibly hinder performance. you do not specify this keyword and override default value. The default is 100. Each value requires (zones*8 + 4) bytes of RAM. Establishes the maximum length for a string variable’s value. Default value is 50. the RAM for cache might come from disk. MATVALCACHE MAXMW MAXSTRING TRAM ZONEMSG ZONES PARAMETERS keywords Keyword MATVALCACHE |KI| Description Number of matrix rows to cache when dealing with the MATVAL function. Valid values range from 1 to 999. but if it is desired to compute longer strings. In general. Each read of a row for matval results in a matrix row being read and stored for possible later use. All string variables will have this possible length. MAXMW |KI| MAXSTRING |KI| 540 Cube Voyager Reference Guide . the more efficient matval is. Optional.9 Matrix Program Control statements Sets general parameters. The user might have to experiment to determine the best number of his application. Default value is 999. the program writes a message for every 10 zones. The program writes to the console when initiated through runtpp. Program writes to the run monitor when initiated through Application Manager or voyager. The program will request the amount that it thinks will provide the most efficient processing. 4000000 is the default. The most efficient amount would be (Zones * Zones * 8 * NumberTransposes). with a value of 1.exe. Optional. With a value of 0. it will provide that much memory. and should not normally be reset.exe. 4MB (4000000) should be adequate for most applications. Default value is 1. if Windows is controlling the computer. the default value for ZONES will be determined by the highest value from any MATI.Matrix Program Control statements 9 PARAMETERS keywords (continued) Keyword TRAM |KI| Description Establishes the maximum amount of memory that is to be used for temporary storage when transposing matrices. For example. If ZONES is not specified. ZONEMSG |IK| Cube Voyager Reference Guide 541 . Valid values are greater than or equal to zero. and the program has no other way to identify the appropriate number of zones. Specify a larger value to reduce run times. However. The program can not detect if the ram is real or virtual. Frequency with which the program writes zonal timing messages to the run monitor or console. With a value of 10. but a portion of it might be virtual memory (temporary work space on disk). the program writes a message for every zone. If there are any input MATI statements processed. ZONES |KI| Establishes the number of zones to process. but that would probably be more than the computer has available in real memory. In general. therefore. the program writes no zonal messages. it will be set to 100. care should be taken to not specify a value that is too large. Value corresponds to number of zones. The use of virtual memory is disastrous in terms of efficiency for the transposing process. 001 PRINT FORM=6. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See “PRINT” on page 66 for details about the standard Cube Voyager statement. Generation.31-60.002 PRINTROW Program: Distribution. FORM=LRCD.9 Matrix Program Control statements Example ZONES=3000 PRINT Programs: Distribution.J.1 form=LRD title='form=LRD' printrow mw=1-21 form=6D base1=y maxperline=10. MW J TITLE FORM MAXPERLINE BASE1 See “PRINTROW” on page 73 for details about the standard Cube Voyager statement. TOTAL2.0CDLR LIST=I. title='form=6D base1=y. maxperline=10' 542 Cube Voyager Reference Guide .Note this line is a continuation LIST= I(6) J(6) TOTAL1. Fratar. Example PRINT FORM=0 LIST=I.JLOOP_J .TOTAL1.83 printrow mw=1-2. LIST=N. Matrix Prints row of matrices.TOTAL(6. Example Examples of output with various parameters follow: pagewidth=80 mw[1]=j mw[2]=j include=1-5.2CS) 'ABCDE'(6.90-100 exclude=35.TOTAL2 FILE=PRINTFIL. Fratar. TOTAL3 FILE=PRINTFIL.3).J. Matrix Format and print a line of information. ....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.....-...90 92 93 94 95 96 97 98 99 100 RENUMBER Programs: Fratar..... This causes an extra layer of processing.91 92 93 94 95 96 97 98 99 100 PRINTROW MW[1] form=6D base1= Tot=5.. Matrix Renumbers (aggregate. and then retrieved and combined after all normal processing is completed.-......36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 -..31 32 34 .390 3 4 5 -.-.-..Matrix Program Control statements 9 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.-.........-.-.....36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 58 59 60 -.-32 33 34 -. Cube Voyager Reference Guide 543 .. because the matrices must be saved.-. 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.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 .-..-.... 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.) terminates data on a record. and a pair of percentages (ROWPCT and COLPCT ) to indicate how the outgoing matrix zonal values are to be allocated to the renumbered zones. it MUST be followed by ”=”. A semi-colon (. anything following the .9 Matrix Program Control statements Each input zone must be assigned a new output zone number. COLPCT is set to ROWPCT. If there are less than three fields. OPZONE is set to 0. Output zone number. The records may have from one to four fields to specify the renumbering. 544 Cube Voyager Reference Guide . If there are three fields. ROWPCT and COLPCT are set to 100. but the first character must be D. The standard fields are: Field IPZONE OPZONE ROWPCT COLPCT Description Input zone number Output zone number Percentage of IPZONE’s values to be assigned to OPZONE when renumbering the IPZONE row Percentage of IPZONE’s values to be assigned to OPZONE when renumbering the IPZONE columns If there is only one field. Two fields may be separated by a dash (”-”) if the two are to form a range. These equivalencies are obtained from records in the designated FILE. Remaining fields are the input zones that are allocated 100% (ROWPCT and COLPCT) into OPZONE. is a comment. usually the case when a zone is to be split into several new zones. if not. or on disk files (compressed format). there must be sufficient disk space for both the intermediate rows. The sum of all ROWPCTs and COLPCTs for each IPZONE should each be 100. a message is issued. renumbered. An OPZONE may appear more than one time.20-30 45. Every IPZONE (1-IPzones) should be fully allocated. Only one of those two keywords can be used at one time. at the normal output phase. To accommodate this process. RENUMBER keywords Keyword FILE |F| Description File that contains the zonal equivalencies. FILE and ZONEO are mutually exclusive. 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. and written to the MATO files. and saved. The intermediate matrices are saved either in RAM (normal format). An IPZONE of 0 means there is intentionally no IPZONE for the OPZONE. Cube Voyager Reference Guide 545 . the normal output matrices are trapped. When all zones have been processed. the record must be broken into several records. and the length of the record would exceed 250 characters. the use of the FILES and INRAM keywords could help considerably in reducing running times. If saved on disk. usually the case when aggregating zones. combined when necessary. An OPZONE of 0 means there is intentionally no OPZONE for the IPZONE. and the final output files. Example D 1=1-10.48. Each record must begin with the District string. The process is optimized to the extent possible. the saved matrices are retrieved in appropriate order. There should be an OPZONE for every zone (1-OPZONES). if not.Matrix Program Control statements 9 If the list of IPZONEs is large. and may not terminate with a dash. a message is issued. An IPZONE may appear more than one time. and ZONES is set to the highest OPZONE. MISSINGZI |S| ZONES |I| Example[1] FILEI MATI=IN. nor greater than 10. a message is issued. it defaults to F. but never less than 1. inclusive. It indicates the level of error associated with gaps in the OPZONE structure.MAT. or M. 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. Single character (if a longer string is specified.MAT FILEO MATO=OUT. A check is made to ensure that there is an OPZONE for all values: 1-ZONES. The value must be in the range 1-10.**. The number of files affects the running time when the final matrices are being formed. district or TAZ number. until they can be sorted and combined in the final stages of the application. no edit is performed. to ensure that each OPZONE doesn’t exceed this value.***. if there are any gaps. or MISSINGZI is not specified. If ZONES is not designated. Alternate method of specifying zonal equivalencies using an input zonal data file. more files generally speeds up the final stage. only the first character is processed) to indicate how to treat input zones that are not fully allocated (ROWPCT and COLPCT totals of 100).9 Matrix Program Control statements RENUMBER keywords (continued) Keyword FILES |I| Description Number of temporary files to use to store intermediate factored matrix rows. W. the program will set the value to ZONES/100. The character may be F. In this convention. Ten files will normally reduce the application time by a factor of about 20-35 per cent as compared to one file. A typical value of ZONEO is an input zonal attribute: ZI. MO=1 546 Cube Voyager Reference Guide . ZONEO and FILE are mutually exclusive. If the keyword is not specified. and if it is none of these. the IPZONE is the current zone number and the OPZONE is the specified input zonal attribute. for example. The meanings are: F — Fatal W — Warning M — Message only (no penalty associated) MISSINGZO ZONEO |S| |S| Indicator similar to MISSINGZI. 88 .78 2.18 .3 5 6 6.22 4.MAT will be all zeros .44 3.Z1_AREA/ZI.DBF is: . the split factor is the ratio of the area of the new zone to the area .EQ RENUMBER FILE=2005ZON.DAT RENUMBER ZONEO=ZI. DIST=2 FILEO MATO=OUT.MAT.1. MO=1 MW[1]=MI.1 .66 . of its parent. .40 2.58 3.48 3. Z=#1.DBF .4 7 8 6.2 3 4 6.24 . 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.MAT. Data structure of TAZDATA1. must load values into MW[1].1 . renumber OUT. 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. must load values into MW[1]. else OUT.5 9 10 6. MISSINGZO=W Example[2] FILEI MATI=IN.18 3.Z NEW_Z1 NEW_Z2 Z_AREA Z1_AREA Z2_AREA . */ .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. This set up assumes all input zones are split into two output zones . A typical process might be to split zones into fully nested sub zones in ArcView.EQ.46 2.1.STEP 1 RUN PGM=MATRIX FILEI ZDATI[1] = TAZDATA1. . MISSINGZI=M.MAT will be all zeros .SPLIT2 Cube Voyager Reference Guide 547 .Matrix Program Control statements 9 MW[1]=MI.1 1 2 6.42 3.MAT according to 2005ZON.DAT. PARAMETERS ZONES=2999 .1.Z_AREA) SPLIT2=100-SPLIT1 . and that the total area of the new zones is equal to the area of the parent zone. renumber OUT.1. establishes a split factor based on the new zone geography .1.75 2. else OUT.73 . ZDATI=ZDATIN. writes the split factors to the PRN file PRINT LIST=SPLIT1. . SPLIT1=100*(ZI.MAT according to ZDATIN. 00 50.2 .STEP 2 – split input trip table to new zonal system RUN PGM=MATRIX FILEO MATO[1] = TRIPS2.13 .00 7.NEW_Z1. FILE = EQUIV_1. ENDRUN . OPZONE and ROWPCT .ZI.53 .00 2.1.ZI. fill work matrix 2 with TRANSIT trips from input matrix 2 RENUMBER. 4.00 65. if different COLPCT factors are desired they would need to be specified in the . NAME=AUTO.00 60.00 49.MAT mw[1]=mi. write the zonal equivalency file PRINT LIST=I. 1.00 9.DAT .31 .00 8.00 41.1.00 57. 5. ENDRUN REPORT Program: Matrix Request reports and establish tracing MARGINS TRACE MARGINREC (CFORM FORM LIST FILE (PRINT)) 548 Cube Voyager Reference Guide . data structure of EQUIV_1. 5.NEW_Z2. the zonal equivalency file has the fields IPZONE.MAT. . 3. FILE = EQUIV_1.00 3.00 1.DAT is : . the default when no COLPCT is specified is to set the COLPCT=ROWPCT. MO=1-2.06 .SPLIT2. 2. 4.00 6. fourth column of the file.94 .00 5.30 . 2.00 4. TRANSIT FILEI MATI[1] = TRIPS1.47 .DAT" PRINT LIST=I.00 58.00 39. .SPLIT1.69 . fill work matrix 1 with AUTO trips from input matrix 1 mw[2]=mi.1.9 Matrix Program Control statements . . FILE = EQUIV_1. 3. 1.87 .00 10.00 42.DAT" .1 .00 34.1. .70 . but any variable or literal string can be specified. the variables are row and column values obtained from the accumulation of margin values for work matrices. Format to use for any numeric data items that appear after this keyword. 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.Matrix Program Control statements 9 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. Format to use for any character data items that appear after this keyword. Variable values are formatted to the zonal record. MARGINREC MARGINREC CFORM FILE |S| |F| MARGINREC FORM |S| Cube Voyager Reference Guide 549 . the earlier files will be overwritten. Specifies a file where the formatted list is to be written. normally. Only one FILE value is allowed per each MARGINREC switch. If names conflict. A separate file is written for each MARGINREC FILE value. and I4 is the intrazonal value for work matrix four.9 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. MARGINREC MARGINS PRINT |?| |KIP| Switch that indicates that the FILE record is to also be written to the standard printed output. C. C2 indicates the column total for work matrix two. there is insufficient RAM to accumulate all the totals. MO. margin accumulation could be canceled for certain matrices. NOTE: MARGINS and MARGINREC cause the program to accumulate margin values for each zone for each of the included matrices.Zones). or I) followed by a number. output matrices and working matrices. I1_I2_I3 is the sum of the intrazonal values for matrices one. of the requests as required. If there is insufficient RAM. and MW to generate reports for input matrices. R1 indicates the row total for work matrix one. for some reason. and I names with an underscore '_' acting as the concatenating character. the program will delete (and notify) some. and J is the zone variable that is used. but the most meaningful one would be J. Variables can be formed by concatenating R. Requests that row and column totals be accumulated and reported for the specified MWs (work matrices). the format applies to only that item. If it is desired to have an explicit format for any item in the list. and three. there may be a format appended to the it. Valid values are: MI. A record is written for each zone (J=1. Such a format is surrounded by (). Example: J ITEM1(6) ITEM2(8C) 'abcde' 'i='(8R) K(L) The variables are normally a character (R. Each MW report is listed in telephone book style with empty zones being omitted. 550 Cube Voyager Reference Guide . Other variables can be inserted into the record. C. MATSTAT |S3| Specifies desired matrices for which statistical summaries will be formatted and reported in the run print file. If. or all. Example: R1_C1 is the sum of the row value and the column value for the zone. two. 8 .1015 13-12 -.-----------.---.--Table 3 .R2.04 9. If a COMP is traced.923.R5_C5 MARGINREC=y LIST=J. ZDAT |?| ZDAT DEC |I| Example These statements illustrate REPORT.---.256 -. so be careful).56638 3. FILE=r:\intras.1050 3-16 -. turn stack tracing on REPORT TRACE=n .77147 106. REPORT MARGINS=1-3.71 13-13 -.357. This one value applies to all variables on all ZDATI statements.0145 3-16 -.86395 -Table 2 .Minimum -------------.Ave ---------- Cube Voyager Reference Guide 551 .99 -.--.--MW[2] 3. Trace can be turned on and off at any time.26.1.Matrix Min/Max (625 cells) ---------. thus controlling the amount of output as desired.455.64 13-13 -.' sum intras for 1-3='.99 978.14 16.923.5450 3-16 -.455.Matrix Program Control statements 9 REPORT keywords (continued) Keyword TRACE Subkeyword |K?| Description Controls the listing of the stack statements as they are processed (can be quite voluminous.357.15.--MW[3] 0.Cnt --.65 1-1 -.17 27. turn stack tracing off MARGINREC=y LIST=J.--.----------.27789 -MW[2] 9.Sum ----------.Matrix Intrazonal Summary (625 cells) ---------.43.Sum ---------.----------.Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 2. Sets the maximum number of decimal places to be printed for any variable.Ave ---------ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 16.17 -.39.R3_R4_C3_C4.256 -.Matrix Summary (625 cells) ----------.87686 38. Switch that indicates that the zonal data arrays generated by any FILEI ZDATI keywords are to be formatted and reported.256 -. request margins summaries REPORT TRACE=y .256 -.print=y REPORT MATSTAT=MW .--MW[4] 6.--.1.370.97 13-13 -.82418 -MW[4] 27.007. only the first five J values will be reported.C1.C2.--.378.1.76187 -MW[3] 978.R1. I1_I2_I3.04 -.Cnt --. request statistical summaries for working matrices Example MATSTAT REPORT: Table 1 .32822 64.14 -. If a named VARS is an array allocated by an ARRAY statement. VARS=TOT1.96 4.39.74 7-7 -.285232 11. the entire array is set to the value of VAL.4.99 -.--.059.96 -. variables. and then reset as this keyword is encountered.97 13-13 -.059.Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 4.85625 -MW[3] 178.7.0.70 1.27 178.2. and are then changed only by the user. but it is not as efficient.629.27 -.82 3-3 -. and is somewhat wordier.Matrix Intrazonal Min/Max (625 cells) ---------.867.1. A COMP statement can accomplish all that SET does.007.378.607520 101. SET keywords Keyword VAL |R| Description Numeric value that the VARS that follow will be set to. is the same as previous statement SET VARS=TOT1 TOT2 COUNTER . Matrix Stores numeric values into one. List of variables that are to be set to the more recent value of VAL obtained from this statement. or more.71 13-13 -.70 -. Most changes are the result of COMP statements.16 -.16 -.867.-----------.24937 -MW[2] 1.16 -.Minimum ------------.--.--MW[2] 6.9 Matrix Program Control statements ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 3.99 3. VARS |S| Example SET VAL=0.--MW[3] 0. is also the same (VAL defaults to 0) 552 Cube Voyager Reference Guide . the coded VARS are all set to zero.09 12-12 -.895984 191.370.629.--. Generation. All variables are set to zero at the beginning of the I-loop.TOT2.COUNTER COMP TOT1=0 TOT2=0 COUNTER=0 . If there is no VAL.14187 -MW[4] 4.64 13-13 -.65 1-1 -.--MW[4] 18. VAL VARS Use SET to set any number of variables to some value. Fratar.--.1.--- SET Programs: Distribution.24750 -Table 4 .16 -.12 5-5 -.788736 304. VAL is initialized to zero when the statement is started. Fratar.Matrix Program Control statements 9 SET VAL=123 VARS=C123.ZONENO. NUMRECS=ZONES LIST=’ Zone Income HHs’ JLOOP PRINT FORM=8. Fratar. INCOME=ZONES . sets all to 123 ARRAY SUMS=50 SET VAL=100.HH[I] INCOME[I] = ZI. Example ARRAY ZONENO=ZONES. Generation. ARRAY NUMRECS See “SORT” on page 76 for details about the standard Cube Voyager statement. . HH[J] ENDJLOOP WRITE Programs: Distribution. Generation. Matrix Output record data files to DBF format RECO Cube Voyager Reference Guide 553 .1. INCOME[J]. sets all 50 cells of SUMS to 100 SET VARS=SUMS . TOT2. VARS=TOT1. LIST=ZONENO[J]. HH=ZONES.INCOME[I] .1. VARS=SUMS . . SORT ARRAY=-INCOME.-HH. sets all 50 cells of SUMS to 0 SORT Programs: Distribution. TOT3 . ZONENO[I] = I HH[I] = ZI. Matrix Sort user-defined arrays. 554 Cube Voyager Reference Guide . WRITE keyword Keyword RECO |I| Description Number of the FILEO RECO[#] DBF file where you want to direct this print output.9 Matrix Program Control statements Use WRITE to specify the record files that are to be written at the end of each I zone. 1. hh3=#7 zdati[2]=employ.dat.dat. at last zone jloop .mat zdati[1]=socoecon.1.1.Matrix Program Examples 9 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. write a file of zonal records print file=newzdat.2.hh3 jloop include=1-5.zda form=6 list=j(3) pop[j] area[j] totemp[j] tothh[j] cbdtrips[j] endjloop endif ENDRUN Example 2 . pop=#2. tothh=10 .z=#1. gov=#2.38.tottrips[j] endjloop if (i==zones) . hh2=#6.2.gov + zi.hh1 + zi.1. this is a 10 zone problem area[i]=zi.56-100.other tothh[i]=zi. retail=#3. other=#4 ARRAY pop=10. hh1=#5. z=#1.cbd zones cbdtrips[j] = cbdtrips[j] + mi.145-150 .2. income=#4.dat file Cube Voyager Reference Guide 555 . area=#3.1.area totemp[i]=zi. area=10 totemp=10. Get I-J values for records with trip tours on them.hh2 + zi. /*Sample setup to use the MATRIX program to process the tours.retail + zi. nfield[76] = 1) . dst=26 . but has not been thoroughly tested for logical content. i.from. flds 32.nfield[stops] > 0) .org.reci. */ RUN PGM=MATRIX mati=hwytime. tablenumber. from file 1 table 1 hwyt[leg]=MatVal(1. Field 23 can also be referenced as ri.ri. org=23.trntime. tablenumber. assuming 1 is highway otherwise transit The program will read each input record from the RECI file and do calculations as specified.dst.mat.42 if (reci.0) endif . trips from dst to org 556 Cube Voyager Reference Guide .nfield[stops].nfield[76] = 1) .nfield[stops].from. . The MatVal function is used to random access any i-j value from any input matrix. from file 2 table 1 trnt[leg]=MatVal(2.mat reci=tours. from last stop to dst if (reci.ri. setup array to store time values with max of 8 legs on each tour array hwyt=8 trnt=8 set val=0.0) else .0) endif leg=leg+1 from=reci.from.from.0) else . initialize output variables .dst. i.org leg=1 loop stops=32.1.nfield[#]. can be referenced by reci.5 .37.dst .42. there are 80 fields on the record.dat. vars=hwyt trnt . failvalue) The failvalue is returned if lookup fails (invalid filenumber.nfield[stops] endif endloop .1. look up highway or transit time based on the major mode for that journey. trips from org to dst from=ri. from file 2 table 1 trnt[leg]=MatVal(2. or j) This script has been tested for validity. if main mode org-dst is hwy .1.9 Matrix Program Examples For each leg of the tour. and field 26 as ri.1. The format is: MatVal( filenumber. if main mode org-dst is hwy if (reci. from file 1 table 1 hwyt[leg]=MatVal(1. j.reci. from.hwyt[3].0) endif .hwyt[7].hwyt[6].57. FIELDS=RECI.0).trnt[2]. EXCLUDERECI=HOUSEHOLDS FILEO RECO[2] = ZONES_2010. Cube Voyager Reference Guide 557 . from file 1 table 1 hwyt[leg]=MatVal(1.nfield[stops] > 0) if (reci. HH_2002(8.nfield[77] = 1) . form=5 list=reci.trnt[3].reci.5 if (reci. POP_2010(8.2). from file 2 table 1 trnt[leg]=MatVal(2.Matrix Program Examples 9 from=ri.trnt[8] .DBF FILEO RECO[1] = ZONES_2002_NEW. FIELDS=RECI.2).hwyt[5].nfield[stops]. HHsiz_2002(4.ri.0).hwyt[2].org.hwyt[4].trnt[7].nfield[stops].nfield[77] = 1) .org. trnt[1].1. 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.2).1.2).nfield[stops] endif endloop .trnt[6]. HHsiz_2002(4. write out I/P record(RECI) and append highway and transit time values print file=tourtime. from file 2 table 1 trnt[leg]=MatVal(2.0).2).trnt[5].DBF.reci.2).0) else .0).ALLFIELDS. Pden_2010(4.1. Pden_2002(6.dat. HH_2002(8. from last stop to org if (reci. if main mode dst-org is hwy .0) else .from.ALLFIELDS.DBF.from. from file 1 table 1 hwyt[leg]=MatVal(1.from. HH_2010(8.trnt[4]. HHsiz_2010(4. Pden_2002(6.0) endif leg=leg+1 from=reci. if main mode dst-org is hwy .hwyt[8].1.dst leg=5 loop stops=47.ri. hwyt[1]. POP_2020=RECI. Pden_2010(6.ALLFIELDS.MAT" MO=1 NAME=HBW 558 Cube Voyager Reference Guide .0).TotalPop PRINT LIST='Average Household size = '. print regional base year statistics if (I=0) .TotalHH PRINT LIST='Total Population = '.4 RO.POP_2002/(ri.8 RO.HH_2010=HH_2002*1.HOUSEHOLDS .0).NFIELD[6]*1.0). compute regional base year statistics TotalHH=TotalHH+RECI. calculate zonal population density per/acre for base year RO.0).0).HHsiz_2010=POP_2010/HH_2010 RO.NFIELD[6]*1.2).2 RO.POP_2010=RECI. HHsiz_2020(4.5 RO.HH_2020=HH_2002*1. factor base year data for 2010 RO. Pden_2002(6. write data to defined output files WRITE RECO=1. Pden_2020(6. rename RECI field RO.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.Pden_2002=ri. HH_2020(8. HH_2002(8.Pden_2010=POP_2010/(ri. factor base year data for 2020 RO. POP_2020(8.HHsiz_2002=ri.AREA/43560) .NFIELD[5] TotalPop=TotalPop+RECI. POP_2010(8. HHsiz_2010(4.2. HH_2010(8.HHsiz_2020=POP_2020/HH_2020 RO. FIELDS=RECI. check for end of file PRINT LIST='Total Households = '.AREA/43560) . calculate zonal average household size for base year RO.Pden_2020=POP_2020/(ri.2).NFIELD[6] avgHHsize=TotalPop/TotalHH .avgHHsize endif .HH_2002=ri.2).2).POP_2002/HH_2002 .9 Matrix Program Examples EXCLUDERECI=HOUSEHOLDS FILEO RECO[3] = ZONES_2020. HHsiz_2002(4.AREA/43560) .2).DBF.2). EXCLUDERECI=HOUSEHOLDS . .. CHOICE ALTERNATIVES=all1.1. DEMAND=ZI.DBI.mdb\AlfaBeta2". with attraction totals as the single constraint. to implement a destination choice.1.P1. .MAT" . STARTMW=99.2. saving it to output file .DBF" FILEI MATI[1] = "{SCENARIO_DIR}\CURRENTCOSTS.A[1] etc) .NUMRECORDS x=DBIReadRecord(1.If you require a gamma curve deterrence function rather than the negative exponential.1.BETA=DI.ZONE_=DI. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.transpose the resulting matrix to correct orientation. production and attraction data (i... .2 all1 . FIELDS=ZONE_ ALFA BETA FILEI DBI[2] = "DBI_Examples.BETA WRITE RECO=1 Cube Voyager Reference Guide 559 .This example gives a ”destination choice” model constrained on production trip ends.mdb\BETA". COSTS=mi.1.ZONE_ RO. ODEMAND=1.transpose the cost matrix. TOTAL=ZI. .e.Matrix Program Examples 9 FILEI ZDATI[1] = "{SCENARIO_DIR}\TRIPENDS.ALFA RO.mdb\ALFA" ZONES=1 LOOP k=1. SORT=ZONE_ JOINTODBI=1 JOINTOFIELDS=ZONE_ FILEI DBI[1] = "DBI_Examples. reading the transposed costs.run MATRIX. 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.ALFA=DI.1.k) RO.To apply singly constrained on attractions. .1.The general approach for a singly constrained in Voyager is to use the MATRIX . .you need to specify the appropriate calculations yourself. DESTSPLIT = TOTAL 0.1.program and the CHOICE command to implement a destination choice model. reversing your use of the . 4) BETA(10.1.BETA = DBA.mdb\AlfaBeta3".9 Matrix Program Examples ENDLOOP ENDRUN Example 6 /* The same process as Example 5 but using AUTOARRAY functionality to accomplish the same task.mdb\ALFA".2.BETA[L3] WRITE RECO = 1 ENDLOOP ENDRUN 560 Cube Voyager Reference Guide .1.1 RO. AUTOARRAY=BETA FILEI DBI[1] = "DBI_Examples.DBI. FIELDS = ZONE_ ALFA(10.ZONE_ = L3 RO.mdb\BETA". AUTOARRAY=ALFA ZONES = 1 LOOP L3=1.ALFA[L3] RO.4) FILEI DBI[2] = "DBI_Examples. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.NUMRECORDS.ALFA = DBA. Cube Voyager Reference Guide Cube Voyager Reference Guide 561 . Topics include: • • • Introduction to the Distribution program Control statements Examples 562 Cube Voyager Reference Guide .10 Distribution Program 10 Distribution Program This chapter discusses the trip distribution process. The most commonly used distribution process is the “gravity” model. In some cases. where: P = the number of trip productions for a zone. A brief illustration of a typical gravity distribution follows. but it does need some help. but other processes are also employed. A gravity model distribution can be easily implemented within Matrix. Usually the process uses the number of trip ends in each zone as the starting point. Cube Voyager Reference Guide 563 .. additional information about some measure of travel between each zone pair should be included in the process.Distribution Program Introduction to the Distribution program 10 Introduction to the Distribution program This section introduces you to the Distribution program. These margin totals are distributed to the rows and column of a generated matrix. Usually. the Matrix program does have some built-in functions that aid in the implementation of the more popular distribution processes.n (A * func(T)). or default. 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. Cube Voyager does not have any automatic. The Matrix program provides a framework that allows the user to perform distribution in a variety of ways. and the user has to follow certain guidelines for proper implementation. The gravity model equation is: TRIPi-j = Pi * Aj * func(Ti-j) / Sz=1. trip distribution process. 564 Cube Voyager Reference Guide . and it difficult to estimate what b should be used. The function of spatial separation (func(T)) is the indefinite portion of the equation. Numerous applications have shown that friction factor curves tend to follow the same patterns for similar conditions. where b is the curve factor. several guidelines must be followed: • There must be a set of Ps and As for each purpose to be estimated.10 Distribution Program Introduction to the Distribution program A = the number of trip attractions for a zone. They are established by the presence of a SETPA control statement. To implement the gravity model in Matrix. 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. and T is the travel time. i = the production zone. It is believed to be best described by an expression of the form of e^bT. z = any zone. The sum of the these products for all Js (relative to I) is obtained and often referred to as the accessibility index for I. j = the attraction zone. Each J’s attractiveness is determined by the product of its attractions and some function of the spatial separation between I and J. n = the number of zones. T = the travel impedance factor between zones. These curves are usually called friction factor curves. To facilitate application. most gravity model processes use a lookup function to obtain empirical values for the function based upon the impedance. Experience has shown that often a single curve does not suffice. Many agencies share the same curves when their regions are similar in nature. 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. 1. and the travel function value (friction factor) is obtained by finding the impedance in a LOOKUP table. One to compute attractiveness for each J.P1.DAT. Example 1 /* given: The impedances are in the first matrix of file: IMP. ZDATI[1] = PA.Z=#1. and one to distribute the productions based upon the values and the accessibility index. a level-of-service matrix is used to obtain the zone-tozone impedance for I-J. MW[1]=PAF * MW[1] GRAVITY PURPOSE=1.ZDA. A[1]=ZI.A1 MW[1] = A[1] * FF(1.RESULT=#1.1.MAT The productions and attractions are in file: PA.ZDA The friction factors are in file: FF. one to sum them to form the accessibility index for I.LOOKUP[1]=#2. FILE=FF.A1=#3 FILEO MATO[1] = OUT. At least three expressions are required.MI. these expressions must be executed in the proper order.DAT */ FILEI MATI[1] = IMP. the GRAVITY control statements can be used to perform a built in process for a doubly constrained GRAVITY model. Obviously.1. The gravity model equations must be executed in a specific order.Distribution Program Introduction to the Distribution program 10 • A mechanism must be established to obtain the travel function.P1=#2. See “Examples” on page 555 under the Matrix program for an example of a singly constrained gravity model.MAT. FFACTORS=FF .1. faster process Cube Voyager Reference Guide 565 . MO=1 LOOKUP NAME=FF. • As an alternative to complete user definition of the gravity formulation. Usually. LOS=MI. INTERPOLATE=Y SETPA P[1]=ZI.1. This process is more efficient than complete formulation.MAT.1). A singly constrained gravity model can be formulated as a destinationchoice model with the CHOICE control statement in Matrix. PAF=P[1]/ROWSUM(1). There is no method to guarantee that the correct column totals (number of attractions) will be obtained for each J zone.-. At the end of each iteration.-.300 Total 240 200 160 600 There really is no matrix yet. The iteration process is repeated until it is decided that the results are close enough.-. This problem is alleviated by iterating the model. The row totals shown are the Desired Ps for each zone. An iteration is a complete pass for all I zones. and the column totals are the Desired As.-. A set of A values internally named Used are set equal to the Desired values.-.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. 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 .-. the estimated column values will not match the desired number of As input for each zone. Following is small example of this process: Prior to the first iteration the desired totals are: Zone 1 2 3 Total 1 -. In all likelihood. the row (production zone) totals for each will always match the number Ps for the zone. based upon the comparison.200 3 -.100 2 -. the estimated column totals are compared to the input As. and. the process is repeated with an adjustment in the data. The model goal is to fill in the matrix with values so that the totals will match the totals shown. The totals are the values as obtained from the SETPA control statements. The adjustment is based upon the closeness for each zone. or that a maximum number of iterations have been performed. the totals did not match exactly (there were some slight differences in the decimal places). the floating point values were close enough to be accepted as having matched. with many zones. Another iteration is performed. 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. 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. As a matter of fact. Additionally. The default is MAXITERS=3. the row totals are correct. 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. MAXITERS specifies that no more than a specified number of iterations are to be performed. Further iterations would be useless. it is not likely that all the Estimated totals would match exactly with the Desired totals.Distribution Program Introduction to the Distribution program 10 As dictated by the formulation. nothing would change. How does the program decide when it should stop? There are two parameters that can be used for controlling cutoff: MAXITERS and MAXRMSE. in this simple three zone problem. But. this is usually sufficient for most gravity model applications. But. In the real world. so adjustments are made to the used As. Cube Voyager Reference Guide 567 . The model is completed. and another iteration is performed. and MAXITERS has not been reached. and 0. 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. In the sample three zone problem the RMSEs for each iteration were computed as: 22. the program knows when the last iteration is being processed. at least three internal purposes are estimated.10 Distribution Program Introduction to the Distribution program the program computes the root mean square error of the differences in Estimated vs. If the default MAXRMSE value had been used. But. With the Cube Voyager process.08. some analysts prefer to estimate them in a separate application. another iteration will be processed with adjusted As for all purposes. There are other popular purpose stratification. 2. a completion flag is set. and Non Home Based (NHB).78. but these are the most commonly used. and some prefer to do them all at once.26 indicates that there were still some slight differences in the Estimated and Desired. Often Internal-External and External-Internal and truck and taxi purposes are also estimated. The final value of 0. Each purpose can have its own impedance matrix and different formulation (functions. The Ps and As and lookup functions can be obtained from different sources. similar to the one just completed. Multiple purposes Usually a given application will consist of more than one purpose. Desired attractions (sqrt (Sum(diff^2) / (n-1)). the results will not get worse. expressions. If the iteration number is equal to the PARAMETERS MAXITERS value. Home Based Other (HBO). convergence could be obtained at some lower iteration. In that case the program will perform another iteration. the process would have cutoff after two iterations. but that may not always be a good choice for certain applications. Traditionally. but as noted above.). they were insignificant. with the most commonly used purposes being: Home Based Work (HBW). That is no concern. There is one caveat: If convergence has not been reached for any purpose. but this time writing 568 Cube Voyager Reference Guide . etc.26. The default is MAXRMSE=10. The MAXRMSE parameter applies to the highest RMSE of all purposes. MATO files are written only on the last iteration. If the computed RMSE is less than MAXRMSE. friction factors. RESULT=2. the set up is only slightly different from what is depicted. INTERPOLATE=Y. LOOKUP[1]=1.RESULT=4 Cube Voyager Reference Guide 569 .Distribution Program Introduction to the Distribution program 10 the MATO files.1. A[2]=ZI. but at the cost of additional time to write matrices during each iteration.1. Example 2: Three purpose . A[3]=ZI. with only three points in it.1. If the estimates follow the same formulation.RESULT=2. monotonically. if convergence is reached before MAXITERS. purposes 1-3 are the same as in Example 2. and two internal-external purposes (with entirely different formulation) are to also be included.same P/A and FF file for all purposes LOOKUP FILE=FF. LOOKUP[2]=1. LOOKUP[3]=1. an additional iteration will be performed in order to obtain the matrices. LOOKUP[1]=1. P[3]=ZI. Other COMP MW[]= statements may be specified. above. Purpose 4 uses an equation for distribution.RESULT=4 SETPA P[1]=ZI. The use of PARAMETERS MATOEVERY will preclude an additional iteration. NAME=FF. The number of purposes is determined by the highest P[] or A[] index established via the SETPA control statement.1. and purpose 5 uses a simple lookup curve.1. The program assumes that there will be purposes from one.DAT. INTERPOLATE=Y.P1.0.RESULT=3.P3.P2. Example 2 illustrates a typical setup for a three purpose application. P[2]=ZI. LOOKUP[2]=1. LOOKUP[3]=1. NAME=FF.1.DAT.1) PAF=P[PURP]/ROWSUM(PURP) MW[PURP]=PAF*MW[PURP] ENDLOOP In Example 3.A3 LOOP PURP=1.1.1. A[1]=ZI.A2.A1. In other words.RESULT=3.MI. but they will not be involved in any internal purpose editing. through that highest index. Example 3 LOOKUP FILE=FF. FAIL=12000.3 MW[PURP] = A[PURP] * FF(PURP. 3.IMPEDANCE) INCLUDE=501-535 ENDIF PAF=P[PURP] / ROWSUM(PURP). A[1]=ZI.P1. P[5]=ZI.2. FAIL=500. A[3]=ZI.A1.A3 SETPA P[4]=ZI.10 Distribution Program Introduction to the Distribution program LOOKUP NAME=XIFF. there are different ways that this distribution could have been written. A[5]=ZI.SHORTIMP MW[4] = A[4]*EXP(-B * IMP) ENDJLOOP ELSE MW[5] = A[5] * XIFF(MI.2.2. P[3]=ZI.1. Since most users may not wish to always code a zone index (it is more intuitive to reference the arrays with just purpose number).1.MI. the zone index has 570 Cube Voyager Reference Guide . and the second index references the zone number.1.1. P[2]=ZI.PI. '200 40-50' SETPA P[1]=ZI.DISTANCE < 3) IMP = MI. '300 30-40'.3.AI. the program issues a message and adjusts the As to match the P total.P3. Referencing productions and attractions Productions and attractions are referenced by using array notation for P and A. A[2]=ZI. where the first index references the purpose number. the zone index need not be supplied.A2.STACNT_OB. However. Differences in the totals would preclude convergence via RMSE calculations because there would always be differences.1. it will be automatically provided. P and A are doubly dimensioned arrays. .100. MW[PURP]=PAF*MW[PURP] ENDLOOP Of course.1. R= '500 1-20'.2. Most likely. read the data directly '400 20-30'.2. the purpose 4 and 5 Ps and As would not sum to the same total because they were derived from separate sources.1) ELSEIF (PURP==4) JLOOP INCLUDE=1-500 IMP = MI.IMPEDNACE IF (MI.P2.3 IF (PURP <= 3) MW[PURP] = A[PURP] * FF(PURP. A[4]=ZI.1.2.STACNT_IB LOOP PURP=1. If there is a difference in the totals for a purpose. they are normally input to the program from an external lookup file. Most times an invalid index will cause a fatal termination. NAME=FF. P and A are protected variables. it is J. the default zone index is I and for A. The friction factor for purpose 1 for a time value of 1. but may not always be predictable. respectively. 3. depending upon the options specified on the LOOKUP statement. respectively. RESULT=4 This statement indicates that the first four values from each record will be used.5 could be either 9000 or 8500. Purpose 0 and Zone 0 are valid. 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. For P. The lower bounds for both indices are zero. and fields 2.Distribution Program Introduction to the Distribution program 10 different meanings for P and A. LOOKUP[1]=1. Field 1 will be the travel time value. If a different index is required. and the friction factor for purpose 2 would be 8000. Zone 0 should always contain the total for the purpose. and the upper bounds are “number of purposes” and zones. and 3. The friction factor for purpose 1 for 1 minute would be 9000. The lookup file is usually formatted as a series of curves – one curve for each trip purpose. they may not be the result of COMP expressions. LOOKUP[3]=1. LOOKUP[2]=1. 2. except on SETPA statements. Travel function values: Friction factors If friction factors are to be used in the distribution process. The curves are organized vertically on the records of the file. If Cube Voyager Reference Guide 571 . it may be explicitly provided. RESULT=2. RESULT=3. and 4 are the values for purpose 1. because there is no explicit FAIL[1] specified. 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 capability allows for compatibility with other model systems. 572 Cube Voyager Reference Guide . the friction factor for any time greater than 50 would be 1. However.10 Distribution Program Introduction to the Distribution program SETUPPER=T is specified. and if SETUPPER=F and INTERPOLATE=T. This can also be controlled by use of the LOSRANGE keyword on the GRAVITY statement. The friction for any value greater than 51 will be 0. no distribution. any time greater than 50 would be 0.5 will result in the value 9000. if FAIL[2]=0 were used. a time value of 0. If the record for 51 were not in the file. the friction will be 8500. In this example. the friction factor will be 9000. PURPOSE LOS FFACTORS KFACTORS LOSRANGE Cube Voyager Reference Guide 573 . Since the Distribution program is a subset of the Matrix program. Only the differences between the Matrix and Distribution control statements are included in this section. it is assumed that the user is familiar with the Matrix-program control statement set. For descriptions of other control statements see “Control statements” on page 451 under the Matrix program. and a few additional ones are available.Distribution Program Control statements 10 Control statements Most of the standard Matrix program statements are valid in the Distribution 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. lookup[3]=1. list=n.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. In this statement. KFACTORS |S| LOS |S| LOSRANGE [R] PURPOSE |I| PURPOSE. and FFACTORS must be specified. The value MUST be either a MW[#] or an MI. Normally. The value MUST be either a MW[#] or an MI. If an I-J values is less than the first value or greater than the second value. Specifies the range of LOS values that are valid for use in the distribution process. or greater. name=ff. Example lookup fail=12000. The lookup arguments will be automatically set to the value from the LOS matrix and the PURPOSE number.result=2. no arguments should be used with the lookup name.name/#. Default range is 0 . Specifies the matrix that contains the K-factor values for each I-J distribution.#.name/#.999999. LOS.result=4.#. Specifies the matrix that contains the level-of-service values for each I-J distribution.0. The lookup table is expected to be in the form shown in the Examples. 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. It is more efficient than using multiple COMP statements to formulate the same process.result=3. Optional. lookup[1]=1. This keyword must be followed by a pair of numbers separated by a dash. and the second value must be greater than the first. GRAVITY keywords Keyword FFACTORS |SN| Description Specifies the expression that results in the friction factor that a gravity equation expects. 574 Cube Voyager Reference Guide . lookup[2]=1.1. See “LOOKUP” on page 55 for hints about using Lookups to obtain friction factors. file=tstff1. Specifies which purpose this is calculation to: the results will be stored in MW[PURPOSE]. The first number must be 0. there will be no distribution between for I-J. los=mw[11].1. If it is anticipated that there will be many iterations to reach convergence. los=mw[11]. the parameters described here may also be specified. This causes the program to run somewhat longer for each iteration. los=mw[11].result=5. Cube Voyager Reference Guide 575 . interpolate=y. gravity purpose=3. MATOEVERY MAXITERS MAXRMSE ZONES In addition to the standard Matrix-program parameters. lookup[5]=1. it normally does not write matrices for the iteration. Since the program does not know that a particular iteration will be the final one until after it completes the iteration. This saves a considerable amount of computer time for larger systems. but may preclude the program from having to run another iteration to obtain the output matrices once convergence is reached.Distribution Program Control statements 10 lookup[4]=1.K5 PARAMETERS Sets general parameters. ffactors=ff ffactors=ff. PARAMETERS keyword Keyword MATOEVERY |K?| Description Switch that can be used to force the program to write output matrices for every iteration. gravity purpose=4. If it is anticipated that the process will involve only a few iterations. gravity purpose=5. it is probably better to set this switch false. gravity purpose=2. losrange=11-48 ffactors=ff ffactors=ff ffactors=ff. it does force another processing iteration to write the matrices once it has determined that this is the last iteration.setupper=n gravity purpose=1. los=mw[11]. los=mw[11]. it is probably better to set this switch true.result=6. But. instead of waiting until the last iteration. Kfactors=MI. If present. If the highest RMSE (for any purpose) exceeds this value. the number of iterations actually performed could be less than this value.10 Distribution Program Control statements PARAMETERS keyword (continued) Keyword MAXITERS |KI| Description Specifies the maximum number of iterations to perform. If the number of zones can not be ascertained from the project file or from any binary input matrices. so this keyword should not be required. The default is 10. if all the purpose RMSEs are less than this value. If the model converges in fewer iterations. ZONES must be provided. MAXRMSE |KR| ZONES |KI| REPORT Specifies Matrix program reports.0001. Normally. Conversely. or the value will default to 100. and the minimum is 0. automatic cutoff is not triggered. this value controls the application. Specifies the cutoff criteria. The default is 3. If the MAXRMSE criterion is met. there will be an input matrix file. and the max is 99. 576 Cube Voyager Reference Guide . Specifies the highest zone number to process. automatic cutoff is triggered. one more iteration will be run (with the same values as the converging iteration) so that the MATO matrices will be written. Distribution Program Control statements 10 ACOMP (ITERATIONS) REPORT keywords Keyword ACOMP |KIP| Description Requests that the comparison of Estimated vs. Specifies the iterations for which the prior ACOMP purposes reports are to be printed. If the values for ACOMP are followed by ITERATIONS. There should be a P[]= and A[]= expression for every Cube Voyager Reference Guide 577 .5 ITERATIONS=5. In ACOMP reports. Desired attractions be reported for the specified purposes. the program will fatally terminate. if it is not included. If no ITERATIONS follow ACOMP values. the PARAMETERS MAXITERS. for all iterations SETPA Establishes base productions and attractions. the reports will be printed for the last iteration (no matter how it is determined: parameter or convergence). the report will be printed for every iteration (could be quite voluminous). The values are reported as nearest integers (without decimal places). P A INCLUDE EXCLUDE The SETPA statement is required. or exceeds. If there are no ITERATIONS specified. If at least one value is equal to.10. the reports will be printed for all iterations.99 . The statement defines to the program how the desired productions and attractions are to be obtained. 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). Only the purposes specified by the keyword are reported. and how many purposes are to be processed. then those ACOMP purposes will be printed only during the iterations specified. specified purposes and iterations REPORT ACOMP=6 . ITERATIONS |IP| Example REPORT ACOMP=1-3. The report is in a format that is similar the MARGINS report. The highest index encountered establishes the number of purposes. EXCLUDE filtering follows any INCLUDE filtering. For each array. the expression is solved in a loop of J=1-Zones. the loop will not be processed for any zones not in the list. The total of the As should match the total of the Ps for each purpose. If it is used.10 Distribution Program Control statements purpose beginning with 1 and continuing. it is acceptable to set the Ps. Duplication of purposes might be helpful if values for different zones for a purpose are to be obtained from different sources. If there are any holes in the purpose scheme. and they are computed only one time -. If the same purpose is referenced more than one time (this is acceptable). If the totals differ by any amount. Complex expressions are allowed. If it is used. In a purpose where the Ps and As are the same for each zone. The SETPA expressions are computed in the order in which they appear in the control stream. the expression will simply point to a ZDATI file variable. or if different INCLUDE/EXCLUDE filters are to be used (separate SETPA statements must be used for different filters). 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. INCLUDE filtering precedes any EXCLUDE zones. INCLUDE |IP| 578 Cube Voyager Reference Guide . Processed the same as EXCLUDE on COMP statements. until all purposes are defined. (NonHomeBased is a typical example). but the use of any variables in the expression could cause unpredictable results. the program will issue a warning statement. a message is issued.prior to the first iteration. the As are scaled so that the A total will match the P total. If the totals differ by more than five percent of the P total. the loop will not be processed for any zones in the list. The Ps and As are computed from the expressions that are supplied. and then set the As equal to the Ps. In most cases. the subsequent values will replace the prior values. monotonically. Processed the same as INCLUDE on COMP statements. SETPA keywords Keyword A EXCLUDE |NV| |IP| Description Expression that is solved to set the attractions for the indexed purpose. p1.p1.nhb. but will work Cube Voyager Reference Guide 579 . get only external data P[1]=zi.p2. . .a1. Example SETPA INCLUDE=1-500. A[1]=zi.1. weird. A[5]=A[1]+A[2]+A[3] . A[4]=10 .cnt.2.2.1.1. internal zone data only P[1]=zi. P[4]=zi. A[1]=zi. A[2]=zi. P[3]=zi. .cnt.1. equal attraction for all zones SETPA EXCLUDE=1-500.1. P[2]=zi.Distribution Program Control statements 10 SETPA keywords (continued) Keyword P |NV| Description Expression that is solved to set the productions for the indexed purpose.1. A[3]=P[3].a2. merges with prior SETPA P[5]=sqrt(A[3]). 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.P3=4. P4=5.A5 LOOP PURP=1.MAT MATO = GMTRIPS. HBO. LOOKUP[5]=1.Z=#1.A1=7. MO=1-5. A3=9. LOOKUP[3]=1.A5=11 MATI = IMPEDE. P5=6.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.A4 A[5]=ZI.1. NHB.P5 SETPA A[1]=ZI. INTERPOLATE=N.0. P3=4.A3 A[4]=ZI. RESULT=2.1.A4=10. A2=8. RESULT=5.A2=8.DO PURPOSES 1-5 MW[PURP] = A[PURP][J] * FF(PURP. LOOKUP[4]=1. LIST=N. A4=10.A2 A[3]=ZI.A1 A[2]=ZI.1.1.P1 P[2]=ZI.P2=3.P1=2.P3 P[4]=ZI. RESULT=6.1. A1=7.DAT 580 Cube Voyager Reference Guide . FILE=TSTFF1. NAME=FF. XI LOOKUP FAIL=12000.5 .1. NAME=HBW.1. SETUPPER=Y MAXITERS=3 MAXRMSE=10 SETPA P[1]=ZI.1.1.P4 P[5]=ZI. A5=11 MATI[1]=C:\DEMO\DEMO11.A3=9.P4=5. P2=3. P1=2. IX.1.1. RESULT=3. RESULT=4.P5=6. LOOKUP[1]=1.P2 P[3]=ZI.MI. LOOKUP[2]=1. Income2. This script then performs the gravity model using the .-----------------------------------------------------.mat.1 LOOP PURP=1.a2=7. FFACTORS=FF ENDRUN Distribution example 3 /* Gravity Application illustrating use of GAMMA Impedance function */ .txt. LOOKUP[3]=1. FFACTORS=FF GRAVITY PURPOSE=4.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. FFACTORS=FF GRAVITY PURPOSE=2.-----------------------------------------------------. NAME=FF. mo=1-4.a3=8. name=Income1.a1=6. LOOKUP[2]=1.1.Income3. FFACTORS=FF GRAVITY PURPOSE=3. . LOOKUP[1]=1. RESULT=2.z=#1. FILE=TSTFF1. RESULT=6.1. in order to generate a trip table. LIST=N. LOS=MW[11]. SETUPPER=N MAXITERS=20 MAXRMSE=35 MW[11]=MI.p3=4. FFACTORS=FF GRAVITY PURPOSE=5.p1=2.MAT mato=hbwgm. RESULT=4. LOOKUP[4]=1. .Income4 PAR maxiters=20 maxrmse=10 Cube Voyager Reference Guide 581 . RESULT=3. RESULT=5. run pgm=tripdist zdati[1]=hbwpa. Finally.0.a4=9 mati=SKIM. LOS=MW[11].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.p2=3. LOS=MW[11]. This script reads the composite time skim table created . distribute with user equation (Results in MW[6-10]) PP = PURP+5 MW[PP] = A[PURP][J]*FF(PURP. from the AM peak period highway and transit skims. LOOKUP[5]=1. .p4=5. . LOS=MW[11]. new trip table. estimated friction factors along with the P's & A's . INTERPOLATE=Y. LOS=MW[11]. HBW GRAVITY MODEL USING GAMMA IMPEDANCES . a trip length frequency is performed for the .5 . ======================LOOKUP FUNCTION===================== LOOKUP NAME=_FFParms.1.p2.1.4 . PUT GAMMA MATRICES IN MW[21]-MW[24] mw[GSKIM]=(mw[TSKIM]^_b)*exp(_c*mw[TSKIM]) ENDLOOP .123' . time for income class 4 .. TITLE='** HBW Income Class 4 Travel Time Frequency **' endrun 582 Cube Voyager Reference Guide . 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 .123'. Beta .2 . TITLE='** HBW Income Class 3 Travel Time Frequency **' FREQUENCY VALUEMW=4 BASEMW=14.1.p3 p[4]=zi. ==============Put TIME VALUES IN WORKING MATRICES=========== mw[11]=mi.1. Gamma Function Parameters LOOKUP[1]=1. . a[3]=zi. ======CREATE GAMMA VALUE MATRICES FOR EACH INCOME CLASS===== LOOP Inc=1.3 . RESULT=3.10 Distribution Program Examples setpa p[1]=zi.p1 p[2]=zi.4 . p[3]=zi.Inc) _c=_FFParms(2. . Alpha. Alpha.020 -0. Income Class 2. Income Class 1. Input Time Skim to MW[11] to MW[14] GSKIM=INC+20 . RANGE=1-140.1. Alpha. TITLE='** HBW Income Class 2 Travel Time Frequency **' FREQUENCY VALUEMW=3 BASEMW=13. RANGE=1-140.a3 a[4]=zi.4 _b=_FFParms(1.020 -0. . Beta ' 2 -0. Beta ' 3 -0. time for income class 1 mw[12]=mi.1 . ========GENERATE FREQUENCY REPORTS BASED ON TIME============ FREQUENCY VALUEMW=1 BASEMW=11.1. TITLE='** HBW Income Class 1 Travel Time Frequency **' FREQUENCY VALUEMW=2 BASEMW=12.Inc) TSKIM=INC+10 . ALPHA VALUE LOOKUP[2]=1. a[1]=zi. =================PERFORM TRIP DISTRIBUTION================= LOOP PURP=1. .1. RANGE=1-140.123'.123'.a2. time for income class 2 mw[13]=mi.1. .1. Output Gamma Skim . RANGE=1-140.020 -0. BETA VALUE INTERPOLATE=N.p4. Income Class 3. Beta ' 4 -0.1.1. Income Class 4. Alpha.1. Set P and A Fields .a4 . time for income class 3 mw[14]=mi.020 -0. No Interpolation needed on income class R=' 1 -0. RESULT=2.a1 a[2]=zi. . Cube Voyager Reference Guide Cube Voyager Reference Guide 583 . Topics include: • • • Introduction to Generation program Control statements Examples 584 Cube Voyager Reference Guide .11 Generation Program 11 Generation Program This chapter discusses the Generation program. The ADJUST stack is processed one time only -. The Generation program has two processing phases and stacks: the normal stack (ILOOP) that begins with the first stack statement. respectively. the second index (zone) is optional. it is suggested that P and A references within the JLOOP Cube Voyager Reference Guide 585 . and an optional ADJUST stack. it is your responsibility to specify what is to be accomplished. very little is assumed by the program. it does not proceed beyond the PHASE=ADJUST statement. The zonal index will be set to I if it is not specified.Generation Program Introduction to Generation program 11 Introduction to Generation program The Generation program processes zonal data according to specified expressions. Usually. computations. There may be up to twenty Ps and twenty As for each zone. and generates arrays of productions and attractions for up to twenty purposes. Only the first index (purpose) is required. To make things a little more meaningful to some users. The computed Ps and As are stored into arrays and must be referenced with array notation. they are referred to as P and A. I and Z can not be revised by the user). you use the Generation program to produce trip end data files (productions and attractions) for use in a trip distribution model. Its purpose is to provide capabilities to adjust and/or balance final production and attraction totals. There may be up to twenty trip purposes estimated in a single application. I may alternatively be referenced as Z. There is very little need to use a JLOOP. It is the user’s responsibility to program the logic. The arrays are doubly dimensioned. (A companion variable Z is set to I every time I is changed internally. The program processes within an overall origin zone loop controlled by the variable named I. the capability is nearly open-ended. However. There are no default processes. Productions and attractions are to be computed for each zone. which begins with the statements following the PHASE=ADJUST statement. The I-loop processes only the normal stack statements. 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. and output.after the I-loop is completed. but if one is used. The lower limit for each index is 0. Any attempt to use an invalid index will result in a fatal message. In ILOOP. A more detailed expression would be P[1][I] = ZI. 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] . LOOP/ENDLOOP. and JLOOP/ENDJOOP blocks and any GOTOs may not span a PHASE. P[1]=ZI. double indexing on the right side of the equal sign can set the process to compute for only that specific zone. PTOT(#) and ATOT(#) can also be used at any time to compute the totals for purpose #.1. It should be noted that IF/ENDIF. Example A[1] = 1 . row and column 0 cells are set to the marginal values. sets only 1 cell P[1] = A[1] . 586 Cube Voyager Reference Guide . When the ILOOP phase is completed. There is a significant difference when referencing P and A in COMP statements in the ADJUST stack. the program fills in the [0] row and [0] columns for the P and A arrays. The COMP functions.POP indicates that the productions for purpose 1 for the current I zone are to be obtained from the ZDATI[1] array named POP. This is to simplify the final adjusting process.POP[I]. The statements in the ADJUST stack can reference index [0] to obtain row and/or column totals. COMP P and A is processed for a single zone index (I). 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.1. However. the upper limits are MAXPURPS and ZONES. but such detail is not necessary. The program will treat such conditions as errors. a COMP P and A causes processing for all zones in that P or A.11 Generation Program Introduction to Generation program contain both indices. in ADJUST. . 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 . 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 . Since the Generation program is a subset of the Matrix program. and a few additional ones are available. it is assumed that the user is familiar with the Matrix control statement set. For descriptions of other control statements see “Control statements” on page 451. Only the differences between the Matrix and Generation control statements are included in this section..Generation Program Control statements 11 Control statements Most of the standard Matrix program statements are valid in the Generation program. It is used to compute variable and P and A array values. 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.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. 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. and then the productions are set equal to the attractions for each zone. First 588 Cube Voyager Reference Guide . most users adjust the Attraction totals to match the Production Totals. P/A row.2. P2A=list A2P=list NHB=list This statement makes the adjustment process much simpler. Example BALANCE A2P=1. Typically. Specifies the purposes whose attraction totals are to be set to the production totals for that purpose. The major difference between the Generation and Matrix programs for COMP statements is in the use of P/A[] and MW[]. Specifies the purposes whose production totals are to be set to the attraction totals for that purpose. 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.4-7 NHB=3 COMP Computes a variable. the J loops from 1 to zones. Secondly. If the second [] is not specified. it will default to I. The COMP statement may contain INCLUDE and EXCLUDE to cause selective processing.90*ahbo IF (I=38-49) P[1]=ZI. If the second [] is not specified.1. P[n][I] |N| Expressions may contain the functions ATOT(#) and PTOT(#). 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 . COMP P[]=. MW[] is not valid in the Generation program. the J loops from I to I (a single iteration).SPECIAL FILEO Generates trip-end records.4. 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. A[]=. While in the Generation program. which return the attraction and production totals for purpose #. when P[]= or A[]= is specified in the ILOOP phase. Within the ADJUST phase. and MW[]= expressions automatically imply a loop based upon J from 1 to zones in the Matrix program. it will default to I.Generation Program Control statements 11 of all. There may be multiple PAO specifications. They will be processed in the order in which they appear in the input stream. The result is stored in P[n][I].P1 COMP A[2]=0. The result is stored in A[n][I]. Causes the program to solve the expression for each value of J. COMP keywords Keyword A[n][I] |N| Description Causes the program to solve the expression for each value of J. each one should reference a different file. Example COMP P[1]= ZI. See “COMP” on page 477 for details of COMP statements. The PRINT processor is called one time for each zone in a loop where Z=1-Zones. A maximum of 100 variables may be designated for single DBF. If the PAO keyword specifies an MDB file for the output.11 Generation Program Control statements require. If DBF=F and PAO specifies an MDB file the program will fail. Normally. and the various trip ends such as P[1]. usually it should be written in a format such that the Distribution process can read it as the distribution trip ends. a[1]. unless turned on. FILEO keywords Keyword PAO PAO CFORM Subkeyword |KF10| |S| Description Name of a file where the formatted records are to be written. the PAO processing uses the Cube Voyager General PRINT control statement processor. For consistency. the records should contain only the zone number (I). the user may optionally name the variables to be written to the DBF records with the NAMES subkeyword. The major difference between PAO and PRINT statement is that PAO specifies the output file by definition. etc. text variables will not be written to a PAO file. Within Cube Voyager. This is off. the most likely place where this data would be read would be in any program that accepts ZDATI files. 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. and the FILE keyword is not allowed. Although other data can be placed on these records. then DBF subkeyword should either not be specified or set to T. If DBF=T is specified. Indicates if the output records are to written as a DBF file. Format for following string list items. normally. PAO DBF |?| 590 Cube Voyager Reference Guide . Full documentation about the sub-keywords can be found in “PRINT” on page 66. p2. if designated as longer than 10. List of items to be formatted into the output buffer. Names to be assigned to the DBF variables. the program will use the variable name directly. the zone index is automatically supplied as Z. the only variables in the list will be Z. If there is no name specified for a variable. For example: LIST=z.a1. A name may not exceed 10 characters. If the LIST field is an expression.p1. FORM=20. In most cases. and expressions of P[n] and A[n] values. Extraneous NAMES (that is.Generation Program Control statements 11 FILEO keywords (continued) Keyword PAO Subkeyword FORM |S| Description Format for following numerical list items. For example (VAR1+VAR2+VAR3) will be named VAR1VAR2VA. DBF=T. they should be enclosed within parenthesis. OTHERPROD. WORKPROD. and should not contain any spaces or commas.2SLR is recommended if the Distribution program is going to read the file. Cube Voyager Reference Guide 591 . ignoring other characters.a3.p3.NAMES=TAZ.NHBPROD PAO LIST |S| PAO NAMES |S| would set the names in the DBF for z. The routine does not check for duplicate names. OTHERATTR.p3. the program will use the first 10 alphanumeric digits. are ignored. NAMES[11] in this example).p2.a2. respectively.a3. P and A must be indexed. If any expressions are used. The names are positional (their indices refer to the positional location of the variables in the LIST). NHBATTR would set the names for a1.a2.p1. Likewise: NAMES[5]=WORKATTR. it will be truncated. This is off. and the program has no other way to identify the appropriate number of zones.. If ZONES is not specified. ZONES MAXPURPS PARAMETERS keywords Keyword ZONES |I| Description Establishes the number of zones to process. if the keyword is not specified. Example PAO = OUTPUT. The maximum value is 20. Z P[1] A[1] P[2] A[2] (P[3]+P[4]) (A[3]+A[4]) PARAMETERS Set general parameters.0. which the program defaults to.DAT. 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. FORM=SL. and establishes an index boundary for P and A in COMP statements. ENDPROCESS Establishes phase blocks.. it will be set to 100.DAT. unless turned on. PHASE ENDPHASE 592 Cube Voyager Reference Guide . Sets the number of P and A arrays to be allocated. MAXPURPS |I| Example ZONES=3000 MAXPURPS=5 PROCESS .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. FORM=8. Setting this to a more realistic value will cause a less drain on computer memory. LOOKUP. the PROCESS control word is not necessary. Example RUN PGM=GENERATION . PHASE=ILOOP P[1]=…. P[1]=…. . . PHASE=ADJUST . the occurrence of another PROCESS statement acts as the ENDPROCESS statement. PROCESS keywords Keyword PHASE |KS| Description Names the phase stack. normally. even if they are located within a phase block. until an ENDPROCESS statement or another PROCESS statement is encountered. the following statements are used to balance Ps and As RUN PGM=GENERATION . to further simplify coding. The control statements that follow it. will be executed when the phase is internally executed. In the Generation program. FILEO. To simplify coding. the following statements are used to balance Ps and As Cube Voyager Reference Guide 593 .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. such as PARAMETERS. PHASE=ADJUST . are not processed as stack statements. The following PHASE names may be specified: • • ENDPHASE |K| ILOOP ADJUST Defines the end of the user control statements for a stack. If ENDPROCESS is used. FILEI. it may be coded as either ENDPROCESS or ENDPHASE. the ENDPROCESS statement is not necessary. And. . 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. PHASE=name may be used directly. Exception: Static statements. Controls the listing of the stack statements as they are processed. This report precedes ADJUST processing. Requests that the final attractions be reported. This report follows any ADJUST processing. A P AC PC TRACE REPORT keywords Keyword AC A PC P TRACE |?| |?| |?| |?| |K?| Description Requests that the computed attractions be reported.11 Generation Program Control statements REPORT Requests reports and establishes tracing. This report precedes ADJUST processing. This report follows any ADJUST processing. Example REPORT AC=y A=y P=y 594 Cube Voyager Reference Guide . Requests that the final productions be reported. Requests that the computed productions be reported. xicnt=6-10.61 * 13.59 * 11.1.hh6=#8. emp1=3.14 * 17.1 * zi.1 * zi.4 * zi.1.hh6 + .4 * zi.hh4 + .1.dat.1.hh2 + zi.8 * zi.18 * 8.1.z=#2.1. hh8=10.hh5 + zi.hh6 + .emp2=4 zdati[3]=c:\demo\demo08.21 * 6.1.hh7 + .1.1.hh2 + .1.21 * 4.hh2 + .68 * 15.hh13 pnhb = .1.hh9 + .9 * zi.1.1.23 * 16.hh6 + zi.59 * 10.13 * 18.hh3 + .dat.23 * 11.1.57 * 6.15 * 16.dat.hh7 + .7 * zi.0 * zi.1.select=1-1.18 * 11. select=2-1.hh11 + zi.62 * 17.hh1 + zi. hh1=#3.hh5 + .hh10 + .1.hh8 + .hh12=#14.23 * 10.hh2 + .16 * 15.1.1 * zi.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.hh10 + zi.hh5 + .hh10 + Cube Voyager Reference Guide 595 .hh12 + .hh3 + .hh11 + .7 * zi.1.1.hh5 + .1.2 * zi.hh7 + .1.hh3 + zi.1.hh8 + .hh11=#13.hh12 + zi.8 * zi.hh13 phbo = .24 * 17.5 * zi.1.8 * zi.1.0 * zi.2.hh4=#6.1.18 * 10.1.23 * 13.hh9 + .1.1.4 * zi.1.62 * 18.hh10 + .2 * zi.57 * 4.1.hh11 + .z=2-4.4 * zi.hh8 + zi.z=#2.62 * 19.hh13=#15 zdati[2]=c:\demo\demo08.1.5 * zi.16 * 14.hh4 + .1.1.1.5 * zi.0 * zi.hh2=#4.4 * zi.hh4 + zi.2.hh1 + .hh10=12.57 * 8.1.hh1 + .hh3=#5.hh7=#9.hh5=#7.emp1 + zi.1.hh13 totemp = zi.23 * 15.hh4 + .hh12 + .1.2 * zi.emp2 phbw = .select=3-1.16 * 13.2 * zi.1.hh9 + zi.hh3 + . p3a=21-25.0 * zi.22 * 4.1.1.1.23 * 14.22 * 8.4 * zi.13 * 19.7 * zi.4 * zi.4 * zi.1.ixcnt=11-15 report zdat=y tothh = zi.hh7 + zi.9 * zi.1.2 * zi.hh9=11.hh6 + .1.22 * 6.1.2 * zi.hh9 + .hh8 + .2 * zi.2 * zi.1.1.13 * 19.4 * zi.select=4-1.1.62 * 16.9 * zi.p4a=31-35 zdati[4]=c:\demo\demo08.61 * 14.hh1 + .62 * 19.1.z=2-4.dat. 03 * 1. V1.25 * 19.Xattr3 for example .2.p[5]..hh12 + .03 * (phbw+phbo+pnhb) pxi = zi.90 * (10. External PA file.08*ahbw + 0.2 * zi.emp2 + tothh) anhb = 1.0.ixcnt p[1]=phbw.1.5 * zi.dat. p[5]=pxi a[1]=0. FILEO PAO[1] = "TRIPENDS. purpose = home based hbp_p = 0.Xattr1. FORM=6.0 * zi.0 * zi.4.p[3].xicnt ahbw = 1.a[3].7 * totemp) ahbo = 1.form=8. Xprod1.11 Generation Program Examples .6 .0 * zi. 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. V254 FILEI ZDATI[2]=zonedata.1. DBF=T.10*ahbo + 0.49 * ( 2.5 * zi.Xprod2.DBF". define trip rates by purposes . V2.2.5*tothh) axi = 0.a[2].a[1].a[4]. These fields could also be fields on your zone data file . P[1] P[2] P[3] A[1] A[2] A[3] . production trip rate per service worker per day 596 Cube Voyager Reference Guide .. dbf data structure is Z.25 * 18.p[1]. production trip rate per industry/agricultural worker per day hbp_s = 0.03*anhb aix = zi..Xattr2.0 * zi.4.25 * 19.dbf .Xprod3.emp1 + 0. p[2]=phbo.. p[4]=pix.92*ahbw a[2]=0. LIST=Z. and we have 3 trip purposes PARAMETERS ZONES=1000 PROCESS PHASE=ILOOP . lets say system has 1000 zones with 901-1000 being the externals . ZDATI[1] as well.emp2 + 0.2 .a[5] ENDRUN Generation example 2 RUN PGM=GENERATION FILEI ZDATI[1]=zonedata.97*anhb a[4]=aix.2.90*ahbo a[3]=0.0 list=z(2).2. production trip rate per person (population) per day hbp_ia = 0.p[4].. .emp1 + 2.1.81 * ( 1.5 .hh11 + .p[2]. dbf data structure is Z.dbf .hh13 pix = 0. p[3]=pnhb. production trip rate per service worker per day schp_r = 0.6 .1 .1 .1.0 . production trip rate per retail worker per day (incl shoppers) nhbp_sc = 0. attraction trip rate per retail worker per day (incl shoppers) hba_sc = 0.1.serv_2002+ per per per per per Cube Voyager Reference Guide 597 .1.95 .3 .15 . production trip rate per person (population) per day schp_ia = 0 .1 .5 . attraction trip rate per person (population) per day scha_ia = 0 . purpose = school schp_p = 0.1. attraction trip rate per industry/agricultural worker day scha_s = 0.1.3 .1.0 .1. attraction trip rate per retail worker per day (incl shoppers) nhba_sc = 0.25 .005 .ret_2002 + hbp_sc*zi. define P/A functions for internal zones . attraction trip rate per person (population) per day hba_ia = 0. attraction trip rate per service worker per day hba_r = 45.95 . attraction trip rate per service worker per day scha_r = 0.pop_2002+ nhbp_ia*zi. attraction trip rate per pupil/student per day .005 . attraction trip rate per pupil/student per day IF (I<=900) . attraction trip rate per retail worker per day scha_sc = 0. attraction trip rate per industry/agricultural worker day nhba_s = 0.inag_2002+ nhbp_s*zi.Generation Program Examples 11 hbp_r = 40. attraction trip rate per person (population) per day nhba_ia = 0.3 .6 .vnames are just the filed names in the dbf file P[1] = (hbp_p*zi.sch_2002) P[2] = (nhbp_p*zi. production trip rate per pupil/student per day scha_p = 0. production trip rate per retail worker per day schp_sc = 0. production trip rate per service worker per day nhbp_r = 12 .1 .serv_2002 + hbp_r*zi.inag_2002 + hbp_s*zi.15 . production trip rate per industry/agricultural worker day schp_s = 0. production trip rate per industry/agricultural worker day nhbp_s = 0. zi.005 . purpose = non-home based nhbp_p = 1. production trip rate per retail worker per day (incl shoppers) hbp_sc = 0. ----. production trip rate per pupil/student per day nhba_p = 1. production trip rate per person (population) per day nhbp_ia = 0.8 .calculate productions per day by purpose . production trip rate per pupil/student per day hba_p = 1. attraction trip rate per service worker per day nhba_r = 14.3 .005 .1.pop_2002 + hbp_ia*zi.1. attraction trip rate per industry/agricultural worker day hba_s = 0. attraction trip rate per pupil/student per day .0 . sch_2002) P[3] = (schp_p*zi.serv_2002 + hba_r*zi.Xattr2 A[3]=zi.1.2.sch_2002) ELSE . 3 .1.3 NHB=2 . adjust zonal attractions so total attractions match total productions BALANCE A2P=1.1.2.calculate attractions per day by purpose .1.1.1.inag_2002+ nhba_s*zi. zi.pop_2002+ schp_ia*zi.serv_2002+ nhba_r*zi.Xprod2 P[3]=zi.1.vnames are just the filed names in the dbf file A[1] = (hba_p*zi.ret_2002+ scha_sc*zi.2.1.1.ret_2002+ nhbp_sc*zi.serv_2002+ scha_r*zi.1. prods set to attrs for purpose 2 ENDPHASE ENDRUN 598 Cube Voyager Reference Guide .pop_2002+ nhba_ia*zi.inag_2002+ schp_s*zi.1.1.ret_2002 + hba_sc*zi. balance attrs to prods for purposes 1.2.1. define P/A for external zones P[1]=zi.1.2.1.2.ret_2002+ nhba_sc*zi.1.pop_2002 + hba_ia*zi.Xattr3 ENDIF PROCESS PHASE=ADJUST .Xprod1 P[2]=zi.1.11 Generation Program Examples nhbp_r*zi.1.1. ----.ret_2002+ schp_sc*zi.Xattr1 A[2]=zi.sch_2002) A[3] = (scha_p*zi.serv_2002+ schp_r*zi.Xprod3 A[1]=zi.1.1.inag_2002+ scha_s*zi.pop_2002+ scha_ia*zi.1.1.inag_2002 + hba_s*zi.sch_2002) A[2] = (nhba_p*zi.sch_2002) . 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 . 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. This section provides an overview of the Public Transport program. and discussing how you can use the program to prepare data and model public transport systems. access. required inputs and generated outputs. egress. and components of costs Cube Voyager Reference Guide 601 . This section also discusses terminology used within this document. network-wide and mode specific. composite and average travel costs.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. or alternatively single best-path routes may be used Demand stratification by user class with variations in the behavior of classes represented by different cost functions Comprehensive fares modeling Preparation of a public transport network for Public Transport’s modeling functionality Generation of the nontransit element of the public transport network (that is. listing the program’s primary capabilities. transfer and park and ride legs) Skimming. select-link/line outputs Reporting of input data. operators. multiple routes with probability of use. lines. line and link loads. model infrastructure. secondary analyses • The Public Transport program requires as input: • • • • • • • A highway or public transport network Public transport system data Line data Fare data Nontransit legs (developed externally or by Public Transport) Generalized cost information Demand The Public Transport program produces: • • • • • • • Nontransit legs Enumerated routes Skim and select-link matrices Loaded lines and nontransit legs Transfer matrices—results of loading analyses A variety of reports of input data and model results A public transport network that can be displayed by Cube and used as an input network for further modeling 602 Cube Voyager Reference Guide . a variety of stop-to-stop movements.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 trips—transfers between modes. the Public Transport model finds “reasonable” or “attractive” multiple discrete routes between zones. nodes and links (that is. operators and wait curves. walk and transit link times. node coordinates. egress from it and transfer between services during the course of a trip. and so forth). considering: Cube Voyager Reference Guide 603 . defining the characteristics of the lines and nodes traversed. produced by Network or Public Transport. presenting opportunities to access the public transport system. You can prepare: • A network. Service or line data. Control information for route enumeration and evaluation. distance. System information used to describe the characteristics of the public transport system such as modes.Public Transport Program Overview 12 Preparing data You can use the Public Transport program to prepare data that supports public transport modeling. • • • • Modeling You can use the Public Transport program to model public transport. The model has several parts: • • • • Route enumeration and evaluation Skimming (levels of service matrices) Loading (assignment) Reporting Route enumeration and evaluation During route enumeration and evaluation. Nontransit legs may be determined externally and/or generated by Public Transport under user control. over which the public transport system operates. containing characteristics of zones. Nontransit legs. the Public Transport model loads demand. Where walk and transit choices are available. where appropriate. fares) Best trip cost • The model can extract network-wide trip costs. scheme evaluation. 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 costs—and the components of costs—of journeys between zones. or the model can stratify them. egress. it also determines the transit share. Loading (assignment) During loading. and transfer points. 604 Cube Voyager Reference Guide . loading demand on the network and producing operational statistics like passenger miles. in the form of trips between zone pairs. demand modeling. These costs are suitable for model validation. nontransit. in-vehicle and wait times. hours and revenue. boarding and transfer penalties. perceived. and actual trip costs and components (that is. 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.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. The model can extract the following skims: • • • Composite costs Value of choice Average. by modes. ” ”lines” and “services” ”transfers” and “interchanges” ”skims” and “levels of service” • • • Cube Voyager Reference Guide 605 .) Two forms of loading are supported.” In particular. multirouting and best-path. namely “transit link” as opposed to “nontransit link. • (Strictly. “transit” is used in this document to describe a type of link over which a public transport service can run. The best-path method does not use walk or alighting choice models.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 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. Reporting During reporting. these models determine the probability of use of the alternative routes. The alternative-alighting model apportions the share of a service to the attractive alternative alighting points of that service. and loads demand using the service-frequency model. trips are then loaded on the routes based upon these probabilities. 12 Public Transport Program Overview • • • • • ”generalized cost” and “generalized time” ”origin-destination pairs.” and “passenger flow” 606 Cube Voyager Reference Guide .” “OD pairs.” “flow.” “load.” “zone pairs.” and “IJ pairs” ”nontransit time” and “walk time” ”loading” and “assignment” ”volume. Cube Voyager Reference Guide 607 .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. within a prescribed hierarchy. Control statements are either static or dynamic. Dynamic statements may be present only within phases. 608 Cube Voyager Reference Guide . You configure the Public Transport program to run through a specific combination of control statements and phases. during the execution of the phases. the program evaluates them once. processes in the blue boxes are performed separately for each class. Static statements may be present anywhere in the job stream. Public Transport program processes and associated phases (With multiple user classes.) See “Phases” on page 641 for a description of the phases in the Public Transport program. the program evaluates them as encountered.12 Public Transport Program Processes You control the main processes and their associated phases. and control information. nontransit leg. node. The DATAPREP phase is mandatory for public transport network development. and link information are taken from networks produce by the Network program. do not code empty phases. public transport system data. and control data. Network development During network development. However. line. Either the Network program or the Public Transport program can produce the input network. 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. The phase provides the control statements for nontransit leg generation and/or input. you must provide public transport system. Cube Voyager Reference Guide 609 . Only code phases that contain control statements. only zone. the description of each phase lists valid control statements (see “Phases” on page 641). This includes stringent validation and consistency checks to ensure that the different components of the public transport network are compatible. lines.Public Transport Program Processes 12 Only context-sensitive dynamic control statements are available to the phases. which may be saved with LINEO. The legs are in the format specified by the NT control statement. route evaluation. See “Public transport network development” on page 876 for examples of this task. skimming. input with NETI Public transport system data. 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. Inputs required for Public Transport network development • • • • A network. which may be saved with LINKO. If trips are loaded in the run creating the public transport network. The saved Public Transport network may be used in subsequent runs of the Public Transport program for route enumeration. except for route-enumeration and route-evaluation control information. The lines are in the format specified by the LINE control statement. input with SYSTEMI One or more lines files. all output files can optionally contain the results of the loading. optionally. in DBF format. loading and loading analyses. The Public Transport network is made available to any other processes in the job stream that require it.12 Public Transport Program Processes The components of the public transport network are common to all user classes. A table of links and their attributes. A text version of the lines in the public transport system. nontransit legs input with NTLEGI[#] • • Outputs produced by Public Transport network development • • • • A public transport network. produced by Network or Public Transport. which may be saved with NETO. which may be saved with NTLEGO. which may be provided separately for each class. It contains all 610 Cube Voyager Reference Guide . Nontransit legs (generated and input). input with LINEI[#] Control information for route enumeration and route evaluation. However. You can use Cube to display but not edit the Public Transport network. You can save an enumerated routes file and input the file to a subsequent run with ROUTEI. the Public Transport program identifies sets of discrete routes between zone pairs. so allowing it to vary between program runs. which you control with the FACTORS statement. Public Transport enumerates routes for all zone pairs. When modeling multiple user classes.Public Transport Program Processes 12 information required for these processes apart from fares data which may optionally be read later. provide separate FACTORS statements for each class to produce enumerated route files for each class. which have some probability of being used by passengers to travel between the zones. This set of discrete routes may be pruned at the route-evaluation stage. Cube Voyager Reference Guide 611 . By default. Associated phases • DATAPREP (mandatory) Route enumeration During route enumeration. Route enumeration is a heuristic process. A ROUTEO file in the job stream invokes route enumeration. you can use ROUTEI and ROUTEO statements to select zone pairs separately for route enumeration and reporting. in compliance with further user specified controls. at the minimum. at every decision point along the route 612 Cube Voyager Reference Guide . Outputs produced by Public Transport route enumeration • An enumerated routes file. For multiple user classes. enumerated routes files. ROUTEO. the Public Transport program: • • • • Examines enumerated routes Eliminates any illogical ones that have crept in due to network simplification Disaggregates bundled routes. ROUTEO[#]. can be examined through a series of reports specified on the REREPORT statement. The line data is converted into transit legs and the network data into nontransit legs. where appropriate Identifies routes that have. The simplified network.12 Public Transport Program Processes See “Route-enumeration process” on page 820 for theory about route enumeration. Associated phases • None Route evaluation During route evaluation. 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. Inputs required for Public Transport route enumeration • A public transport network file. the data is organized in a highly compressed form for processing and storing routes. or produced previously and input with NETI. produced either by the current run of the Public Transport program. which is described in “Network simplification” on page 808. a user specified probability of use or more. they are evaluated as required. and loading-analyses processes.Public Transport Program Processes 12 The route-evaluation process is a prerequisite for the skimming. (Enumerated routes produced by an earlier run may be input with ROUTEI for evaluation or generated by specifying a filename with ROUTEO. 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. (For multiple user classes. select-link. Indeed. • NOTE: Any previously built NETI and ROUTEI files that you input must be compatible. This is because only enumerated routes are saved. but not saved. Produced for each zone pair.) Evaluated routes may be reported with ROUTEI and ROUTEO. but described separately. loading. Fares data may be read directly into a route-evaluation run. as they report on different aspects of the Public Transport model. Cube Voyager Reference Guide 613 . Inputs required for Public Transport route evaluation • • A public transport network file. and loading-analyses processes are performed on the fly. select-link. produced either by the current run of the Public Transport program. The skimming. these are by-products of the route-evaluation process. or produced previously and input with NETI. Can be reported by zone pair. loading. enumerated routes files input with ROUTEI[#]). Selecting one or more of these processes automatically invokes the routeevaluation process. produced either by the current run of the Public Transport program. or produced previously and input with ROUTEI. See “Route-evaluation process” on page 826 for the theory supporting route evaluation. A route file. see “Skimming — Quick reference” on page 625 for a quick reference to the skimming functions. either in the MATO phase or outside the Public Transport program. The skimming process produces skim (level of service) matrices of total trip costs and their components. See “Public transport skimming” on page 881 for examples of this process. Skimming is also described in “Skimming process” on page 839. 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 . set to zero. from the information generated by route evaluation. for modeling demand. and the cells for unconnected IJ pairs.12 Public Transport Program Processes Associated phases • • MATI SELECTIJ Skimming (level of service) This section describes skimming in detail. These can be reset to large values. you can produce skims for each class from the individual enumerated route files. NOTE: All skim matrices have their intrazonal cells on the diagonal. When modeling multiple user classes. either produced by the current run of the Public Transport program. produced either by the current run of the Public Transport program. Each skim function has a name and one. MATO[#]). the files must be compatible. Outputs produced by Public Transport skimming • • A matrix file. which may be saved in the file designated by LINKO. 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. or produced previously and input with ROUTEI (for multiple user classes. two or no arguments. NOTE: If previously built files are input with NETI and ROUTEI. A table of links and their attributes. in DBF format. and is specified as follows: • • • SkimName(Arg1) SkimName(Arg1. MATO (for multiple user classes. A route file. matrix files. enumerated routes files input with ROUTEI[#]). Arg2) SkimName where: Cube Voyager Reference Guide 615 . 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. or produced previously and input with NETI.Public Transport Program Processes 12 Overview Inputs required for Public Transport skimming • • A public transport network file. the attribute skimmed is the total for the zone pair.7. So. The arguments in skim functions are evaluated as expressions. If Arg1=0. This could also be written as 1.4. MW[7] will contain a DIST skim for mode 1. the extracted skim is for the specified route set.12 Public Transport Program Processes • SkimName includes an explicit prefix. setting Arg1 to zero or one will produce the same result.5 would produce one skim for modes 1 through 5. Combinations such as 1. if Arg1>0. For example. Note that range specification for skim functions is different from the standard specification for Cube Voyager.3.9. 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.-5. Example 1: Shows how skims requiring one argument are invoked.-12 are valid. Therefore. • Arg2 is a list of modes for which the skim is required.-5. or a default. the skim for the route set which is also the overall skim for the OD pair (route set).2. the standard way of specifying ranges. The second argument is a single number or a list of single numbers and pairs specifying ranges.3. MW[8] will contain a TIMEA skim for 616 Cube Voyager Reference Guide . Arg2=1-5 would result in Arg2=-4. Example 2: Shows how skim functions requiring two arguments are invoked. MW[2]=COMPCOST(0) MW[3]=ValOfChoice(0) MW[4]=IWAITA(0) Currently only one route set is produced. Arg2= 3 would provide a skim for mode 3 while Arg2=1. 1) MW[8] = TIMEA(0. MW[7] = DIST(0. Here.9. the parenthesis () should not be coded.TMODES) MW[13] = TIMEP(0. TMODES or NTMODES (case insensitive).31.31. MW[11] = TIMEP(0.Public Transport Program Processes 12 modes 1.11.33 which are nontransit modes.8.32. MW[9] for modes 1. Example 3: Shows an alternative method for invoking skim functions requiring two arguments.8. MW[9] for transit modes and MW[10] for nontransit modes. MW[8] will contain a TIMEA skim for all modes.7.11 which happen to be the transit modes in the system and MW[10] for modes 31. an alternative way to specify Arg2 is ALLMODES.1.7. Example 4: Shows how a skim function requiring no arguments is invoked.31.7. 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 .ALLMODES) MW[12] = TIMEP(0.-9.NTMODES) • Where a skim requires no arguments.11) MW[10] = TIMEA(0.9.1.-33) If skims are required for all.-9.11.7.32.-33) MW[9] = TIMEA(0. transit or nontransit modes.and 33. MW[14] = BESTJRNY Subsequent sections describe the types of skims that can be extracted and their contents. Arg2 is text rather than a list. assigned to nodes by IWAITCURVE keyword. 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. or. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement. 618 Cube Voyager Reference Guide . weighted by the WAITFACTOR keyword. The additional wait time occurs when unable to board a service (so needing to wait for the next one) and at the end of modeled period (where demand exceeds capacity causing a bottleneck). from a default wait curve. for nodes that have not been assigned one. Actual transfer wait time XWAITA(RouteSet) Computes the average actual wait time incurred at the transfer points of all “attractive” routes between zones. from a default wait curve. assigned to nodes by the XWAITCURVE keyword. 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. for nodes that have not been assigned one.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. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement. or. this skim computes the average in-vehicle run time for all “attractive” routes between zones. Perceived initial wait time IWAITP(RouteSet) Computes the average actual time incurred at the start of the trip for all “attractive” routes between zones. or. or. weighted by WAITFACTOR. Mode) For transit modes. for nodes that have not been assigned one. for nodes that have not been assigned one. 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. Cube Voyager Reference Guide 619 . It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement. from a default wait curve. weighted by WAITFACTOR. from a default wait curve. factored by any line specific factors. It is taken from the network link data. assigned to nodes by XWAITCURVE.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). It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement. Perceived transfer wait time XWAITP(RouteSet) Computes the average actual time incurred at the transfer points of all “attractive” routes between zones. assigned to nodes by IWAITCURVE. it is taken from the network link data and factored by any line specific factors. For nontransit modes. egress and transfer) for all “attractive” routes between zones. TIMEP. This component of cost is included in the perceived travel time skim. so care should be taken to avoid double-counting. and RUNFACTOR. It is taken from the nontransit legs generated or read in by the GENERATE statements and factored by RUNFACTOR. It is taken from the nontransit legs generated or read in by the GENERATE statements. this skim extracts the average in-vehicle run time for all “attractive” routes between zones. As a perceived data skim. this skim computes the average nontransit time (access. Mode) For transit modes. 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. Mode) For transit modes. RUNFACTOR and crowding factor. Penalty skim functions This section describes penalty skim functions: • • • Actual transfer penalty Perceived boarding penalty Perceived transfer penalty 620 Cube Voyager Reference Guide . this skim extracts the average additional invehicle run time for all “attractive” routes between zones. Perceived crowded link travel time CWDCOSTP(RouteSet.0. this skim extracts the average nontransit time (access. egress and transfer) for all “attractive” routes between zones. Perceived travel time TIMEP(RouteSet. It is taken from the network link data and factored by any line specific factors.12 Public Transport Program Processes For nontransit modes. Perceived boarding penalty BRDPEN(RouteSet. It is calculated from the fare systems used by the “attractive routes. in monetary units. Perceived transfer penalty XFERPENP(RouteSet. for all “attractive” routes between zones. It is taken from XFERPEN. Mode) Cube Voyager Reference Guide 621 . It is the actual penalty as coded in XFERPEN.” Fares are calculated either by transit leg or for a sequence of legs. Mode) Extracts the average actual transfer penalty for all “attractive” routes between zones. in the latter case the fare is apportioned to the legs in proportion to leg distance. Mode) Counts the boarding penalties associated with transit legs of the trip.Public Transport Program Processes 12 Actual transfer penalty XFERPENA(RouteSet. Generalized cost units FAREP(RouteSet. weighted by XFERFACTOR with XFERCONST added. Mode) This skim is the average perceived transfer penalty for all “attractive” routes between zones. Fare skim functions This section describes fare skim functions: • • Monetary units Generalized cost units Monetary units FAREA(RouteSet. Mode) Extracts the average fare. 12 Public Transport Program Processes Extracts is the average fare. in the latter case the fare is apportioned to the legs in proportion to leg distance. for all “attractive” routes between zones. The fare is calculated as for skim FAREA. Fares are calculated either by transit leg or for a sequence of legs. at each decision point. from the fare systems used by the “attractive routes. in generalized cost units.” and converted into generalized cost units with mode specific VALUEOFTIME. 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. 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 . the best choice is taken). Composite cost COMPCOST(RouteSet) Measures the perceived costs of travelling between zone pairs using all “attractive” routes. It is taken directly from the network link data. Mode) Extracts the average distance travelled by the “attractive” routes between zone pairs. Boardings BRDINGS(RouteSet. 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 number of boardings used by the “attractive” routes between zone pairs. walk or alighting). Cube Voyager Reference Guide 623 . It takes into account all choices available at decision points (for example.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. and is appropriate for use in demand modeling and the evaluation of schemes. It highlights where the public transport system is unable to satisfy the demand flows which are being loaded. This skim is only available when crowd modeling is performed. 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. The EXCESSDEMAND skim only gives cell values where demand exists and bottlenecks prevent it reaching the destination. and wait time adjustments are used. These trips would need to wait till beyond the modeled period before being able to board their next transit leg. It is only available when crowd modeling is performed. and wait time adjustments are used. 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. and no viable alternative route is available. 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).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. 624 Cube Voyager Reference Guide . 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 . ALLMODES)+ XFERPENP(0. Mode) FAREP(RouteSet.Public Transport Program Processes 12 Sample calculation: ValOfChoice(0) = ((IWAITP(0)+ XWAITP(0)+ TIMEP(0. ALLMODES)+ BRDPEN(0. Mode) EXCESSDEMAND EXCESSPROP FAREA(RouteSet. Summary of skim functions Function BESTJRNY BRDINGS(RouteSet. See “Skimming (level of service)” on page 614 for a detailed description. Mode) COMPCOST(RouteSet) CWDCOSTP(RouteSet) CWDWAITA(RouteSet) CWDWAITP(RouteSet) DIST(RouteSet. 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. Mode) BRDPEN(RouteSet. Demand may be stratified by user class and loaded to enumerated routes generated either by class or for the whole Public Transport network. to the attractive routes between zone pairs. Mode) TIMEP(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. Loading is invoked by assigning. in the form of trips. 626 Cube Voyager Reference Guide .12 Public Transport Program Processes Summary of skim functions (continued) Function TIMEA(RouteSet. the Public Transport program assigns passenger demand. Mode) ValOfChoice(RouteSet) XFERPENA(RouteSet. either input or generated trip matrices to TRIPSIJ[#]. or trips for individual zone pairs to the variable TRIPSIJ in the SELECTIJ phase. 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. in ASCII format. 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. may be reported with the REPORT statement. Inputs required for Public Transport loading • • Public Transport network file. enumerated routes files input with ROUTEI[#]). or computed during the run (for multiple user classes. This network may be displayed by Cube but not edited. trip matrix files input with MATI[#]). which may be saved in the file designated by LINKO. which may be saved in the file designated by NTLEGO.Public Transport Program Processes 12 The results of loading. including loads. which may be saved in the file designated by NETO. which may be saved in the file designated by LINEO. either produced by the current run of the Public Transport program. produced either by the current run of the Public Transport program. in DBF format. • Trips for loading onto the routes These may be input as a trip matrix with MATI. or produced previously and input with ROUTEI (for multiple user classes. Loaded lines. in ASCII format. they must be compatible. Route file. Outputs produced by Public Transport loading • A loaded Public Transport network with transit and nontransit loads. NOTE: If previously built NETI and ROUTEI files are input. passenger flows on lines. See “Public transport loading” on page 883 for an example of this function. or produced previously and input with NETI. • • • Associated phases • MATI Cube Voyager Reference Guide 627 . Loaded nontransit legs. A table of link and their attributes. See INTERCEPTO and SCREENLINEO in “FILEO” on page 708 for more information. A route file. produced either by the current run of the Public Transport program. matrix files. You can also use Cube Analyst to estimate Public Transport demand matrices. When you model multiple user classes. enumerated routes files input with ROUTEI[#]) NOTE: If you input previously built NETI and ROUTEI files. they must be compatible. Lines may be identified explicitly or selected based on their mode 628 Cube Voyager Reference Guide .12 Public Transport Program Processes Select link During the select-link process. or produced previously and input with NETI. or produced previously and input with ROUTEI (for multiple user classes. either produced by the current run of the Public Transport program. this process can produce select link outputs for each class from the individual enumerated route files. Inputs required for Public Transport select link • • A public transport network file. and can also perform select-link loading. 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. the Public Transport program produces output matrices of demand matching selection criteria. or nodes in the network. Outputs produced by Public Transport select link • • A matrix file. lines. MATO (for multiple user classes. MATO[#]) Loadings. In a run. The select-link criteria are defined as expressions. which allows compound conditions (using and / or / not operations) to be specified. These allow you to obtain results when demand flows for an I-J pair are zero. The select-link function outputs a matrix. or passing the node. The general form of the select-link function is: SELECTLINK (expression) where the expression defines the selection criteria. However. You can save the resulting matrices to the FILEO MATO[n] where n is the user class being evaluated (that is. The process normally considers just transit legs using the link/line. The demand flows loaded onto the network may be restricted to just that demand which meets the selection criteria. Where several select link functions are used in a run only one of them may contain the keyword which triggers select-link based loading. boarding a transit line). each one being associated for output purposes with a different working matrix. You may specify additional keywords in the expression to obtain either percentage or proportion of demand (rather than actual demand flow) satisfying the criteria. or for nodes the activity may be restricted to specific movements (for example. This permits the display of demand and loadings which use the selected link. select link results are saved to the same matrix file as skim outputs). containing that demand which satisfies the selection criteria. 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. if required nontransit legs may be considered.Public Transport Program Processes 12 or operator attributes. 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 . you may specify a series of selection criteria. 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. or obtained from scenario keys (by substitution into the script). working variables or results of COMP commands may not be used to specify values which form part of a selection expression. As a general rule. The values required by the user must be specified directly in the script. the expression takes the form L = ANode-BNode 630 Cube Voyager Reference Guide . Where no route is found for an I-J pair all select link functions will return zero values.12 Public Transport Program Processes MW[MatrixNumber] = SELECTLINK (expression) The compute command is coded as part of the SKIMIJ phase. Cube Voyager Reference Guide 631 . the expression takes the form: LINE = LineName Use of two or more line names in a list is permitted. The expression used may contain a list of link specifications. 104-105*. 107-109) selects demand if one of the links 101 to 102. whereas: MW[2] = SELECTLINK(L=1025-1028*) selects demand traveling along the link in either direction. and may be replaced by a space character.” For example: MW[3] = SELECTLINK(L=101-102. The use of comma between link specifications is optional. 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. using any one of the links turns the selection criterion to “true.Public Transport Program Processes 12 This identifies all demand traversing the link in the direction from the given A-node to the B-node. which are separated by commas (or alternatively spaces). 104 to 105. Selection criteria which require the use of two or more links are described below. If a list is defined. 105 to 104 or 107 to 109 is on the path. Select line To select demand using a particular line. and when used the selection criteria is true if any one of the listed lines is used. For example: LINE = MUNI-?? would match line names MUNI-01 and MUNI-02. and ranges of nodes may be specified using ‘-‘. MUNICENTRAL.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. Use the “?” for single characters. Select node To select demand passing through a particular node. Examples: MW[1] = SELECTLINK(N=107.12 Public Transport Program Processes Line names may contain masks of a single trailing “*” or one or more trailing “?. For example: LINE = MUNI* matches line names such as MUNI. the expression takes the form: N=NodeNumber Lists of nodes may be used. MW[2] = SELECTLINK(LINE=A*. and MUNINORTH. Examples: MW[1] = SELECTLINK(LINE=RED1) selects demand using the line which has name RED1. or finish at the specified node(s). Use the “*” for multiple columns. B*) selects lines with names beginning with either A or B. 632 Cube Voyager Reference Guide . pass through.” The leading nonmasked portions will then be compared for selection purposes. 5. Tests using not equals (!= or <>) are permitted with operator conditions. 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. The use of | (or) operators may sometimes be avoided when the same data type is referred to in both tests.Public Transport Program Processes 12 Select mode To select demand which uses a particular mode.7. The example: Cube Voyager Reference Guide 633 . For example: MW[5] = SELECTLINK(MODE=3. Use the “and” operator (& or &&) and “or” operator (| or ||) to combine simple conditions. Select operator To select demand which uses lines from a particular operator. Lists and ranges may be used when specifying the required modes.7-9) selects demand which uses any of modes 3. Tests using not equals (!= or <>) are permitted with mode conditions.5. Example: MW[7] = SELECTLINK(OPERATOR=3) selects all demand on lines run by the operator having an identification number of 3. the expression takes the form: OPERATOR = Number Lists and ranges of numbers may be used when specifying the required operators. Combining selection criteria together You can combine two or more select-link criteria to form compound conditions.8 or 9. Again. consider how you might combine a test on a link with a test on a line. which is used first does not matter. In evaluating this test it does not matter which of the links is traversed first. When combining tests using two data types it is also necessary to consider how the conditions interrelate. 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). 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. it is use of both of them which sets the selection to “on. and such conditions are considered in the following section.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. 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. Alternatively the requirement may be that the line was used to traverse the specified link. use of the “and” operator is appropriate. For example: MW[6] = SELECTLINK(L=211-234 & LINE=GREEN) treats the two conditions as independent tests. this is a “simultaneous condition” where two or more conditions must all apply at one point in the trip. 634 Cube Voyager Reference Guide . Where the selection criteria are independent.” In a similar manner: MW[4] = SELECTLINK(LINE=RED2 & LINE=BLUE7) selects demand which uses both line RED2 and also line BLUE7. 421-422) Two tests based on link-selection criteria may readily be combined using the “and” operator. These conditions are independent of each other. As an example. or operator conditions Node conditions with line.Public Transport Program Processes 12 Using simultaneous selection criteria Where two conditions apply simultaneously the operator. When using negated tests with line conditions. The use of brackets around each simultaneous condition is optional. For example. the condition LINE != RED means “used lines other than RED. mode. then this condition would be true as some line other than RED is used on the second leg. The “not equals” operator (!= or <>) is not permitted in link or node expressions (that is. and may be omitted without affecting the results. Such simultaneous conditions are combined together before any “&” and “|” operators are evaluated. L or N expressions). it is often appropriate to use an expression of the form !(LINE=RED) which means “did not use line RED. 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. mode. Cube Voyager Reference Guide 635 . 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. brackets ease reading of the condition groups. use “+” to combine them.” If considering a two-leg trip where line RED used on the first leg. The “+” operator is typically used to combine: • • • Link conditions with line.” Use of “not equals” may give results which do not exactly match your intentions. For conditions using node selection (that is. allowing the selection criteria to consider particular types of movement. unless mode selection criteria have been specified. 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. For conditions using link selection (that is. These are specified in the select link expression by a TYPE keyword (which is usually part of a simultaneous condition. The following examples illustrate use of the TYPE keyword: 636 Cube Voyager Reference Guide .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). • • 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. You can amend this default behavior. The TYPE keyword may not be followed by a “notequals” (!= or <>) operator. The condition may use a list of two or more of these settings to select movements where any of the listed types apply. linked by “+” operator to the associated link or node condition). L= conditions) the TYPE keyword can take either of the following values. The TYPE keyword may not be followed by a “not-equals” (!+ or <>) operator. The proportion of demand meeting the criterion may be obtained by including the PROBABILITY keyword in the expression (that is.Public Transport Program Processes 12 • MW[1] = SELECTLINK(L=101-102 + TYPE = NTINCLUDED) Selects all journeys travelling along link 101 to 102. or egress from the public transport system to reach a destination zone. Cube Voyager Reference Guide 637 . As an example: MW[3] = SELECTLINK(LINE=TRAM1. PROBABILITY=T ). walking). following that they may board another line there. 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. PERCENT=T ). percentages may be obtained by using the PERCENT keyword (that is. walk to another node to board a line. • MW[2] = SELECTLINK (N=123 + LINE = X + TYPE = BOARD) Selects just the demand boarding line X at node 123. they make an interchange between lines at that node). • MW[5] = SELECTLINK(N=579 + TYPE = THRU. Similarly.ALIGHT) Selects all transit demand arriving at node 579 (whether they alight or continue on the line). • MW[2] = SELECTLINK((N=123 + TYPE=ALIGHT) & (N=123 + TYPE=BOARD)) Selects all journeys which both alight and board at node 123 (that is. PERCENT=T) Returns percentage values for each I-J pair which use the line TRAM1. whether using a transit line or nontransit (for example. • MW[2] = SELECTLINK(N=123 + TYPE=ALIGHT) Selects all journeys which alight at node 123. only one of these may be used to trigger select-link loading. then the skims are obtained for all evaluated routes (that is. As with the loading process. the Public Transport program presents further reports of transit and nontransit passenger loadings than those performed during the loading process. As an example: MW[2] = SELECTLINK(L=303-307*. Any request for loading analyses automatically invokes a loading process. The analyses currently available are: • • • Transfers between modes Transfers between operators Stop-to-stop movements 638 Cube Voyager Reference Guide . so the crowding is based on complete loadings. LOAD=T) Although a program run may include several SELECTLINK functions. the restriction using selection criteria applies to the last iteration. demand stratified by user class produces loading analyses for each class. rather than loading the entire demand as specified by the parameter TRIPSIJ. If skims are obtained when performing select-link loading. This is invoked by including the keyword and setting LOAD=T in the select link expression. Where crowding is modeled. Loading analyses During the loading-analyses process. they are not restricted to the subset of routes which match the select link criteria). Loading analyses are associated with the MATI phase.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. Crowd modeling During the crowd-modeling process.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. the program completes the route-evaluation and loading processes. 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. At each iteration. You can save this analysis to a DBF file with FILEO STOP2STOPO. either for a selection of stops. which are repeated for all user classes. the Public Transport program iteratively balances loaded demand against capacity. of the crowd modeling procedures: • • Link travel time adjustment Wait time adjustment Cube Voyager Reference Guide 639 . The iterative process may use either. or both. and then adjusts the costs in the model to reflect the assigned loads. printed reports. the results obtained from the last iteration (in the form of loaded flows.12 Public Transport Program Processes See “Crowding” on page 857 for information about the theory of crowding models. 640 Cube Voyager Reference Guide . and skims) provide the model outputs. When crowd modeling is performed. the program evaluates them as encountered. MATI. the program evaluates them once. generally in working matrices. Control statements provide information and instructions to the program. during the execution of the phases. Static statements may be present anywhere in the job stream. In the Public Transport program. are: • • • • • • • NODEREAD — Computes node based variables. and are secondary to the main functions of the Public Transport program. MATI — Computes trips for loading. control statements are either static or dynamic. saving them. DATAPREP — Prepares the public transport network for modeling. You specify the exact configuration for the Public Transport program to run through a combination of phases and control statements. Dynamic statements may be present only within phases. MATO — Manipulates and reports skim. and loading-analyses matrices. presented in the order they would normally be implemented. LINKREAD. and MATO phases provide data manipulation facilities. Cube Voyager Reference Guide 641 . They are optional. context-sensitive computations within them. select-link.Public Transport Program Phases 12 Phases The Public Transport program executes its main processes—data processing and modeling—within a series of phases. The NODEREAD. LINKREAD — Computes link based variables. The phases. You control all the phases and can initiate additional. SELECTIJ SKIMIJ — Extracts skims and select link results. End of GENERATE ENDPHASE Regardless of the functionality selected for any run of the Public Transport program. . Specify phases in a script as follows: PHASE=DATAPREP . You only must code phases that contain control statements. See “Control statements” on page 653 for more information. no user intervention is required. ... a list of valid statements is provided with the description of each phase. This is read and set up at the start of each run. is always input...Generate access/egress legs GENERATE . 642 Cube Voyager Reference Guide .12 Public Transport Program Phases Only context-sensitive dynamic control statements are available to the phases. basic or public transport. a requirement is that a network. you need not code empty or null phases. 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 . XplusY = NI.” An example of a computed node variable is: NW. Input node variable names must have the case insensitive prefix “ni.Y Computed variables are available for the duration of the run but not saved back to the network. numeric or string.12 Public Transport Program Phases NODEREAD In the NODEREAD phase. This information is for use primarily in the DATAPREP phase but is available in later phases if the DATAPREP phase is active. Only one NODEREAD phase is permitted per run. and node based variables from the input network. Vectored variables have the case insensitive prefix “nw. See “Example 2: Preparing a public transport network from TRIPS link data” on page 878 for an example of this phase. you can compute node-based information from the input network’s node attributes with NETI.” The evaluated expression may contain any valid variables. The computed variables may be scalars or vectored by node. Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO 644 Cube Voyager Reference Guide . The use of a vectored variable produces an array containing a computed value for each node. The control statements within the NODEREAD phase are executed once per node.X + NI. . you can compute link-based information from the input network’s link attributes with NETI. Only one LINKREAD phase is permitted per run. Control statements available in this phase ABORT Cube Voyager Reference Guide 645 .Public Transport Program Phases 12 IF.” An example of a computed link variable is: LW. ENDLOOP PRINT Public Transport variables available in this phase ZONES LINKREAD In the LINKREAD phase. The use of a vectored variable produces an array containing a computed value for each link. See “Example 2: Preparing a public transport network from TRIPS link data” on page 878 for an example of this phase.. and node based variables from the input network... Vectored variables have the case insensitive prefix “lw..” The evaluated expression may contain any valid variables. numeric or string. ELSEIF ..Time * 1.5 Computed variables are available for the duration of the run but not saved back to the network. ENDIF LOOP . This information is for use primarily in the DATAPREP phase but is available in later phases if the DATAPREP phase is active.GCTime = LI.. ELSE .. The control statements within the LINKREAD phase are executed once per link. Input link variable names must have the case insensitive prefix “li. The computed variables may be scalars or vectored by link. or you can produce them externally to the Public Transport program and input them in this phase.. ENDIF LOOP ..12 Public Transport Program Phases BREAK COMP CONTINUE EXIT GOTO IF.. ELSE .. See “Public transport network development” on page 876 for examples of this phase... You can compute data for nontransit leg generation from the input network with the COMP statement.. 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. ELSEIF .. You can develop nontransit legs with one or more GENERATE control statements. Control statements available in this phase ABORT BREAK 646 Cube Voyager Reference Guide . . ENDIF LINKLOOP . although COMP statements can also compute working matrices. Cube Voyager Reference Guide 647 . and loading analyses processes are done for each zone pair. and the matrix indicates that there is no highway access for zone I. one row at a time.#.... if MATI points to a highway network matrix.. ENDLINKLOOP LOOP . I-J. (MW[#]).. ELSE . from FILEI MATI matrices (MI. ELSEIF . you might set a variable for zone I and test in the SELECTIJ phase.. ENDLOOP PRINT Public Transport variables available in this phase ZONES MATI The MATI phase produces working matrices. loading. You might use this phase to: • Examine the matrix input with FILEI MATI. This phase provides a flexible mechanism for generating and manipulating one row of a matrix at a time.Public Transport Program Phases 12 COMP CONTINUE EXIT GENERATE GOTO IF. and determine if there is anything specific about zone I that could affect further processing for that zone.name). skimming.... I. For example. before the route evaluation. The MATI phase is executed for each origin zone. but for a zone pair at a time. ENDLOOP PRINT PRINTROW 648 Cube Voyager Reference Guide . you can use the MATI phase to select zones for processing... from an origin zone (I) to all zones (J).... report. You can also do this in the SELECTIJ phase. ELSE . You can merge highway skims with • skims extracted in the Public Transport program run.12 Public Transport Program Phases • Compute a row of trips. and then manipulate. and save the trips in a working matrix.. ENDIF JLOOP . Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF. for subsequent loading. The working matrix may be reported with the PRINTROW statement. MW[#]. ELSEIF . ENDJLOOP LOOP . using the COMP statement and the built-in ROW functions... See “Public transport loading” on page 883 for an example of this phase... Input matrices external to the Public Transport program with FILEI MATI. and save those matrices with FILEO MATO. With the BREAK statement. The working matrix is designated for loading with PARAMETERS TRIPSIJ[userclass]. The ROUTEI and ROUTEO subkeywords I. The Public Transport program executes the SELECTIJ phase prior to the route-evaluation process for the I-J pair.J. J. This phase can compute the trips to be loaded for each I-J pair. The SELECTIJ phase allows a finer selection of specific I-J combinations. 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.1. For example: PHASE=SELECTIJ if(I < 10) CONTINUE if(J > 10) BREAK TRIPSIJ=MI.TRIPSIJ ENDPHASE In this fragment of code.75 PRINT LIST=I. loading. and SELECTBYMAT provide the first line of selection but they do not control specific I-J combinations. for bypassing the route-evaluation process. I-J. although if the I-J combination is precluded by the values on the ROUTEI and ROUTEO. 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. (Route evaluation is a time consuming process. Cube Voyager Reference Guide 649 . and loading analyses processes.Public Transport Program Phases 12 Public Transport variables available in this phase ZONES USERCLASS I J SELECTIJ The SELECTIJ phase selects pairs of zones. that I-J pair is not available to this phase.1 * 0. immediately after route evaluation... See “Public transport skimming” on page 881 for an example of this phase. then saves them. ELSE .. 650 Cube Voyager Reference Guide . ELSEIF ..12 Public Transport Program Phases Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF. 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.. The Public Transport program invokes SKIMIJ for each zone pair.. generally in working matrices with the COMP MW[#] statement. I-J. you use the MATO phase with the matrices produced by the skimming and loading analyses phases. Generally. but you can also process other working matrices similarly.. you can use the MATO phase to select zones for processing. skimming. and loading analyses processes for all destination zones of that origin zone.. With the BREAK statement. See “Public transport skimming” on page 881 for an example of this phase. You can manipulate matrices with the COMP statement and a set of built-in ROW functions.. reports and writes work matrices to the FILEO MATO files. combines. and create a report with the PRINTROW statement. ENDJLOOP LOOP . loading. Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF. ELSE ...Public Transport Program Phases 12 MATO In the MATO phase.. ELSEIF .. after completing the route evaluation. I.. The program executes this phase once for each origin zone.. ENDLOOP PRINT PRINTROW Cube Voyager Reference Guide 651 . the Public Transport program revises. ENDIF JLOOP .. 12 Public Transport Program Phases Public Transport variables available in this phase ZONES USERCLASS I J 652 Cube Voyager Reference Guide . Some are specific to this program while others are available throughout Cube Voyager. MODE. • The control statements available in the Public Transport program are listed below.. FACTORS).. The Public Transport program has two types of control statements: • Static — Evaluated only once. 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 .Public Transport Program Control statements 12 Control statements Control statements provide instructions and information to the Public Transport program. Citilabs recommends keeping static control statements together at the beginning of the script file. at the start of each run.. PRINT. Some static statements are provided in files.. see each phase’s description in “Phases” on page 641 for a list of valid statements. ENDJLOOP. Dynamic — Evaluated as encountered. JLOOP . Examples of static control statements include FILEI. PARAMETERS. FILEO. LINE. Phases only permit contextsensitive control statements. GENERATE. not in the job script (that is. These may only be present in the processing phases. regardless of their location in the script. Examples of dynamic control statements include LINKLOOP . ENDLINKLOOP. and REREPORT. . ELSEIF ... ELSE .... 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... ENDJLOOP LINE LINKLOOP .. ENDLINKLOOP LOOP . 654 Cube Voyager Reference Guide ...12 Public Transport Program Control statements Control statement GENERATE GOTO IF. ABORT MSG = text ABORT keyword Keyword MSG |S| Description Optional. ENDIF JLOOP .. Message printed when the program terminates. WalkSpeed <= 0 || lw. the script reports the links and aborts the run with an appropriate message. If BREAK is within a LOOP .. the script terminates processing for the I zone but does not bypass output and zonal reporting statistics.. If BREAK is not within a LOOP or JLOOP block.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 . control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1).a <=24 || li.Generate access legs only if walk costs coded on links GENERATE. this script checks that the speed of links that may be used for walking is between 0 and 5 km/h. li.0 )) LnkCnt=LnkCnt+1 print list=li.. ENDJLOOP block. PHASE=DATAPREP LnkCnt = 0 LINKLOOP if((li..b <=24) && (lw.b. If the script finds links outside this range. Cube Voyager Reference Guide 655 . Upon encountering BREAK. ENDPHASE BREAK Breaks out of a loop.WalkSpeed > 5. ENDLOOP or JLOOP ..Public Transport Program Control statements 12 Example Before generating access and egress legs in the DATAPREP phase.a.. lw.. the script immediately passes control to the statement after the associated loop. Example 1 Loop terminates if “condition 1” is not met. skimming. and loading-analyses processes are completed for loop J within loop I. regardless of the value of L1.3 IF (condition 1) statements ELSE BREAK ENDIF ENDLOOP IF (condition 2) BREAK Example 2 MATI selects zones 1 to 19 for processing. Therefore. The route-evaluation. the processes will run for zone 20 but will not save any matrices produced. LOOP L1=1. ignoring all other zones.1. control passes to the following IF statement and processing for zone I ceases. PHASE=MATI IF(I==20) BREAK MW[1] = MI. loading. Therefore. skimming. loading. breaks out of the I-loop. enabling no further processing. and saving matrices to file.1 ENDPHASE Example 3 MATO selects zones 1 to 19 for reporting.) PHASE=MATO 656 Cube Voyager Reference Guide . manipulating matrices. and bypasses end-of-zone processing for zone I. BREAK terminates the I-loop at zone 20 for each user class. they would be done only for zones 1-19. and loading-analyses processes effectively stop after the 19th zone for each user class. (Because MATO follows the processes.12 Public Transport Program Control statements When used within the Public Transport program’s MATI or MATO phases. BREAK bypasses any more processing for the relevant I zone. When “condition 2” is met. the route-evaluation. BREAK terminates the loop at the 20th zone. INCLUDE=list of J zones.Public Transport Program Control statements 12 IF(I==20) BREAK MW[1] = MW[1] * 1. or matrix element from an expression. or more. The number of arguments must match the requirements of the function.2 ENDPHASE COMP Computes a variable. See “Expressions” on page 33 for more details. or row data and return a value. arguments enclosed within parentheses (). 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. Built-in functions include: • • • Numeric functions (see “Numeric functions” on page 35) String functions (see “Character functions” on page 38) Row-based functions. Cube Voyager Reference Guide 657 . matrix. Built-in functions must be followed by one. EXCLUDE=list of J zones Expressions are either numeric formulas or selection criteria. string. Numeric expressions can use built-in functions that operate on numeric. VAR=expression MW[n]=expression. filtering values indicated by any INCLUDE or EXCLUDE lists on this statement.12 Public Transport Program Control statements • Skimming functions. 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). As the program internally loops on J. Matrices can contain up to MAXMW rows. Not permitted if COMP statement within JLOOP . the program only solves the expression one time only. By default no zones are excluded. Within a JLOOP statement. must be between one and Zones. or 1. The second index. if not. ENDJLOOP block. the program compares J to the values in the EXCLUDE list. 658 Cube Voyager Reference Guide . the program does not evaluate or store the expression for that J. Filter applies to all MW[n] values on the COMP statement. Always processed after INCLUDE subkeyword. Specified values can range from 1 to the highest zone number.. with J being the value of the loop’s current J. If the current J is on the list. • MW[n][o] — Defines the value for column o in row n. with J being the loop’s J if within a JLOOP. 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. Values of J excluded when computing the MW[n] expression.. The program solves the expression one time only. MW EXCLUDE |I| Optional. Value for a working matrix. o. as indexed by n. You can specify this keyword in two formats: • MW[n] — Defines the value for row n of a working matrix. Not permitted if COMP statement within JLOOP . Specified values can range from 1 to the highest zone number.messy -. the variable must be a character string variable..invalid: abc has been declared a string abc = abc+'456' . Values of J included when computing the MW[n] expression.jkl is declared numeric jkl = xyz . Variable that stores result of an expression. Examples of variables are: abc = '123' def = 123 abc = def . In the above examples. each node in the NODEREAD phase or each link in the LINKREAD phase). If the current J is not on the list.. As the program internally loops on J. ENDJLOOP block.do not mix types jkl = 1 . the statements with jkl= might never be executed. Filter applies to all MW[n] values on the COMP statement. the program does not evaluate or store the expression for that J. Cube Voyager Reference Guide 659 .Public Transport Program Control statements 12 COMP keywords (continued) Keyword MW Subkeyword INCLUDE |I| Description Optional. the program compares J to the values in the INCLUDE list.xyz is declared a string The program does not always compute expressions for variables that are not used as input to some process. because jkl is never used.invalid: xyz is declared a string (later) xyz = 'xyz' .valid abc = abc+def . The COMP statement sets a variable type to the result of the variable’s first evaluated expression. The program evaluates each encountered expression (for example. By default all zones are included. VAR |K| Optional. If the result is a character string. FORM=10. ALLMODES) Endphase Phase=MATO x=ROWADD(6. FORM=10. Anode. FORM=10.1.2 if (ROWSUM(4) > 0) PRINTROW MW=4 TITLE='IWAITA'. FORM=10. 660 Cube Voyager Reference Guide .2 if (ROWSUM(6) > 0) PRINTROW MW=6 TITLE='IWAITP'. BASE1=T.2 Endphase Compute average perceived trip cost skim from its components. BASE1=T. Phase=SKIMIJ MW[1]= IWAITP(0) MW[2]= XWAITP(0) MW[3]= TIMEP(0.3. BASE1=T. FORM=10.2 if (ROWSUM(5) > 0) PRINTROW MW=5 TITLE='XWAITA'.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. bypassing all intermediate statements. BASE1=T. FORM=10.4.2 if (ROWSUM(3) > 0) PRINTROW MW=3 TITLE='ValOfChoice'. BASE1=T. HighestNodeNum = MAX(HighestNodeNum. Bnode) CONTINUE Jumps to the end of a loop.2 Endphase Determine the highest node number in the public transport system. Phase=MATO if (ROWSUM(2) > 0) PRINTROW MW=2 TITLE='Compcost'.2. using standard function MAX.ALLMODES) MW[5]= XFERPENA(0. BASE1=T.5) PRINTROW MW=6 TITLE='AVJRNYCOST'.ALLMODES) MW[4]= BRDPEN(0. LOOP processing is bypassed for the L3s for which “condition 2” is met. except output and zonal summaries.3 IF (!(condition 1)) CONTINUE ENDLOOP In this user-controlled loop. ENDLOOP ENDLOOP JLOOP processing is bypassed for the Js for which “condition 1” is met... The outermost LOOP operates over the full range of L2. processing for the I zone is terminated..Public Transport Program Control statements 12 If CONTINUE is within a LOOP .L2+5 IF (condition 2) CONTINUE ... bypassing any statements between the IF and ENDLOOP. ENDLOOP or JLOOP .K2. but output and zonal reporting statistics will not be bypassed. Example 4 PHASE=SELECTIJ Cube Voyager Reference Guide 661 . no more Js will be processed for the I zone. If the condition is met. ENDJLOOP block. incrementing in steps of KINC.. similarly. Example 3 LOOP L2=K1. for that value of L1. ENDJLOOP LOOP L3=L2. from K1 to K2. control passes to the appropriate ENDLOOP or ENDJLOOP statement.. control is passed to the ENDLOOP when “condition 1” is not met. Otherwise.KINC JLOOP EXCLUDE=25-50.88 IF (condition 1) CONTINUE .. Example 1 LOOP L1=1.. Example 2 IF (condition) CONTINUE This statement is used in an explicit or implicit loop over I... 403-455 for processing. used to compute crowded travel time for particular combinations of transit lines and user-class. CROWDCRVDEF Defines crowding curves. Crowded travel times are behavioral measures which increase the in-vehicle time to reflect the discomfort of standing or travelling in crowded conditions. I and J.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.0 at both x=0 and x=100). If crowding is not applied. The first CONTINUE bypasses origin (I) zones 1-402 and the second one bypasses destination (J) zones 1-403. then either do not code line capacities. You can define up to 255 wait curves. The first BREAK stops the I-loop after zone 455 and the second stops each Jloop after zone 455. or use a flat curve (with y-value set to 1. 662 Cube Voyager Reference Guide . No default curves are provided. Specifies a unique numeric identifier for a crowding curve. Cube Voyager Reference Guide 663 . There is a linear interpolation between coded points. For example: CROWDCRVDEF NUMBER=1 LONGNAME="Suburban Rail" NAME="S-Rail" .1.0) to the first coded point.1. CROWDCRVDEF keywords Keyword CURVE |R| Description Defines X-Y pairs for the crowding curves used to compute link travel times under crowded conditions. CURVE= 0. Specifies a text-string identifier for a crowding curve. Maximum value: 10. the corresponding crowding factor values must increase.0. LONGNAME NAME NUMBER |S| |S| |I| Optional.1.1. Specifies a second text-string identifier for a crowding curve. the curve is extrapolated beyond that point at the same gradient as applies immediately below the point.Public Transport Program Control statements 12 Input CROWDCRVDEF statements must be input in the public transport system data file with SYSTEMI.0 (where the crowding factor is at least 1.0) to 100. the curve runs from the point (0-1. It is in addition to NAME. Crowding factor (Y-axis) may not decrease as utilization (X-axis) increases. Utilization (measured as a percentage) is the curve’s X-axis and the crowding factor is the curve’s Y-axis. when progressing from one point to the next.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. Optional.000. Must be the first keyword coded on the CROWDCRVDEF control statement. Specify the utilization values in ascending order. 20. Valid values range from 1 to 255. while the pairs themselves must be separated by a comma.0. or remain the same. When the last coded X-value is less than 100%. The values for utilization vary from 0. 100. Each pair of X and Y values may be separated by a comma or a dash. When the first coded X-value is greater than 0% utilization. Length of the modeled period in minutes.0. When set to false. Default value is false. CURVE= 0-1. ITERATIONS PERIOD |I| |I| Specifies the number of iterations performed during a crowd-modeling run. When set to true.1. NAME="Medium distance Rail". When set to true. Default value is false. CROWDMODEL keywords Keyword ADJUSTLINK |?| Description Optional. or must wait for a later service. CROWDCRVDEF NUMBER=1. Default value is false. Valid values are 1 to 99. APPLY |?| Optional. which reflects higher behavioral costs associated with travelling in crowded conditions. invokes link travel-time adjustment. Uses the available capacity of a service (at a particular boarding point) along with demand data to establish whether travellers may board this service. the crowding model is disabled. APPLY = T. 37-1. When set to true. ITERATIONS = 10 664 Cube Voyager Reference Guide . Any demand matrix loaded during assignment should be calculated for the model period.9 CROWDMODEL Specifies the crowding model used in the run of the Public Transport program. Default value is 60. ADJUSTWAIT = T. ADJUSTWAIT |?| Optional.12 Public Transport Program Control statements Example Defining crowd curve number 1 for rail services. 100-1. invokes the calculation of additional wait time. runs the crowding model. Example CROWDMODEL. Valid values are 1 to 1440. Optional. Second unique string that identifies the earliness curve (in addition to NAME). including a wait-time adjustment. EARLYCRVDEF keywords Keyword NUMBER Subkeyword |I| Description Unique number that identifies an earliness curve. EARLYCRVDEF Defines an earliness curve (in similar style to wait curves.) Curves should be such that y values never decrease as X increases. EXIT Terminates loops (implied or explicit).10 . Valid values range from 1 to 255. Which curve is used is defined in the factor file for the user class. When the program encounters an EXIT statement within a loop. Example LOOP iter=1. ENDLOOP This loop terminates either when iter=11 or the condition specified by expression is met. NOTE: Must be the first keyword coded in an EARLYCRVDEF control statement. Cube Voyager Reference Guide 665 .Public Transport Program Control statements 12 Specifies a run with 10 iterations of crowd modeling. the program passes control to the end of the loop. NUMBER NUMBER NAME LONGNAME |S| |S| Optional. Unique string that identifies the earliness curve. IF (expression) EXIT . 666 Cube Voyager Reference Guide . performs an accessibility run (to obtain travel time skims for mapping isochrones. Some FACTORS keywords are used for both the route enumeration and evaluation processes.12 Public Transport Program Control statements Keyword NUMBER Subkeyword CURVE |RKV1 0000| Description List of X-Y coordinates that define the earliness curve. you need not code the control statement name FACTORS. as noted in the keyword description. Separate each pair with a comma. FACTORS statements must be input in a separate file with FACTORI keywords on the FILEI control statement. All other factors are rejected as irrelevant. FACTORS Specifies the generalized cost factors and control information for the route enumeration and evaluation processes. For most of the keywords. The index of the FACTORI keyword. Each user class that the program references must have FACTORI keywords defined on a FILEI control statement. is the number of the user class. If there is no index. Separate X and Y values in a pair by a comma or a dash. Requires just DAYTYPE and either PERIOD or TIMEPOINT values to be specified in FACTORS file. You define user classes with the USERCLASSES keyword in the PARAMETERS control statement.) Default is false. The keywords on this statement are all “trigger” keys. The values can be input in any order. the program uses the last value specified. if the keyword appears multiple times. #. The X-axis shows headway and the Y-axis shows wait time. the program assumes the index is 1. FACTORS keywords Keyword ACCESSIBILITY Subkeyword |K?| Description When true. although two or more classes may reference the same file. others apply to one or the other. all-or-nothing routes.0 to 1. A value of 1 indicates that the walk and onward costs have equal weight. Cube Voyager Reference Guide 667 . Default value is 45. 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. Default value is 1. only those routes with MAXFERS or fewer transfers are enumerated (that is. A traveler’s willingness to walk might relate to network familiarity. AONMAXFERS |IK| Optional. Lower values indicate the walk cost has more influence than the onward cost in the traveler’s choice.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword ALPHA Subkeyword |RK| Description Optional.0. Determines the relative weights for the generalized costs of the walk leg and the remainder of the route in walk-choice model. Multirouting models only enumerate the all-or-nothing route if the number of transfers exceeds MAXFERS. Valid values range from 0. AONMAXFERS is not used) Valid values are 0 to 45.0. When BESTPATHONLY=T. Applies only to route evaluation. Only routes with AONMAXFERS (or fewer) transfers are enumerated to the routes file. Maximum permitted number of transfers on the minimum-cost. then selects the lowest generalized cost path out of each “departure time”.e. the evaluation process identifies a single best path. If a line runs half-hourly. Default is false. onto which all demand is loaded. When set to true. BESTPATHS |K?| When true. QUICKESTPATH or QUICKESTMULTI path are true. enumerates multi-routing (i. LAMBDAW. If using best-path modeling with MUSTUSEMODE set to true. The default value is false. and SPREADFUNC.) 668 Cube Voyager Reference Guide . there is however just one underlying route. REWAITMAX. otherwise the keywords are ignored. full multi-routing takes place (i. multiple paths for each departure time). The best-path-only method cannot be used with either the crowding model or the service frequency and cost model.e. AONMAXFERS. 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. Do not set BESTPATHONLY to true if PARAMETERS keyword FARE is true or AONMETHOD has value 3. CHOICECUT. making higher MAXFERS settings appropriate. When using best-path modeling. LAMBDAA. SPREADFACT.) If none of BESTPATHS. enumerates multiple paths for each departure time and each path is included in evaluation. the program ignores settings for the FACTORS keywords ALPHA. The term path is used to mean a route which is followed using a set of departure and arrival times at each stop. and the enumeration process changes its mode of operation: Best paths using more then MAXFERS transfers are not enumerated. the program uses the FACTORS keywords SPREADCONST. and REWAITMIN.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword BESTPATHONLY Subkeyword |?K| Description Optional. Applied in addition to the transfer penalty specified by XFERPEN.2. If p is the proportion of the demand that takes the least-cost alternative. The default value is 0. For example. it is not used when modeling best path routes. Eliminates alternatives with low probabilities of use at walk or alternative-alighting decision points. This selects the lines/runs which operate on that day. Cost to destination by choice i Costi CostBest Cost to destination by the best choice CHOICECUT applies only to route evaluation. CHOICECUT |RK| Optional. in minutes.01. This is equivalent to choices being eliminated if: CHOICECUT > e – λ ( Costi – CostBest ) where: λ Scale parameter that reflects traveler sensitivity to cost differences. Valid values range from 0 to 0. 3. and 4 is five minutes and the penalty for boarding a line on mode 5 is six minutes. DAYTYPE |KI| The day type number which the model relates to. Cube Voyager Reference Guide 669 .6 then the penalty for boarding any line on mode 1 is three minutes.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword BRDPEN Subkeyword |RKV999*| Description Optional. It takes the value of LAMBDAW or LAMBDAA. the penalty for boarding any line on modes 2. then the program discards alternatives taking less than p*CHOICECUT. Applied only to transit modes. if BRDPEN=3. depending upon the point in the trip at which it is applied. Valid values range from 0 to 9999.3*5. The default value is 0. nonzero values specified for nontransit modes do not have any effect. Mode-specific boarding penalty. Valid values range from 0 to 999. the default curve (y=x) will be used. when modeling walk and car connectors. EXTRAXFERS1 is one of three parameters controlling the exploration of routes. 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. you can use this keyword to restrict access legs to the required mode (that is. Optional. EXTRAXFERS1 applies only to route enumeration. walk or car) for a user class. There is no default. 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. when modeling walk and car connectors. Specifies modes that cannot be used as access connectors (from zones to transit lines) during route enumeration. car or walk) required for a user class. You can use this keyword to delete particular modes (transit or nontransit) from the model for a particular user class. DELMODE |IKV999| Optional. Specifies modes that cannot be used as egress connectors (from transit lines to destination zones) during route enumeration. See “Route generation” on page 686 for more information. you can use this keyword to restrict egress legs to the mode (that is.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword DELACCESSMODE Subkeyword |IKV999| Description Optional. EXTRAXFERS1 |IK| 670 Cube Voyager Reference Guide . The default value is 3. There is no default. Valid values range from 0 to 10. If no curves are specified. Valid values range from 0 to 999. For example. we choose one before or after that period). Valid values range from 0 to 999. Number of transfers at which the program stops exploration of less direct routes. For example. There is no default. Specifies modes that the program will not use during route enumeration. DELEGRESSMODE |IKV999| Optional. MODE=7-11 FARESYSTEM applies only to route evaluation. Cube Voyager Reference Guide 671 . in excess of the minimum required.30. MODE=1-6 FARESYSTEM=2. Maximum number of transfers explored in excess of the number of transfers required by the minimum-cost route. Mixing the two could produce ambiguous allocations. all FARESYSTEM keywords must apply to either modes or operators. EXTRAXFERS2 is one of three parameters controlling the exploration of routes. If using multiple fare models. but you must code one for each FARESYSTEM.40 FARESYSTEM NUMBER=2. The program allocates fare systems to lines. none are specified. EXTRAXFERS2 applies only to route enumeration. The default value is 2. NOTE: The MODE and OPERATOR subkeywords are mutually exclusive. NAME="DIST-Journ".0. you can apply that fare model to a selection of transit modes: FARESYSTEM=1. IBOARDFARE=100. An upper bound on the number of transfers. For example. FAREFROMFS=0. STRUCTURE=DISTANCE. Valid values range from 0 to 10. Valid values range from 1 to 1999.50 In the factors file. FARESYSTEM |IK| Optional. STRUCTURE=FLAT. UNITFARE=70. FAREFROMFS=40.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword EXTRAXFERS2 Subkeyword |IK| Description Optional. you might describe a fare model in the FAREI files as: FARESYSTEM NUMBER=1. NAME="Flat".). is controlled by EXTRAXFERS1 and MAXFERS (see “Route generation” on page 686. through their modes or operators. The fare model must be one of the fare systems defined with the FARESYSTEM control statement in a FILEI FAREI file. By default. Number of the fare model that applies to the modes or operators selected with the subkeywords MODE or OPERATOR. IBOARDFARE=50. the wait time is based on combined frequency of all lines in the transit bundle regardless of mode. By default the BESTPATHONLY enhancement identifies the best path using unimodal transit-legbundles. collection of lines from a boarding point to an alighting point) on a “potential best route” is multimodal. In this case. Optional. and then waits for a service of that mode (ignoring any potentially useful services in the transit leg bundle of any other mode). FREQBYMODE comes into effect when a transit-leg bundle (that is. This corresponds to traveler behavior where a traveler selects a mode of travel. Default value is 0.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword FARESYSTEM Subkeyword MODE |IVt|1 Description Optional. The wait times are based on the headway of the mode under consideration. The default value is true. 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. Default value is 0. List of operators that the fare model specified in FARESYSTEM applies to. List of transit modes that the fare model specified in FARESYSTEM applies to. If modes 1 and 2 form a bundle. FARESYSTEM OPERATOR |IVo| 2 Optional. and the average IVT is based on all modes. 672 Cube Voyager Reference Guide . Valid values range from 1 to 999. Program ignores any nontransit modes in the list. and corresponds to traveler behavior where they “select the useful service that first arrives at the boarding point. then either you use mode 1 or you use mode 2 depending on IVT and wait times in the two cases.” and mode does not affect that boarding pattern. Valid values range from 1 to 99. If FREQBYMODE is false then multimodal transit leg bundles are allowed. This gives lower wait times. inclusive. Requires KBETA when true. For example. When true. Determines the proportion of trips allocated to each alighting node. The default value is system generated. IWAITCURVE NODES |IV10000| List of nodes to which the wait curve number specified by IWAITCURVE. No default. KIRCHOFF |K?| LAMBDAA |RK| Cube Voyager Reference Guide 673 . 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. given IWAITCURVE=2.0. The program ignores wait curves associated with zones or nodes that are not stops. IWAITCURVE applies only to the route-evaluation process. The default value is the value of LAMBDAW.0001 to 99. This keyword is required if IWAITCURVE is specified. KBETA=2 will calculate costs raised to the power -2. Default is false. Wait curve used to calculate the initial wait time for trips starting at nodes specified by NODES subkeyword. NODES=10002000. Applies only to the route-evaluation process. uses Kirchoff (power-function) to determine choices. Valid values range from 1 to the system’s highest node number. applies when they are the initial boarding points of trips. Optional.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword IWAITCURVE Subkeyword |IK| Description Optional. Not used when modeling best-path routes. Valid values range from 0. Scaling factor for the alternative-alighting node model. KBETA |KR| Power used in Kirchoff distribution (coded positive but used as negative in a similar way to lambdas). based on the composite cost differences between the alternatives. Valid values range from 1 to the number of wait curves in the network. 2500-2600. Optional.0001 to 99. the program does not use this factor when modeling best-path routes. based on the composite cost differences between alternatives. LAMBDAW applies only to the route-evaluation process. 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.000. MAXCOMPD applies only to route enumeration. This factor determines the proportion of trips allocated to each walk choice at a node.0. The default value is 50. When there are transit choices. we choose one before or after that period). Used to dimension arrays that store components and their attributes.250. the program uses the transit modes’ composite cost to a destination to determine the transit share.2. Number of components generated during the route-enumeration process. the service-frequency model allocates the transit share among the different transit choices.000. triggered by the AONMETHOD keyword on the PARAMETERS control statement. the default value should work for a medium-sized network of 400-500 zones. Valid values range from 0. The number of components generated depends upon the number of lines in the public transport system and the connectivity of the network. Subsequently. Scaling factor for the walk-choice model. The default value is 0. 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. Valid values range from 1000 to 1. If no curves are specified. MAXCOMPD |IK| 674 Cube Voyager Reference Guide . The program only requires MAXCOMPD when using older algorithms. the default curve (y=x) will be used.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword LAMBDAW Subkeyword |RK| Description Optional. Specifying “varName” will use “ni. The default value is 5.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword MAXFERS Subkeyword |IK| Description Optional. then the program enumerates viable routes. MAXFERS works with EXTRAXFERS1 and EXTRAXFERS2 to control the number of routes generated. regardless of the number of enumerated routes (AONMAXFERS is not used). MAXWAITVAR |KS| Optional. then the program only enumerates the minimum-cost route (subject to any constraint imposed by the AONMAXFERS factor). Specifying “varName” will result in “ni. When an origin-destination pair has a minimum-cost route with at most MAXFERS transfers. as best routes requiring more transfers are not enumerated. 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). MINXFERVAR |KS| Cube Voyager Reference Guide 675 . When interchanging at a node. If the transfers exceed the MAXFERS when using multirouting. Specifies the name of a node variable which holds the minimum time taken for transfer at each node. Specifies the name of a node variable which holds the maximum wait time which travelers are prepared to spend waiting at each node.varName” from the input network. When the PARAMETERS keyword AONMETHOD is set to 3.varName” from the input network. you might use higher MAXFERS values. Maximum number of transfers allowed in routes between origin-destination pairs with more than one enumerated route. When BESTPATHONLY is true. Optional. For pairs with only one enumerated route. the departure time must be this much later than the arrival time. MAXFERS is the maximum number of transfers allowed in route enumeration. Valid values range from 0 to 10. See “Route generation” on page 686. AONMAXFERS sets the maximum number of transfers. By default. Additional cost allowed on enumerated routes of a required mode (a mode specified in MUSTUSEMODE).999. MUSTUSEMODE |IKV999| Optional. Optional.g. QUICKESTPATH QUICKESTMULTI REBESTPATHCOST |K?| |K?| |?K| When true. if the cheapest route for an origindestination pair is 23 and MUMEXTRACOST is 30. 23+30). False — Computes transit • Cannot be false if BESTPATHONLY is true. 676 Cube Voyager Reference Guide .999. Must be false if program uses service frequency and cost model. 0930-1030 means 9:30am to 10:30am. When true. set to the value of BESTPATHONLY. PERIOD |KRPa| Time-tabling specific: Range of values each in hhmm format which specify start and end of modeled period.1 to 999. Either this or TIMEPOINT must be used in timetabling runs. If you specify two or more values. the program enumerates the route if any of the modes are used. See “Generalized cost” on page 797 for a description of costs. Valid values range from 0 to 999. Default is false. The default value is 999. There is no default value. Flag that sets method for computing transit costs in route enumeration: • True — Computes transit costs closer to those used in evaluation. the program will enumerate routes on the required mode that have a cost of up to 53 (that is. enumerates a single path. Default is false. E. Valid values range from 0. For example. Specified modes must be transit modes. enumerates a single fastest path for each “departure time”.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword MUMEXTRACOST Subkeyword |RK| Description Optional. Specifies required transit modes in a route for enumeration or evaluation. Cube Voyager Reference Guide 677 . and hence evaluation. Default value is 999. REFAREFACTOR |RKV999*| Optional. The factors apply to transit modes. With faster modes having higher factors. Public transport systems often include a mix of transit modes. Specifies a factor which is included in calculating the cost for a transit leg which is then used in enumeration. but does not include fares in the cost. Upper cost limit that applies during route enumeration. and when fares are modelled faster more expensive modes compete with slower cheaper alternatives. Routes using slower modes may be outside these margins. and the enumeration process is more likely to find routes using slower modes. This factor is available in multi-route modelling.01 to 999. their costs are increased by a higher proportion.999. as they may be a function of the entire route rather than just one transit leg. 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.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword RECOSTMAX Subkeyword |RK| Description Optional. Valid values range from 0. as determined by SPREADCONST and SPREADFACT. The enumeration process uses the same perceived travel time as evaluation. the costs of nontransit legs are left unchanged.0 as they inflate the perceived cost to take account of fares.999. Enumeration selects routes which lie within defined margins of the best route. REFAREFACTOR values are typically >= 1. The program excludes more expensive routes from enumeration. and cannot be used when BESTPATHONLY=T. and so are omitted from the route set. 0 to 30.0. Setting REWAITMAX to 3.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword REWAITMAX Subkeyword |RK| Description Optional. The program computes a leg bundle’s wait time from the sum of the frequencies in the bundle’s legs: (60. Minimum weighted wait time for a leg bundle during route enumeration. if a leg bundle’s frequency sums to 60 vehicles per hour. Maximum weighted wait time for any leg bundle in route enumeration. The program computes a leg bundle’s wait time from the sum of the frequencies of the bundle’s legs: (60.0 ensures that a minimum wait time is incurred for all leg bundles regardless of the frequency of their services. The default value is 5.0. REWAITMIN applies only to route enumeration. REWAITMAX applies only to route enumeration. The default value is 1. 678 Cube Voyager Reference Guide . Setting REWAITMIN to 1. REWAITMIN |RK| Optional.0./Frequency)/2 For example.5 minutes. the wait time is 6 minutes. it is not applicable when modeling best-path routes. it is not applicable when modeling best-path routes. Setting REWAITMAX to 0 excludes wait time from consideration during route enumeration. Valid values range from 0.0.0 to 200./Frequency)/2 For example. if the frequency of a leg bundle sums to 5 vehicles per hour. the wait time is 0.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. Valid values range from 0. 8. Cube Voyager Reference Guide 679 .5.01 to 10. Service model to be used in routeevaluation. Values ranging between 0. run times for modes 2. SERVICEMODEL |S| Optional.9 then the program multiples run times for mode 1 by 1.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.5.0. The default value is 1. Valid choices are: • • FREQUENCY — Specifies Service-frequency model FREQUENCYCOST — Specifies Servicefrequency-and-cost model Default value is FREQUENCY.8 and run times for mode 5 by 1. if you include RUNFACTOR=1. and loading-analyses processes. skimming.9. 3 and 4 by 1. For example.01 and 3.0.1. Valid values range from 0.0 are appropriate for most modeling requirements. loading.3*1. Default value is 5. Determines which of a group of non-transit connectors are used in a multi-routeing model. giving the benefit of shorter run times. Any interchange between a pair of lines which takes place at a node will be chosen in preference to a walk connection. By setting SHORTESTWALK a smaller set is used.2. a similar approach is followed. Default value is 1. exceeding 2. or a downstream timing point for access. the time (excluding wait) is calculated from a point upstream of the first alighting stop under consideration on the from-line.0. Constant used in multirouting function to compute SPREAD (see “SPREADFUNC” on page 681). not applicable when modeling best-path routes. not applicable when modeling best-path routes. 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. When SHORTESTWALK=F the selection is based on travel time between lines and/or zones. When SHORTESTWALK=T the selection is based on the lowest cost connector. Applies only to route enumeration. When SHORTESTWALK is unset the selection is based on the lowest cost connector. SPREADFACT |RK| Optional. without any reduction in connectivity in the network. Valid values range from 0 to 1000.0 only in rare circumstances.0.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword SHORTESTWALK Subkeyword |?K| Description Optional. or interchange legs (which may be at or between stops). The default is unset. SPREADCONST |RK| Optional. Applies only to route enumeration. using an upstream timing point when selecting for egress. Typical values range from 1.0.2. Multiplicative factor used in multirouting function to compute SPREAD (see “SPREADFUNC” on page 681). 680 Cube Voyager Reference Guide . Valid values range from 1 to 10.05 to 1. to a point downstream of the latest boarding stop on the to-line. For transfers. The connectors may be between zones and stops. For zone-line connectors. SPREAD defines an upper cost limit for routes between an O-D pair. GCost(MinRoute) + SPREADCONST) • SPREADFUNC=2: SPREAD = GCost(MinRoute)* SPREADFACT + SPREADCONST Where: • GCost(MinRoute) — Generalized cost of the minimum-cost route. The generalized cost the route-evaluation process uses is more accurate. SPREADFUNC applies only to route enumeration. No default. • The program enumerates routes with a cost less than or equal to SPREAD. SPREADCONST — Time that may be added to the minimum generalized cost time between zone pairs. The program computes the upper limit based on value of SPREADFUNC: • SPREADFUNC=1: SPREAD = MAX(GCost(MinRoute)* SPREADFACT. • SPREADFACT — Factor that the minimum generalized cost time between zone pairs may be multiplied by.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword SPREADFUNC Subkeyword |IK| Description Optional. NOTE: This is an estimate. Default value is 1. NOTE: The parameter applies to each decision point (alighting/boarding node) on a route in addition to the destination. Cube Voyager Reference Guide 681 . Integer specifying the function that computes SPREAD during route enumeration. The traveler leaves the origin at this fixed/defined time (specified in hhmm format) and appropriate paths are found and evaluated. TIMEPOINT |KR| Alternative to PERIOD for time-tabling. The lower limit is the cost of the “minimum cost” route between the two zones. it is not applicable when modeling best-path routes. For example.0. applied to nodes specified with NODES subkeyword. Transit-mode-to-transit-mode constant that can be added to the weighted transfer penalties obtained from XFERPEN. in monetary units per hour.0. consider: WAITFACTOR=1. XFERCONST FROM |IV100| Integer specifying the “from” mode for the transfer penalty specified with XFERCONST. XFERCONST |RKVt [t]|1 Optional. the program will add three minutes to the transfer penalty specified by XFERPEN.5. Applies only to route evaluation. 682 Cube Voyager Reference Guide .12 Public Transport Program Control statements FACTORS keywords (continued) Keyword VALUEOFTIME Subkeyword |RKVt*|1 Description Optional. Transit-mode-specific value of time. 30004500 The wait times for nodes 1000 through 2000 and nodes 3000 through 4000 will be multiplied by 1. Node-specific wait-time weighting factor. Valid values range from 0. For example. consider: XFERCONST=3. Valid values range from 1 to the network’s highest mode number.5. NODES=1000-2000.0 to 5000. WAITFACTOR NODES |IV10000| List of nodes that WAITFACTOR applies to. Applies only to route evaluation. Valid values range from 0. Does not apply to nontransit modes.0. Converts monetary fares into generalized cost.0. Only code if using fares. The default value is 0. Use FROM and TO to specify the applicable modes. TO=25 For transfers from mode 10 to mode 25. sufficient values for most modeling range from 0.01 to 10. Valid values range from 0. Valid values range from 1 to the network’s highest mode number. XFERCONST TO |IV100| Integer specifying the “to” mode for the transfer penalty specified with XFERCONST. WAITFACTOR |RK| Optional. Typically.0 to 9999.01 to 3. Default value is 1. ignored in such cases. FROM=10. consider: XFERFACTOR=1.5. Valid values range from 1 to the network’s highest mode number.0. Transit-mode-to-transit-mode weighting factor for transfer penalties specified by XFERPEN. FROM=10. XFERFACTOR FROM |IV100| Integer specifying the “from” mode for the transfer penalty factor specified with XFERFACTOR.01 to 10. The default value is 1. Valid values range from 1 to the network’s highest mode number. Use the subkeywords FROM and TO to specify the applicable modes. For example.5. the program multiplies the transfer penalty specified by XFERPEN by 1.0. Valid values range from 0. TO=25 For transfers from mode 10 to mode 25.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword XFERFACTOR Subkeyword |RKVt [t]|1 Description Optional. XFERFACTOR TO |IV100| Integer specifying the “to” mode for the transfer penalty factor specified with XFERFACTOR. Applies only to route evaluation. Cube Voyager Reference Guide 683 . FROM=10.999. 684 Cube Voyager Reference Guide . to mode) and BRDPEN(to mode) must be greater than or equal to zero. XFERPEN FROM |IV100| Integer specifying “from” mode for transfer penalty specified with XFERPEN. Use negative transfer penalties in conjunction with boarding penalties to reflect the relative attractiveness of transfers between some modes compared to others. in minutes. Use the subkeywords FROM and TO to specify the applicable modes. Transfer penalties may be negative but the sum of XFERPEN(from mode. Code a high penalty to ban transfers between modes. XFERPEN only applies to route evaluation. The default value is 0. Valid values range from 1 to the network’s highest mode number. consider: XFERPEN=5. Valid values range from 1 to the network’s highest mode number.12 Public Transport Program Control statements FACTORS keywords (continued) Keyword XFERPEN Subkeyword |RKVt [t]|1 Description Optional. XFERPEN TO Integer specifying “to” mode for transfer penalty specified with XFERPEN. Transfer penalties apply between the alighting and boarding transit modes. The program applies XFERPEN in addition to BRDPEN. For example.5. TO=25 For transfers from mode 10 to mode 25. a penalty of 999 minutes is sufficient. Transit-mode-to-transit-mode transfer penalty. The program ignores any nontransit legs traversed between the two. the program adds 5. Valid values range from -99 to 9. In most cases.5 minutes. A high penalty makes any route with such transfers “unattractive” to the choice models. XWAITCURVE NODES |IV10000| List of nodes that the wait curve specified in XWAITCURVE applies when they are boarding stops at transfer points. 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. NODES=1000-1500 The program uses wait curve number 4 to compute the wait time at nodes 1000 through 1500.1 SPREADCONST = 10. XWAITCURVE applies only to route evaluation.3 Cube Voyager Reference Guide 685 . o indicates number of transit operators 3. Valid values range from 1 to the maximum number of wait curves in the network. when those nodes form transfer points in a trip. The program ignores wait curves associated with zones or nodes that are not stops. t indicates number of transit modes 2. Wait-curve number used to calculate wait times for trips that involve transfers to nodes specified with NODES subkeyword. For example.0 LAMBDAW = 0. 1. The default is a systemgenerated wait curve. Valid values range from 1 to the network’s highest node number.Public Transport Program Control statements 12 FACTORS keywords (continued) Keyword XWAITCURVE Subkeyword |IK| Description Optional. consider: XWAITCURVE=4.0 REWAITMIN = 5 REWAITMAX = 30 //Evaluation Controls ALPHA = 1. to=8-12. XFERCONST=5. from=7-10. Next. MINXOD. n=25-1000 //IVT factor by mode RUNFACTOR[7] = 1. The program ensures that routes do not exceed the specified constraints. to=8-12. from=7-10.3 //Wait time IWAITCURVE=1. the program determines the connections required to transfer between lines. Second. number of transfers must be no greater than MAXFERS. RUNFACTOR[11] = 2. from=11-12. to=7-12. from=7-10.5.5.0. First. number of transfers must be less than or equal to the minimum of: MINXOD+EXTRAXFERS2 EXTRAXFERS1 MAXFERS The search for routes has two stages. the program searches for “attractive” routes for each O-D. XFERCONST=2.0. to=7-12. First. nodes=1300-1400 XWAITCURVE=2. the program explores the connections and generates routes by progressing through a sequence of lines and connections. from=11-12.0. the program generates minimum-cost routes for all O-D pairs and records the number of transfers required for these routes. XFERFACTOR=1.5 XFERPEN=3. XFERPEN=2.5.0.5 //Penalties BRDPEN[7] = 4*2. RUNFACTOR[8] = 2.25. 686 Cube Voyager Reference Guide .12 Public Transport Program Control statements LAMBDAA = 0. XFERFACTOR=2. n=150-1600 WAITFACTOR=2. If number of transfers exceeds MINXOD. Route generation MAXFERS works with EXTRAXFERS1 and EXTRAXFERS2 to control the number of routes generated. from=11-12. Attractive routes depend on the number of transfers: • • If the number of transfers equals MINXOD. to=7-12. to=7-12. The program expends more effort where travelers make a greater proportion of tips. or 2 transfers. 1. suppose MAXFERS=5. This is consistent with observed travel patterns: 70-80% of trips are completed within two transfers or three transit legs. EXTRAXFERS1=4 and EXTRAXFERS2=2. Use separate FARESYSTEM statements to define multiple fare systems in public transport network. FARESYSTEM Defines fare systems that the program uses to calculate trip fares. the program explores routes with up to 4 transfers (the EXTRAXFERS1 constraint applies). the program explores 5 transfers (the MAXFERS constraint applies). Thus. Cube Voyager Reference Guide 687 . 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. If O-D pairs have minimum-cost routes with 0. 3. If O-D pairs have minimum-cost routes with 3 or 4 transfers. Finally. for O-D pairs that have minimum-cost routes with 5 transfers. or 4 transfers (the MINXOD+EXTRAXFERS2 constraint applies).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). the program will explore routes with up to 2. the program explores more routes for directly connected zone pairs than for less directly connected zone pairs. loading. NAME="FAREZONE-FROMTO". travelers incur fares when using the lines. LONGNAME="WITHOUT FAREFROMFS". FAREFROMFS=10*0. 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. SAME=CUMULATIVE. UNITFARE=0.83 Example 2: Zone based “FROMTO” fare system with no FAREFROMFS FARESYSTEM NUMBER=8. STRUCTURE=FROMTO. Example 1: Distance with IBOARDFARE + UNITFARE + SAME=SEPARATE FARESYSTEM NUMBER=4. you must allocate all lines to fare systems. IBOARDFARE=1. SAME=SEPARATE.35. STRUCTURE=DISTANCE.1. The program uses fare systems for the evaluation. You can code a NULL fare system to run lines effectively free. and loading-analyses processes.1. When modeling fares. The program allocates fare systems to lines.FAREZONE 688 Cube Voyager Reference Guide . skimming. LONGNAME="WITH FROM-TO FARES". FAREZONES=NI.12 Public Transport Program Control statements You input the FARESYSTEM statements to the Public Transport program with the FILEI FAREI file. The program does not use fares in enumeration. or directly with the LINE control statement. FAREMATRIX=FMI. either indirectly through transit modes and operators with FACTOR FARESYSTEM. NAME=DISTANCE. You must code FAREFROMFS in monetary units. Fare incurred when transferring from fare systems defined by other FARESYSTEM control statements to this fare system. Valid strings are standard matrix names of the type: FM. 30 The costs of transferring from fare systems 1. and 3 to fare system 3 are 45. The program converts the fare. and the column the alighting fare zone traversed. FAREMATRIX is required for STRUCTURE=HILOW or STRUCTURE=FROMTO statements. For example.Public Transport Program Control statements 12 FARESYSTEM keywords Keyword FAREFROMFS Subkeyword |RVn| 1 Description Optional. and the column the highest fare zone traversed.# or FMI. the row of the matrix represents the lowest fare zone traversed. and 30 monetary units. and cannot be used for any other types. You can include boarding fares applicable at transfers in FAREFROMFS. 2.Name. into generalized cost with VALUEOFTIME. respectively. FAREMATRIX |S| Optional. Cube Voyager Reference Guide 689 .#. 70. The default value is 0. the row of the matrix represents the boarding fare zone traversed. the program converts to generalized cost with VALUEOFTIME. For STRUCTURE=HILOW. derived from FAREMATRIX. and incentives (that is. negative fares) between select fare systems. For STRUCTURE=FROMTO.#. Name of the fare matrix for this fare system. You can also provide the cost of transferring between the same fare system. 70. Must be input with FILEI FAREMATI. consider: FARESYSTEM NUMBER=3 FAREFROMFS=45. Separate each pair of X and Y values with a comma or hyphen.1.1. In the coordinates. FARETABLE=1-1. 4. Thus. the fare is the last coded fare.00. Separate each pair of coordinates with a comma. For example: FARESYSTEM NUMBER=11. the fare is the first coded fare. You can use fare tables when STRUCTURE is DISTANCE. 3.12 Public Transport Program Control statements FARESYSTEM keywords (continued) Keyword FARETABLE Subkeyword |RKV32000| Description Optional.5. in monetary units. For example. 5-5.85. the X-axis represents distance and the Y-axis represents fare. FAREZONES=NI. COUNT.5. Y. The fare. When STRUCTURE is DISTANCE. List of X. 2-1.85. STRUCTURE=COUNT. If the measure of trip length is greater than the last coded value of X.00.FAREZONE.75. the fare can never decrease.2. and either stay the same or increase with trip length.75. must always be greater than zero.4. SAME=CUMULATIVE. the curve runs parallel to the X-axis up to the first coded point and beyond the last.10. if STRUCTURE is DISTANCE. or ACCUMULATE.5 or FARETABLE=1.and Y-coordinates that define the table used to compute fares for a trip’s “length” component (rather than boarding or transfer components).10. LONGNAME="WITH FARE ZONES". 5. if the measure of trip length is less than the first coded value of X. 690 Cube Voyager Reference Guide . Other mechanisms available are UNITFARE and FAREMATRIX. the X-axis represents trip length and the Y-axis represents the fare. 44. 2. 3-2. NAME="FAREZONE-COUNT". the fare would be 0.32 for a 12-km trip.50 INTERPOLATE=T The fare would be 0. must always be greater than zero and increase with trip length. and 1.70 for a 5-km trip. For example. Cube Voyager Reference Guide 691 .0. Default value is F.2. INTERPOLATE only applies if STRUCTURE is DISTANCE.60 for both the 5-km trip and the 9-km trip.10 for a 9-km trip. X values must range from 1 to the number of fare zones and increase monotonically.SAME=SEPARATE. The fare. 1. When STRUCTURE is ACCUMULATE. FARETABLE INTERPOLATE |?| Optional. the program assume the curve is a step function.60. The fare for each zone must be greater than zero. 10.1. if INTERPOLATE was F. Y. consider: FARESYSTEM NUMBER=2 LONGNAME="ALL" NAME="ALL" STRUCTURE="DISTANCE".0. If STRUCTURE is COUNT or ACCUMULATE. Flag that specifies interpolation between coded points in the fare table.5.0.15.50. 4. The program converts the fare derived from FARETABLE into generalized cost with VALUEOFTIME. However.1.20 for the 12-km trip.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. There are two possible values: • • T — Linear interpolation between coded points F — Step function. and 1. FARETABLE=2. The default value is 0. The program uses the fare system of the line on which the traveler completes the first leg. FROMTO. The technique for grouping nodes into fare zones depends on the fare zone system used. Valid values range from 1 to 1999. If STRUCTURE is HILOW. Valid strings are standard names for node variables of the type: NI. The program converts the fare into generalized cost with VALUEOFTIME. You must code IBOARDFARE in monetary units.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 node’s fare zone number. 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. LONGNAME NAME NUMBER |S| |S| |I| Optional. Required if STRUCTURE is HILOW. If STRUCTURE is COUNT. Fare zones may represent groups of nodes or single nodes. Unique string identifier for a user-defined fare system. FROMTO. you must use an annular grouping. you use sequential grouping. 692 Cube Voyager Reference Guide . or ACCUMULATE.Name. Unique numeric identifier for a user-defined fare system. COUNT. or ACCUMULATE. Optional. IBOARDFARE |R| Optional. NOTE: Must be first keyword in FARESYSTEM control statement. Second unique string identifier for a userdefined fare system. Calculate fare from IBOARDFARE and FAREFROMFS. Each fare zone has an associated fare which is accumulated as the zone is traversed. For this value. String that indicates how the program calculates the fare for consecutive legs of a trip with the same fare system. lines with such systems give free rides. STRUCTURE SAME |S| Optional. Cube Voyager Reference Guide 693 . used to compute fares. 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).Public Transport Program Control statements 12 FARESYSTEM keywords (continued) Keyword STRUCTURE Subkeyword |S| Description Measure unit for trip length. Possible values include: • FLAT — Trip length is not relevant for this fare structure. do not code any other FARESYSTEM keywords. FREE — Defines a NULL fare system. measured in user-specified units (such as miles or kilometers). • • • • • • Data requirements of fare systems vary with STRUCTURE. ACCUMULATE — Trip length is the number of fare zones crossed. See “Fares” on page 845. DISTANCE — Trip length is in-vehicle distance. FROMTO — Trip length is an attribute of the boarding and alighting fare zones. 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. 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. Use with caution. All FILEI keywords are “trigger” keywords and need not be preceded by the control statement name. 1. Default value is 0. 694 Cube Voyager Reference Guide .12 Public Transport Program Control statements FARESYSTEM keywords (continued) Keyword UNITFARE Subkeyword |R| Description Optional. For example LINEI can have up to 32 files. Cost per unit of the measure defined in STRUCTURE. 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. if STRUCTURE is DISTANCE. the trip cost is UNITFARE * trip distance + boarding and transfer fares. NOTE: The Public Transport program allows certain types of files to have multiple files. The program converts to generalized cost with VALUEOFTIME. Specifies files that may be input to the Public Transport program. Due to a restriction on the total number of files. Code in monetary units. For example. fewer files than permitted for a particular file type may be active in Application Manager. FACTORI[3]=FACTSUC3. If there is no index. The output network file may not be suitable for use with fares in subsequent runs of the Public Transport program. FACTORI LIST |?| Optional. FILEI FACTORI[1]= FACTSUC1. You may input up to ten input factor files. FACTORI OMITFARES |?| Optional. corresponding to the classes defined by PARAMETERS USERCLASSES statement. routeevaluation.FAC. Possible values: • Y — Omit validation of fare-related data in the factor file. Cube Voyager Reference Guide 695 . FACTORI is required for the route-enumeration. However. N — Validate fare-related data in the factor file. You must code explicitly for each user class. Specifies the names of the input factor files. do not specify FACTORI because the network contains FACTOR data. • • Y — List the lines file as input N — Do not list the lines file as input Default value is N.3-4. • Default value is N.FAC See “FACTORS” on page 666 for a list of keywords you can use. loading. Flag that indicates whether to list the lines file as input. Default value is 0. if you input a Public Transport network with NETI. one per user class. FACTORI MAXERRS |I| Optional. Maximum number of errors allowed in the factor file before the program stops processing factors. Specify an index. and loading-analyses processes. though you can assign the same file to two or more classes.FAC. for each. User class 3 and 4 use the same factors. Flag that indicates to validate fare data in the factor file. the program assumes it to be 1. FACTORI[4]=FACTSUC3. Example FACTORI for USERCLASSES=1. [#].Public Transport Program Control statements 12 FILEI keywords Keyword FACTORI Subkeyword |FKVu| 1 Description Optional. The file contains one or more FARESYSTEM control statements. Flag that indicates whether the list the fare systems as input. f[j]. Delimit files with either commas or white space. FAREI LIST |?| Optional. Input files may contain either standard Cube Voyager binary matrices or records containing matrix data in the pattern: M. Column number for the 1st f[j] that follows.. If you do not specify an index. J. followed by the fare for line j+1 and so on. Name of the input file that contains one or more matrices used for computing fares. Append an index to each. Name of input file defining the fare systems. then M must be the table number. Required if the program will consider fares during routeevaluation and skimming processes. I J f[j] Fare for line j. There must be a row for each fare zone that will use the matrix.name.I.f[j+1]. 696 Cube Voyager Reference Guide . Row number.y.x.. See “FARESYSTEM” on page 687 for a list of keywords you can use.12 Public Transport Program Control statements FILEI keywords (continued) Keyword FAREI Subkeyword |FK| Description Optional. Possible values: • • FAREMATI |FKV| Y — Lists the fare systems as input N — Do not list the fare systems as input Optional.x. depending upon how you specify FARESYSTEM FAREMATRIX. the program assumes the index is 1. then M must match name. You may input up to 99 files. If FAREMATRIX=FMI.).f[j+n] where: M Either a name or number. y (x specifies the FAREMATI index. There may be multiple records for a line.. If FAREMATRIX=FMI. To input the lines from a Cube geodatabase stored in an MDB file. Default value is 0. you need not specify an index. Possible values: • Y — Downgrade data errors found when reading lines data to data warnings. Cube Voyager Reference Guide 697 . the program stops processing lines. Therefore. the program assigns an index of 1. However. See “LINE” on page 745 for a list of keywords you can use. Append an index to each. LINEI SKIPBADLINES |?| Optional. Flag that indicates whether to list the lines file as input. Name of input file containing lines. The program will be able to read the entire input file without termination due to data errors. Without an index. routeevaluation. loading. 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. described with the LINE control statement). LINEI LIST |?| Optional. Indexes need not be monotonic or sequential. specify the file name followed by a backslash and the name of the geodatabase feature class. and loading-analyses processes. if inputting only one file. Valid index numbers range from 1 to 32. or in TP+ format. if you input Public Transport network with NETI. You must convert any lines files in TRIPS format to Cube Voyager format. When errors exceed this number. • The default value is the value of PARAMETERS SKIPBADLINES. The file can contain lines in Cube Voyager format (that is. do not specify LINEI should not be specified because the network contains line data. N — Treat data errors as errors. LINEI is required for the route-enumeration. You may input up to 32 lines files. Optional.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword LINEI Subkeyword |FKVf|2 Description Optional. Maximum number of errors permitted in lines files. Flag that indicates whether to treat data errors as warning. You must index LOOKUPI. For example: FILEI MATI[1]= TRIPSUC1. Name of file containing records for a lookup function implemented with the LOOKUP control statement. 698 Cube Voyager Reference Guide . MATI |FKVf|2 Optional. you can use the MATI keyword to input any type of matrix data into working matrices. MATI[4]=TRIPSUC3. You can define up to 10 matrix files to input. The Public Transport program only requires trip matrix files for the loading process. Because the run can compute trips.MAT. the PARAMETERS TRIPSIJ statement specifies which demand matrix the Public Transport program loads for each user class. and output the data with MATO. Index values can range from 1 to 10. Name of an input matrix file.MAT This statement names the input matrix files. the program assumes the index is 1.12 Public Transport Program Control statements FILEI keywords (continued) Keyword LOOKUPI Subkeyword |FKV999| Description Optional. Therefore. and then manipulate. MATI[3]=TRIPSUC3. Equivalent to the FILE keyword of the LOOKUP control statement.MAT. If you do not specify an index. report. you need not input trip matrix files. Networks produced by the Network program contain just the basic public transport infrastructure. NTLEGI and LINEI files unless you invoke the Public Transport Network Development function. In this case. Files can be produced by the Network program or a previous run of the Public Transport program. nodes. and links. you need not provide SYSTEMI. generated with the GENERATE control statement. the public transport network may also contain nontransit and transit loads. FACTORI. input with LINEI Factor data. if NETI specifies an input network produced by the Public Transport program. If specifying a Cube geodatabase network. Thus. stops. in addition to the basic infrastructure. They contain. the program only takes the basic network infrastructure from the NETI file. zones.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword NETI Subkeyword |FK| Description Name of the input network file. Cube Voyager Reference Guide 699 . Networks produced by the Public Transport program are complete public transport networks. input with FACTORI Nontransit legs. you must supply all other components. or both When produced by a Public Transport run in which trips were loaded. all the components that make a public transport network: • • • • System data input with SYSTEMI Line data. input with NTLEGI. enter the filename followed by a backslash and the name of the Cube geodatabase network. Files can be a Cube binary network file or a Cube geodatabase network store in an MDB file. List of origin zones for the route-evaluation.RTE. See “NT” on page 759 for a list of keywords you can use. ROUTEI[4]=ROUTESUC4. If you do not specify an index. and loading-analyses processes. Specify origin zones with single numbers or pairs of numbers separated by a dash. You can define up to 10 route files to input.RTE. 3. each user class has its own route file. For example. Valid values range from 1 to the network’s highest zone number. When you define an input route file for a user class. Name of input files containing nontransit legs. Index values can range from 1 to 32. Explicitly specify a unique file for each user class. Use commas to delimit each number or pair. You can define up to 32 input files. Name of the input route files. Append each keyword with the index of the user class. The GENERATE READNTLEGI statement defines valid indexes that the program will process. Indexes need not be monotonic or sequential. skimming. Index values can range from 1 to 10 (the number of user classes). If you do not specify an index. Append each keyword with an index. ROUTEI[3]=ROUTESUC3.RTE This statement defines input route files for user classes 1. one per user class. consider: FILEI ROUTEI[1]= ROUTESUC1. You can define input route files for some user classes and generate them for other user classes. the program assumes the index is 1. loading. ROUTEI I |IV1000| Optional. The PARAMETERS USERCLASSES statement defines user classes. the program bypasses the route-enumeration process for that user class.12 Public Transport Program Control statements FILEI keywords (continued) Keyword NTLEGI Subkeyword |FKVf|2 Description Optional. 700 Cube Voyager Reference Guide . the program assumes the index is 1. specify the file name followed by a backslash and the name of the geodatabase feature class. and 4. ROUTEI |FKVu|1 Optional. such as NTLEGI[5]. To input the nontransit legs from a Cube geodatabase stored in an MDB file. List of origin zones for reporting evaluated routes.Public Transport Program Control statements 12 FILEI keywords (continued) Keyword ROUTEI Subkeyword J |IV1000| Description Optional. ROUTEI REPORTI |IV1000| Optional. skimming. loading. Use commas to delimit each number or pair. Use commas to delimit each number or pair. Specify destination zones with single numbers or pairs of numbers separated by a dash. Cube Voyager Reference Guide 701 . Specify origin zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. The program writes the report to file specified with REPORTO. and loading-analyses processes. Valid values range from 1 to the network’s highest zone number. Specify destination zones with single numbers or pairs of numbers separated by a dash. ROUTEI REPORTJ |IV1000| Optional. See “Evaluated routes” on page 788 for an example of this report. List of destination zones for the routeevaluation. Valid values range from 1 to the network’s highest zone number. List of destination zones for reporting evaluated routes. Valid values range from 1 to the network’s highest zone number. 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 network’s highest zone number. ROUTEI TRACEJ |IV1000| Optional. List of destination zones for printing evaluated routes using the tabular-format route report. Specify destination zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. Valid values range from 1 to the network’s highest zone number. SCREENLINEI |FK| Optional. Name of a screenline file that produces intercept data for Public Transport matrix estimation. You can create the file with Cube or a text-file editor. The file must use the “link-count” format used by Cube Analyst’s Matrix Estimation program; the turns-count format is not supported. The file contains the definition of the screenlines (in terms of constituent links), along with link count and confidence-interval data. 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 line’s 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 class–specific 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 Transport–program 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 network’s highest zone number. By default, the program enumerates and saves routes originating from all zones. ROUTEO J |IV1000| Optional. List of destination zones for which the program enumerates routes and saves. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to the network’s highest zone number. By default, the program enumerates and saves routes bound for all zones. 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 network’s highest zone number. ROUTEO REPORTJ |IV1000| Optional. List of destination zones for which the program reports enumerated and evaluated routes Specify the list as a set of single numbers or 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 network’s highest zone number. ROUTEO SELECTBYMAT |S| Optional. Matrix used to produce I and J selections such that the program enumerates and saves routes only for the Is that have originating trips and the Js that have terminating trips. Normally, specify the trip matrix being loaded. For example, MI.x.NAME. For the evaluation, skimming, loading, and 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 network’s 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 network’s 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 network’s link variable that contains confidence-level data. The confidence level is expressed as an integer value, ranging from 1 to 10000. You must define either CONFVAR or DEFCONF. Use the DEFCONF keyword when a single confidence-level value applies to all links. SCREENLINEO SCREENLINEO COUNTVAR DEFCONF |S| |I| Name of the input network’s 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 network’s link variable that contains the screenline number. This variable has a value ranging from 1 to 9999 when a link forms part of a screenline, and a zero value for all other links. Cube Voyager Reference Guide 723 specify the file name followed by a backslash and the name of the geodatabase feature class. you can output a number of different analyses from a single run of the program. NOTE: Citilabs recommends producing files no larger than 2 GB. 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. Therefore. Name of file where the program saves the results of the stop-to-stop analyses.12 Public Transport Program Control statements FILEO keywords (continued) Keyword STOP2STOPO Subkeyword |FKV4| Description Optional. See “More on stop-to-stop analysis” on page 729. To save results in the Cube geodatabase (in MDB format). 724 Cube Voyager Reference Guide . the largest size that Cube Voyager and Cube Base can properly process. but not both. 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. File is either DBF format or MDB format. The two sets of data fields are mutually exclusive. You can specify up to four output files. 6. Must specify MODES subkeyword. regardless of intervening modes. Must specify MODES subkeyword.8 The program recodes any transit legs using modes 6. FIRSTLASTBYMODE — Movements from first node to last node on a particular mode. List of numbers the program uses to recode the modes on transit legs before completing stop-to-stop analysis on a route. STOP2STOPO GROUPEDMODES |IV999| Optional. ADJACENT — Movements for each leg of a trip. Thus. 7.7. See “More on stop-to-stop analysis” on page 729. For example. Cube Voyager Reference Guide 725 .Public Transport Program Control statements 12 FILEO keywords (continued) Keyword STOP2STOPO Subkeyword ACCUMULATE |S| Description Optional. Default value is FIRSTLAST. subsequent numbers are the modes recoded. Specifies types of transit movements included in the stop-to-stop analysis. Valid values range from 1 to the network’s highest mode number. (Relevant when transit movement type is ADJACENTBYMODE or FIRSTLASTBYMODE). First number is the mode number assigned during recoding. any transit legs with modes listed in the second are subsequent positions are assigned to the mode listed first. consider: GROUPEDMODES = 3. Possible types include: • • • • FIRSTLAST — Movements from a trip’s first node to last node. ALLONOFFS — Movements for all on-off combinations. or 8 to mode 3. • All movement types other than ADJACENT can contain one or more transit legs. ADJACENTBYMODE — Through movements from first node to last node on a particular mode. If you code both GROUPS and NODES. Note that the program does not explicitly report nodes in the output file. NOTE: If you code neither NODES nor GROUPS. Delimit each number or pair with a comma. 726 Cube Voyager Reference Guide . such as platforms within a station or clusters of bus stops on either side of a road. Flag indicating whether to list the contents of the DBF file to the printer file. You define a node’s stop-group number on the input network’s node record in the variable specified in STOPGROUP. Stop-groups are either single stop-nodes or a collection of stop-nodes. the program outputs stop-to-stop movements for the specified groups that will include only the specified nodes. the program includes all nodes belonging to the specified groups in the analysis. If you do not code NODES.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. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. you can exclude nodes from their groups. Valid values range from 1 to the network’s highest stop-group. Thus. Identify stop-groups by number. STOP2STOPO LIST |?| Optional. 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. the program generates a fatal error. u represents user class Example Some files that may be output by the Public Transport program. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. 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. but cannot disaggregate those movements to the nodes in the group. with STOPGROUP=SGNAME.prn ROUTEO = enumroute. J=1.SGNAME stores the stop-group numbers. Name of the node variable that contains the stop-group number. STOP2STOPO NODES |IV9999| List of stop nodes for which the program extracts stop-to-stop movements for the ACCUMULATE subkeyword. I=1. This subkeyword is required if GROUPS is not coded. Valid values range from 1 to the network’s highest mode.24. Delimit each number or pair with a comma. Valid values range from 1 to the network’s highest node. For example.net REPORTO = reports. 1.24.15.9.24 Cube Voyager Reference Guide 727 . Delimit each number or pair with a comma. you must code STOPGROUP. Default value is all modes. If you code GROUPS. REPORTI=1.Public Transport Program Control statements 12 FILEO keywords (continued) Keyword STOP2STOPO Subkeyword MODES |IV999| Description Optional. FILEO NETO = onetwork. then the node variable NI. the program reports on intragroup movements.15. 15.24 REPORTJ=1. When using stop groups. used in GROUPS. STOP2STOPO STOPGROUP |S| Optional.rte. In the past.12 Public Transport Program Control statements Example of SCREENLINEO & INTERCEPTO RUN PGM=PUBLIC TRANSPORT FILEO REPORTO = "PAPTR00B. However. PT network output from PT program ENDRUN Considerations on numeric formats Traditionally planners have maintained most transportation planning matrices in integer format. only a few decimal places are required for each cell value. this is not necessarily true with newer computers. computers could process integers much faster than floating point numbers.RTE" FILEO SCREENLINEO = "PT ANALYST EXAMPLE\PAPTR00B. SCREENVAR=SCRLNO COUNTVAR=PTCOUNT CONFVAR=PTCONF FILEO INTERCEPTO = "PAPTR00B. the Public Transport program stores matrix values with a special packing routine that tries to minimize the file’s space requirements. writing double-precision numbers to the matrix files would generate very large files. and cannot always maintain the precision required for certain types of matrices. However.NET" . The 728 Cube Voyager Reference Guide . Cube Voyager processes all matrices in double-precision (16 digits) format to accommodate a wider range of values.DAT". 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.ICP" FILEI NETI = "PAPTR00D. and to not lose precision or accuracy when computing.PRN" FILEO ROUTEO[1] = "PAPTR00B. Therefore. 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. Single-precision floating point provides only six to seven digits of precision. and in most cases. the movement type affects the output records. consider a cell computed as 10/3. With this keyword. More on stop-to-stop analysis For stop-to-stop analysis. you can group distinct modes of the route together. to sixteen digits. requiring four bytes to store... If DEC is 2 for that number. Use the GROUPEDMODES subkeyword to recode modes prior to transit-route analysis. the program writes output records that reflect the modes used in the route’s transit legs. Cube Voyager Reference Guide 729 . If DEC were S. If DEC is D or S. Upon reading. a model might use two or more mode numbers for different types of rail travel. it would be stored as an 8-byte double-precision. If not specified. The S and D formats require more storage space. the result is 3. that might not be precise enough for the programs that read it.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.33333333. the program skips the integer conversion attempt and stores all cells as either 8-byte double values or 4-byte single values. you eliminate this detail from the analysis. and if DEC were D. the value would be stored as a 4-byte single-precision. the resulting integer is 333. The program analyzes a transit route based on the values of other STOP2STOPO subkeywords.. If converted to an integer while DEC is 0. DEC defaults to 2. By grouping the discrete rail modes together. another application will automatically restore the number to 3. You might be more interested in transfer to or from rail than in changes between the different rail modes. the result is accurate to about seven digits. However. the program stores the cell as a double-precision value. requiring two bytes to store. and the cell would require only one byte to store—a significant reduction. For example.33. The result is 3. allowing them to appear as one mode for analysis and in subsequent data output. When the movement type is 4 or 5 (ACCUMULATE is FIRSTLASTBYMODE or ADJACENTBYMODE). When changed to single precision. and saves the appropriate records. For example. 5-6. 5-8. followed by the leg with the lowest distance (DIST ). 3-4. 1-4. 7-8. The Public Transport program maintains one table of nontransit legs. 5-6 on mode 2 4. 9-10 on mode 1 Value of ACCUMULATE FIRSTLAST ADJACENT ALLONOFFS FIRSLASTBYMODE Movements analyzed 1-10 1-2. 9-10 1-2. 1-10. two-mode trip: 1. 3-6. 1-2 on mode 1 2. 5-6. 3-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. 3-4 on mode 1 3. or generate and input nontransit legs. Use the READNTLETI keyword to input previously generated and validated nontransit legs or externally generated ones. 7-8 on mode 1 5. 3-8. The program keeps one leg for each Anode–B-node combination in the table—the leg with the lowest EXTRACTCOST. The program dynamically updates the table while processing GENERATE statements. 730 Cube Voyager Reference Guide . input. 7-8. 1-6. 1-8. each with different criteria. 7-10.12 Public Transport Program Control statements Example of ACCCUMULATE subkeyword Suppose you have a five-leg. 3-4. 5-10. You can generate. You can use one or more GENERATE control statements to generate nontransit legs. MAXNTLEGS specifies the maximum number of legs the program will generate for a mode from a FROMNODE. See NTLEGI under “FILEI” on page 694. Use the necessary keywords to control the nontransit linkgenerating process produced by the GENERATE statement. adding acceptable legs to the legs table. The program ignores nodes specified in TONODE that are not stop nodes. and compares the cost to the mode’s MAXCOST. Finds transit modes at each node specified in TONODE. GENERATE statements must be in the DATAPREP phase. computes the cost to the node. For example. If you specify neither file.Public Transport Program Control statements 12 and then the leg with the lowest NTLEGMODE. If SLACK is not specified. Cube Voyager Reference Guide 731 . the program saves the leg. the program saves the legs in the table to the Public Transport network file specified by NETO and/or the file specified by NTLEGO. the slack for a mode effectively becomes the difference between the best cost and the MAXCOST for the mode. The program adds the best leg for a mode. If the cost for at least one of the modes is less than the mode’s MAXCOST and if the specification in DIRECTLINK is satisfied. the program: • Builds minimum-cost routes between each node specified with FROMNODE to each node specified with TONODE that is a transit stop. • • • None of the GENERATE keywords are “trigger” keys. Examines each saved leg. 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. you must code all keywords on a GENERATE control statement. Merges legs using any special transaction codes. the program discards the legs at the end of the run. With this statement. you might specify that the program replace a generated leg with a longer leg. After processing all GENERATE statements. the program generates the link. If ACCESSLINK only contains one value. Paired values indicate the start of new access links. If ACCESSLINK provides numeric values for cost and distance. Distance traveled on this access link (real). Specify an access link as: A-S. Cost of using this access link (real). the program adds them to the link’s cost and distance.12 Public Transport Program Control statements GENERATE keywords Keyword ACCESSLINK |R| Description Optional.cost. One or more access links from park-and-ride facilities to stop nodes. If the link does not exist in the network. the program adds that value to the link’s cost. The program obtains the cost from the route to the A-node. Valid values for A and S are 1 to the network’s highest node number. Separate each access link with a comma. You specify pairs of numbered sets. distance — Optional. Enter paired values in the correct order to avoid generating an error. 732 Cube Voyager Reference Guide .distance where: • • • • A — Surrogate access point (integer) S — Stop node (integer) cost — Optional. the program ignores any TONODE keywords. If you specify ACCESSLINK. which is specified by mode. both actual and perceived costs may be skimmed. NTLEGMODE=32 This script fragment generates nontransit legs on the basis of minimum distance. the program applies no limit to number of links.x. You may exclude links from the GENERATE process with network data items. and speed.Distance. FROMNODE to TONODE 2 — Reverse direction. time. TONODE to FROMNODE 3 — Both directions. and classifiers. Maximum number of network links a nontransit leg can traverse. you can factor the nontransit leg cost. COST=li. The route-enumeration and evaluation processes use perceived (or factored) costs. such as link distance. with the FACTORS RUNFACTOR control statement. DIRECTION |I| Optional. such as link distance. Optional. EXTRACTCOST=li.Time. Enclose expressions in parentheses. derived from COST or EXTRACTCOST. For example. but skims time along the minimum-distance legs and saves as the cost. you can skim the cost specified by EXTRACTCOST from the network links underlying the nontransit legs. EXCLUDELINK |N| Optional. The expression can contain network data items. To obtain the perceived nontransit cost. Enclose expressions in parentheses. Expression that computes the network links to exclude from the generation of nontransit legs. Integer indicating direction of the generated nontransit legs. Cube Voyager Reference Guide 733 . consider: GENERATE. You can factor with RUNFACTOR[32]=x. Used to determine the minimum-cost nontransit legs between the nodes specified in FROMNODE and TONODE (or ACCESSLINK). Possible values: • • • DIRECTLINK |I| 1 — Forward direction. The cost of nontransit legs may be the cost on the basis of which they are built or. The sample script fragment produces nontransit legs with a mode of 32. cost. By default. FROMNODE to and from TONODE Default value is 3.Public Transport Program Control statements 12 GENERATE keywords (continued) Keyword COST |N| Description Expression for computing network link costs. and speed. The expression can use network data items. If you do not specify this keyword. You may specify nodes as numeric values or names of variables that store valid numeric values. INCLUDELINK |N| Optional. 734 Cube Voyager Reference Guide . you can factor the nontransit leg-cost derived from COST or EXTRACTCOST with the FACTORS RUNFACTOR control statement. you might specify: FROMNODE=1-NUMZONES Valid values range from 1 to the network’s highest node number. and classifiers. The skimmed costs become the costs of the nontransit legs. Enclose expressions in parentheses. to compute the cost. such as link distance. See “More on using LIST keyword” on page 738.12 Public Transport Program Control statements GENERATE keywords (continued) Keyword EXTRACTCOST |N| Description Optional. Enclose expressions in parentheses. To compute perceived nontransit costs for use in the enumeration and evaluation processes. such as link distance. cost. LIST |?| Optional. Expression that computes the network link costs skimmed from nontransit legs built on the basis of COST. time. the program derives the cost of nontransit legs from the COST keyword. F — Do not list nontransit legs. The expression can use network data items. FROMNODE |S| Optional. Default value is F. Possible values: • • T — List each nontransit leg and the network links traversed. Flag indicating whether to list nontransit legs. For example. to determine included links. Expression that computes network links included in the generation of nontransit legs. Node or list of nodes that program generates nontransit legs from. 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. Valid values range from 1 to 999. Minimum cost allowed for a particular transit mode to enable generation of nontransit legs. However. However.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. if the TONODE specifies a zone. Valid values are 0 to 500 (in the same units specified in COST). Default value is 5. Default value is 0. 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. Valid values range from 1 to 999. Valid values are 0 to 500 (in the same units specified in COST). The default value is 0. When determining the maximum cost for a leg. Therefore. MINCOST |RVt*|1 Optional. Flag indicating how to use one-way links when generating nontransit legs. the program uses the mode of the FROMNODE. If both FROMNODE and TONODE are zones. You must specify MAXCOST for at least one mode. Maximum number of nontransit legs to generate for a particular transit mode from a FROMNODE to a TONODE serviced by that mode. Cube Voyager Reference Guide 735 . Specify cost per mode. MAXNTLEGS |IVt| 1 Optional. 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. the program ignores MAXNTLEGS. the program uses the mode of the FROMNODE. the program uses the mode of the TONODE. The value of SLACK affects the value of MAXCOST. the program uses the mode of the TONODE. You must specify a value. NTLEGMODE |I| Nontransit mode assigned to the generated nontransit legs. When determining the minimum cost for a leg. if the TONODE specifies a zone. ONEWAY |?| Optional. unless other non-zero modes service the node. the program generates no trips to nodes serviced by modes without a MAXCOST specified. If you do not specify SLACK. the program ignores SLACK. 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. SLACK generally refers to the modes serviced by the TONODE. Valid values range from 1 to 7. SLACK |RVt| 1 Optional. the program obtains the mode from the FROMNODE. You must code a corresponding FILEI NTLEGI statement. 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. Specify per mode. the program reads nontransit legs from a file and merges them into the generated links table. However. If SLACK is set to zero. For example. If both FROMNODE and TONODE are zones. the program only uses MAXCOST to limit nontransit-leg generation. the program only saves the best-cost legs. Default value for any mode is the value of MAXCOST for that mode. 736 Cube Voyager Reference Guide . No other keywords are valid with READNTLEGI. the program will save legs with a cost up to 14 minutes. consider: MAXCOST[4]=20. When you code READNTLEGI. Use a separate GENERATE statement for each nontransit leg file input. Delimit data fields with commas or spaces. With SLACK specified.12 Public Transport Program Control statements GENERATE keywords (continued) Keyword READNTLEGI |I| Description Optional. SLACK[4]=8 If the best leg has a generalized cost of 6 minutes. Index number of the input nontransit leg file. MAXCOST provides the primary control. Use FROMNODE and TONODE with READNTLEGI to filter input records through the from. The NT control statement determines the format of the input records. Amount added to the best-cost nontransit leg between the two nodes to determine the maximum cost of legs saved. SLACK provides a secondary control for restricting the generation of nontransit legs.and to-nodes. if the TONODE is a zone. Valid values are 0 to 500 (in the same units specified in COST). 1 (currently the same result as setting to 0). set to include all nodes (number of zones +1 to the network’s highest node number). possibly preventing valid routes. Node or list of nodes to which the program generates nontransit legs.1 introduced a new algorithm that creates nontransit legs between pairs of nodes where a transit line operates.1). Integer that specifies algorithm program uses to execute GENERATE control statement. • • Default value is 0. By default. Earlier versions excluded such legs. 1 — Use the algorithm from version 4. and SLACK as in version 4. the program uses the version 4. 1. Possible values: • 0 — Use the latest algorithm (currently. using the maximum costs from the initially-generated legs as limits. Use this setting when modeling best-path routes (that is. XFERMETHOD |I| Optional. when FACTOR BESTPATHONLY=T ).1 algorithm to create additional legs.0. Valid values range from 1 to the network’s highest number.Public Transport Program Control statements 12 GENERATE keywords (continued) Keyword TONODE |S| Description Optional. Specify nodes as numeric values or names of variables that store valid numeric values.0 when creating nontransit legs.0 algorithm for generating connectors with the additional connectors created with the version 4.1 algorithm. if you wish to use newly identified connectors while not losing any previously generated connectors. 2 — Supplement the version 4. • 3 — Use the algorithm from version 4. the algorithm developed with version 4. This value is appropriate for models developed under version 4. t indicates number of transit modes Cube Voyager Reference Guide 737 .0. MAXNTLEGS. The program ignores TONODE if the GENERATE control statement contains the ACCESSLINK keyword. The program creates an initial set of nontransit legs using keywords such as MAXCOST. The total number of legs generated might exceed limits specified in MAXNTLEGS. Version 4. Next. LINKTYPE=30-32). SLACK=20*5. COST=LI. MAXCOST=20*10. PHASE=DATAPREP //Note: the GENERATE command must precede controls //GENERATE 1: Access and Egress links for zones 11272 GENERATE.. While processing statements.LINKTYPE=1. MAXCOST=20*20.80..8-13. followed by the one with the lowest distance (DIST ). TONODE=1273-5644.20. INCLUDELINK=(li. followed by the one with the lowest NTLEGMODE.0. FROMNODE=1-1272. The table stores exactly one leg for each combination of A-node and B-node—the one with the lowest EXTRACTCOST. DIRECLINK=5 //GENERATE 2: Transfer legs for the PT Network GENERATE. MAXNTLEGS=20*5.time. The second GENERATE statement produces transfer legs between stops. FROMNODE=1273-5644. NTLEGMODE=100.Distance*60/4.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 program adds legs to a table of nontransit legs. TONODE=1273-5644.30-32). DIRECTION=3. 738 Cube Voyager Reference Guide . COST=li.4. INCLUDELINK=(li. DIRECTION=3. SLACK=20*5. NTLEGMODE=100. MAXNTLEGS=5. ENDPHASE More on using LIST keyword You may use one or more GENERATE statements to generate nontransit legs. 2052 .Public Transport Program Control statements 12 If a GENERATE statement has LIST set to T.36 0. a GENERATE statement might list one leg.36 0. that leg might not be included in the final table of legs. MAXCOST=12*1.distance).18 Link 2052 1 35 0. the program lists the legs in the table when that statement is processed.xcost). DIRECTION=3.xcost). Though the program might list a leg during GENERATE.18 M(625): 2 Nontransit Legs 0.xcost). GOTO label Cube Voyager Reference Guide 739 . LIST=T. if the later statement revises the leg.36 1 3674 1 3674 The final nontransit legs saved will be: 1 . FROMNODE=1.18 Link 2052 1 36 0. To view or report the final set of nontransit legs. save them to the file specified with the FILEO NTLEGO control statement. TONODE=2052 LIST='GEN2' GENERATE COST=(li. EXTRACTCOST=(lw. DIRECTION=3.distance). EXTRACTCOST=(lw. EXTRACTCOST=(lw. LIST=T. NTLEGMODE = 36.35 (and reverse) GOTO Jumps immediately to a named statement. The following example illustrates this process: LIST='GEN1' GENERATE COST=(li. and a later GENERATE statement a different leg. FROMNODE=1. NTLEGMODE = 36. MAXCOST=12*1.18 GEN2 GEN3 Link 1 2052 35 0. Similarly.TONODE=2052 The printed result of this will be: GEN1 Link 1 2052 36 0.distance). FROMNODE=1. MAXCOST=12*1. DIRECTION=3. NTLEGMODE = 35 LIST=T.36 1 3674 1 3674 0. TONODE=2052 LIST='GEN3' GENERATE COST=(li. ENDIF blocks........... Example In this example... ELSE . ENDIF Performs certain operations based on conditions. the GOTO statement passes control in the forward and backward directions.. ELSEIF . but with a dot (. :hwybuild IF (expression) GOTO :hwybuild IF. The target statement must begin with a colon (:). They may not overlap LOOP . ELSE .. named “:label. Use care when the :label statement is within a different IF or LOOP block. 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......” Each GOTO statement must have an associated :label statement. ENDLOOP blocks.12 Public Transport Program Control statements When GOTO is processed. . (The program automatically defines any variables not predefined.. GOTO hwybuild . You may append the following control statements to a single IF statement: • BREAK 740 Cube Voyager Reference Guide . ELSEIF .) You may nest but not overlap IF... flow immediately branches to the target statement.) in their name as numeric variables. . Cube Voyager Reference Guide 741 . or IF blocks. ENDJLOOP blocks for matrix computations that you cannot complete with a single COMP MW control statement. ELSEIF (loop_cntr > 10) . ENDJLOOP Controls a loop over the column cells (J) of the current row (I) in a matrix... and may not overlap other JLOOP.6-30.time_to_bcd > 200000) GOTO :SKIPZONE IF (expression) EXIT One example of the IF block statement. you use JLOOP . Typically.56)) ... ENDIF JLOOP ... ELSE .. LOOP.. IF (matrix.57 & k=(2*j-4)) || ((J*k) = 14-20. Each row represents an origin (I) zone and each column represents a destination (J) zone..time < 32) . ELSEIF (loop_cntr > 5 && diff... IF((j=3-5...Public Transport Program Control statements 12 • • • • COMP CONTINUE EXIT GOTO PRINT • Example Two of uses of the single IF statement... JLOOP blocks may not be nested. Jend defaults to the number of zones in the network. J. List of up to three integers that define the value of the loop control variable. In that case. • • Because the list of values for J can be expressions. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. The logic for JLOOP and ENDJLOOP processing is: • At JLOOP: If J is specified. depending on the direction from Jbeg to Jend. Jend. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. Jend=Zones. Jend defines the terminal value of the loop’s control variable. you must separate the values with commas. Enclose expressions containing commas in parentheses. Valid values range from 1 to the network’s maximum number of zones. and Jinc defaults to 1. • At ENDJLOOP: Add Jinc to J. Else set J=1. 742 Cube Voyager Reference Guide . Jinc where: • Jbeg defines the initial value of the loop’s control variable. set to 1 or -1. terminate fatally. If not specified. Control passes to statement following ENDJLOOP. If you do not define Jbeg.12 Public Transport Program Control statements JLOOP keywords Keyword J |I| Description Optional. establish values for Jend and Jinc. If (J < 1 or J > Zones or Jend <1 or Jend > Zones). Process statements within JLOOP. and Jinc defaults to 1. you cannot define Jend or Jinc. A JLOOP block causes the program to loop between the JLOOP statement and its ENDJLOOP statement. Default value is 1. Specify as: J=Jbeg. Jinc=1. You may define each integer with an expression. Jend defaults to Jbeg. J. If not specified. Jinc defines the increment for the loop’s control variable. J. moving J from Jbeg to Jend in increments of Jinc. ELSEIF . JLOOP is invalid (the phase is executed once per IJ pair) SELECTIJ and SKIMIJ 1. Cube Voyager Reference Guide 743 . JLOOP statements are valid. However... The following statements are valid within a JLOOP block: • • • • BREAK COMP CONTINUE EXIT GOTO (:label statement must be inside current JLOOP) IF. ELSE . including COMP MW statements.. Program executes JLOOP once.. Program executes JLOOP once per matrix row (or origin zone). You may use J keyword to select destination zones. and will act as a zonal loop. Program performs no matrix processing during these phases. ENDIF PRINT • • • JLOOP processing varies by phase. there is no destination zone. Phase NODEREAD and LINKREAD1 DATAPREP1 MATI and MATO JLOOP processing Program executes JLOOP for each node or link processed. with the current value of J..Public Transport Program Control statements 12 The program processes all statements between the JLOOP and ENDJLOOP statements. Therefore.. 1.1 * 0. NUMBER NUMBER NUMBER NAME LONGNAME CURVE |S| |S| |RKV1 0000| Optional. JLOOP J=1. Separate X and Y values in a pair by a comma or a dash. NOTE: Must be the first keyword coded in an LATECRVDEF control statement. Second unique string that identifies the lateness curve (in addition to NAME). ROWSUM1 = 0 ROWSUM3=0 JLOOP ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP Example 2 Print the first ten cells of each row. Separate each pair with a comma. Optional. Valid values range from 1 to 255.) Curves should be such that y values never decrease as X increases. LATECRVDEF keywords Keyword NUMBER Subkeyword |I| Description Unique number that identifies a lateness curve. List of X-Y coordinates that define the lateness curve. Unique string that identifies the lateness curve. J. 744 Cube Voyager Reference Guide . The X-axis shows headway and the Y-axis shows wait time. TRIPSIJ ENDJLOOP LATECRVDEF Defines a lateness curve (in similar style to wait curves.25 TRIPSIJ=MI. Which curve is used is defined in the factor file for the user class.75 IF(J > 10) BREAK PRINT LIST=I.12 Public Transport Program Control statements Example 1 Compute the sum of each row for two matrices. NNTIME. TIME. ACCESS_C. and XYSPD). and VOL. These data items form part of an output FILEO LINEO file.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. Nodes have their own attributes. TF. which you define with the NODES keyword. but the program does not read this data when processing a FILEI LINEI file. Cube Voyager Reference Guide 745 . ON. The Public Transport program’s loading models append the results of the loading process to line nodes. LINE keywords describe the line’s attributes. FMVOL. Lines traverse two or more nodes. in up to seven files with FILEI LINEI. using the keywords FMOFF. some are optional. or in the Public Transport network file with FILEI NETI. Some are required. SPEED. OFF. None are “trigger” keys. FMON. You may input lines to the Public Transport program in ASCII format. you must code all keywords on a LINE control statement. DELAY. When crowding is used. 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. the Public Transport program’s Loading Models append results of a crowd run to the output LINE data with the FMCAPACITY keyword. defined with subkeywords (ACCESS. RT. DELAY_C. Possible values: • • CIRCULAR |?| T — Program makes all the line’s nodes into stop nodes. F — Indicates line is linear. 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. Crowd curve used to adjust link travel times for a modeled user class. Optional. F — Program uses node designation. A route can go through this node without incurring any boarding and transfer penalties or waiting time. 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.12 Public Transport Program Control statements Several of the LINE keywords and NODES subkeywords adjust network link times by line. LINE keywords Keyword NAME ALLSTOPS Subkeyword |S| |?| Description Unique string identifier for a transit line. Possible values: • • T — Indicates line is circular. 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. Default value is F. CROWDCURVE |IV10| Optional. Flag indicating whether all nodes in the line are stop nodes. Flag indicating whether a line is circular or linear. Default value is F. 746 Cube Voyager Reference Guide . Valid values range from 1 to 255. Optional. boarding and transfer penalties plus wait time—for routes passing this node. NAME must be the first keyword in a LINE control statement. Default values are those specified in the VEHICLETYPE control statement. Linear lines may also have the same first and last nodes but passengers must incur a boarding—that is. even those explicitly designated as nonstop nodes. Must be greater than or equal to any specified seating capacity.000. If coding only one headway value.000. between two vehicles on a line. You can code up to five different headways for a line. HEADWAY |RV5| Interval. you must enter each index separately. such as HEADWAY[1]=10. which form part of a FILEI FAREI file. The program does not read in or store this value when processing a FILEI LINEI file containing this data. Line’s capacity when the program runs a crowding model and writes the resulting line data file. List required and no default provided. which defaults to 1 or the value associated with a FILEI ROUTEI file. Valid values range from 1 to 20. The FARESYSTEM control statement defines fare systems (see “FARESYSTEM” on page 687). Cube Voyager Reference Guide 747 . Optional. The program selects the headway for a run from PARAMETERS HDWAYPERIOD. Valid values range from 1 to 20. Overrides value provided by FACTORS FARESYSTEM control statement. Valid values range from 1 to 2000. FMCAPACITY |R| Optional. Valid values range from 1 to 1999. HEADWAY[3]=30. in minutes. 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. The value specified with the FACTORS control statement may vary by user class. Line’s fare-system number. sum of seated and maximum-standing capacities) of vehicles operating on this line. HEADWAY[2]=20. You cannot enter HEADWAY=10. Fare systems entered with this keyword must be defined in a FILEI FAREI file.Public Transport Program Control statements 12 LINE keywords (continued) Keyword CRUSHCAP Subkeyword |I| Description Optional. DAYTYPE FARESYSTEM |IPa*| |I| List of day types on which line operates.30. If entering multiple headways. you may enter either HEADWAY=x or HEADWAY[1]=x. Default values are those specified in the VEHICLETYPE control statement. and applies for all user classes. Crush capacity (that is.20. At this seat-occupancy point. between two vehicles on a line in the reverse direction of a two-way line. Load distribution factor—the percentage of seats occupied when standing first occurs. The default value is the value of HEADWAY (the value in the forward direction). LOADDISTFAC |R| 748 Cube Voyager Reference Guide . You can code up to five different headways for a line. you must enter each index separately. use is only necessary when start times have ranges. Integer indicating mode of the transit line. If entering multiple headways. If coding only one headway value. Valid values range from 1 to 999. LONGNAME MODE |S| |I| Optional. The default value is the value specified with the VEHICLETYPE keyword. such as HEADWAY_R[1]=10. INTERVAL |Rc| Defined headway between departures from starting node when an interval is specified in STARTTIMES. which defaults to 1 or the value associated with a FILEI ROUTEI file.0 to 100. Interval. HEADWAY_R[2]=20. Optional. Valid values range from 0. you may enter either HEADWAY_R=x or HEADWAY_R[1]=x. in addition to NAME.12 Public Transport Program Control statements LINE keywords (continued) Keyword HEADWAY_R Subkeyword |RV5| Description Optional.0. You cannot enter HEADWAY_R=10. 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. Specified in minutes. Second unique string identifier for a transit line.20. HEADWAY_R[3]=30. Valid values range from 1 to 2000. in minutes.30. passengers begin experiencing increases in perceived travel time due to crowding. The program selects the headway for a run from PARAMETERS HDWAYPERIOD. that node’s value must be 0 or 2). Valid values are 0. 1. You must specify at least two stop-nodes for a line. you may use N as an alias for NODES. the program generates a link. If you code the NODES keyword multiple times for a line. To ease the coding in such cases. commas. otherwise passengers cannot ride to the end of the line.Public Transport Program Control statements 12 LINE keywords (continued) Keyword NODES or N Subkeyword |I| Description List of nodes that the transit line traverses. Default value is 0. When using ACCESS_C. exit only. NODES DELAY |R| Optional. Use negative node numbers to indicate nonstopping nodes. or access and exit. The program inverts the access restriction for the line’s reverse direction. calculating the link’s distance from the node coordinates and taking the speed from XYSPEED or XYSPD. If you insert a subkeyword in the list of nodes. you must enter the NODES keyword again. If two consecutive nodes do not map to a link in the underlying Public Transport network. Integer indicating ACCESS value for a stop node and all subsequent stop nodes until you specify the next ACCESS or ACCESS_C keyword. Separate node numbers with spaces. NODES ACCESS |I| Optional. Code between the two nodes that compose the link. Valid values range from 1 to the network’s highest node number. the program joins the last node of the previous node list and the first node of the next node list to form a link. Valid values are any number greater than or equal to 1. or 2. following the subkeyword value. or dashes. Additional time delay added to the link time. you must check that the line’s last node allows exiting (that is. Cube Voyager Reference Guide 749 . Citilabs suggests coding the NODES keyword as the line’s last keyword. Valid values are: • • • 0 — Stop for access and exit 1 — Stop for access only 2 — Stop for exit only Default value is 0. Integer indicating whether a stop node is for access only. NODES ACCESS_C |I| Optional. in minutes. Default value is 0. Flow-metered number of passengers alighting from the line at the preceding node. the line spends at the preceding stop node and all subsequent stop nodes until you specify another DWELL or DWELL_C subkeyword. Valid values are numbers greater than or equal to 0. This is the result from running a crowding model. 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). in minutes. NODES DWELL |I| Optional. Additional time delay added to the link time and all subsequent link times until you specify the next DELAY_C or DELAY keyword. Dwell time. Valid values range from 0 to 999.12 Public Transport Program Control statements LINE keywords (continued) Keyword NODES Subkeyword DELAY_C |R| Description Optional. Flow-metered number of passengers boarding the line at the preceding node. Valid values range from 0 to 999. Optional. which accounts for bottlenecks in the public transport network when loading demand data (see “Crowd modeling” on page 639). which accounts for bottlenecks in the public transport system when loading demand data (see “Crowd modeling” on page 639). NODES FMON 1 |R| NODES FMVOL 1 |R| 750 Cube Voyager Reference Guide . NODES FMOFF 1 |R| Optional. Flow-metered number of passengers the loading models (with crowding) assign to the link connecting the preceding node and the next node. Valid values are any number greater than or equal to 1. Valid values are numbers greater than or equal to 0. Dwell time. Optional. This is the result from running a crowding model. Valid values are numbers greater than or equal to 0. Default value is 0. NODES DWELL_C |I| Optional. the line spends at the preceding stop node. 6. The program does not set travel time between nodes to zero.2. in minutes.3. NODES=1. In this case.7.3. NNTIME=-1.7. The PARAMETERS keyword TRANTIME sets the expression for computing base transit travel time for links in the highway network. Statements that set NNTIME to -1 (or to 0) start the time counter from the last node listed. NODES=5. NODES=1.7. NODES=5. Statements that set NNTIME to a non-zero. The program adjusts (that is.4. NNTIME=-1.3. For example: NODES=1. NODES=5.2. NNTIME=5 Sets the time from node 4 to node 7 to five minutes. doing so produces an error.6.2. the program retains the computed travel time.6. NODES=1.4. Do not use NNTIME for two-way lines.3.2. NNTIME=-1. the NNTIME=-1 is unnecessary.Public Transport Program Control statements 12 LINE keywords (continued) Keyword NODES Subkeyword NNTIME |R| Description Optional.4. positive value set the travel time between the last node listed and the previous node where the time counter started.7. Travel time. and sets the time from node 4 to node 7 to fifteen minutes. and the time from node 4 to node 7 to six minutes. NODES=8. NNTIME=10 Sets the time from node 1 to node 4 to ten minutes. between the most recent node and the node preceding the last NNTIME keyword. NNTIME=10. Cube Voyager Reference Guide 751 . NNTIME=10.4. NNTIME=15 Sets the time from node 1 to node 4 to ten minutes.4. The program automatically starts the time counter at a line’s first node.3. and the time from node 7 to node 9 to ten minutes.6. and restart the time counter at the last node listed. NODES=5.9. overrides) the computed link and delay times between the nodes to reflect the NNTIME value.2. NNTIME=5. NODES=1. The LINE keyword XYSPEED and subkeyword XYSPD set speeds for links not in the highway network. NNTIME=10 Sets the time from node 4 to node 7 to five minutes. NNTIME=6 Sets the time from node 1 to node 4 to ten minutes. and adjusts accumulated times to downstream nodes.12 Public Transport Program Control statements LINE keywords (continued) Keyword NODES Subkeyword OFF 1 Description |R| Optional. and then uses that value. NODES ON 1 |R| NODES RT |R| NODES SPEED |R| Optional. the program makes subsequent adjustments from the node of prior adjustment. Valid values are numbers greater than or equal to 1. Number of passengers alighting from the line at the preceding node. NODES TF |R| Optional. Valid values are numbers greater than or equal to 0. Optional. Time factor applied to the current link and subsequent links until encountering another TF subkeyword or SPEED subkeyword. the program implicitly sets to zero. This is the result of a loading operation performed by the load models. until the next SPEED or TF subkeyword. Speed for all subsequent links in the line. Valid values are numbers greater than or equal to 1. Intermediate run time from the line’s first node to the most recently coded node. the values must increase. If you code more than one RT subkeyword. The program adjusts the accumulated time to the most recent node to match the specified value. Valid values are numbers greater than or equal to 0. and any previous TF or SPEED subkeywords. Valid values are numbers greater than or equal to 1. Overrides the value specified in TIMEFAC. Do not code RT at the first node. If coding multiple RT subkeywords. Optional. The program uses TIMEFAC for links the line traverses until encountering SPEED or TF. Number of passengers boarding the line at the preceding node. RT and keyword RUNTIME are mutually exclusive. This is the result of a loading operation performed by the load models. 752 Cube Voyager Reference Guide . SPEED overrides the TIMEFAC keyword value. TIME=5. RT. Sets the line’s speed for the current link and any subsequent links not in the input network until encountering the next XYSPD subkeyword. NODES XYSPD |R| ONEWAY |?| Optional. or RUNTIME. Cube Voyager Reference Guide 753 . Number of passengers the loading models assign to the link from the preceding node to the next node. Integer indicating operator of the transit line. For example: N=100. The link time is subject to adjustment by NNTIME. Default value is T. Valid values are numbers greater than or equal to 1. Valid values range from 1 to 999. NODES VOL 1 |R| Optional. Possible values: • • T — Coded line is a one-way line. Do not code XYSPD for two-way lines. N=103 Sets the time for link 102-103 to five minutes. Doing so produces an error.Public Transport Program Control statements 12 LINE keywords (continued) Keyword NODES Subkeyword TIME |R| Description Optional. Flag indicating whether line is one way.101. OPERATOR |I| Optional. You can define public transit operators with the OPERATOR control statement. F — Coded line is a two-way line. Time to traverse the link that connects that last node specified with the next node specified. Valid values are numbers greater than or equal to 0. Overrides the value of XYSPEED. Optional. Valid values are numbers greater than or equal to 1. The reverse direction is treated as a separate line for processing. Replaces link time computed using coordinates and XYSPD or XYSPEED.102. the program adjusts the time on all of the line’s links so that the time sums to this value. TIMEFAC |R| 754 Cube Voyager Reference Guide . Seating capacity of vehicles operating on this line.12 Public Transport Program Control statements LINE keywords (continued) Keyword RUNTIME Subkeyword |R| Description Optional. STARTTIMES |RPa| A list of departure times of runs from the first/starting node. When you specify RUNTIME. the program obtains default information from the vehicle type and overrides that information with attribute data. You may code in conjunction with the VEHICLETYPE keyword. Valid values are numbers greater than or equal to 1. Ranges are “expanded” into discrete runs using the interval value immediately preceding the start times Optional. delays. and ranges of values (e. 07000900) may be specified. VEHICLETYPE |I| Optional. Time factor applied to the travel time of all links the line traverses. you can code the vehicle type or its attributes in the LINE statement. Valid values range from 1 to 255. The program only scales the link’s travel time and DELAY and DELAY_C components. and intersection delays exceeds the specified value. then the program increases the value of RUNTIME to this total. When including crowd modeling. If you set PARAMETERS EXTENDRUNTIMES to true and the total time calculated from link times. in minutes. The program applies this factor until encountering a NODES TF keyword or NODES SPEED keyword. The program retains the original values of dwell times and intersection delays.000.000 minutes. SEATCAP |I| Optional. Defaults to value specified with VEHICLETYPE.g. Valid values range from 1 to 10. Integer indicating vehicle type operating on this transit line. If you code both the vehicle type and the attributes of the vehicle type. Valid values range from 1 to 30. from the first node to the last node. Values are in hhmm format. Line’s scheduled time. Use the VEHICLETYPE keyword to override the seating capacity value with a line-specific capacity. dwell times. 776. If the link does not exist in network. Valid values range from 1 to 300. 759. 760. 774. -777. Add turn penalties to the approach link of the modelled intersection. The program uses a twopart approach to process the keywords and obtain a line’s final link times: 1. -756. Qualified links do not exist in the input network. or TF. Speed on qualified links in this transit line. 773. -3673. SPEED. CIRCULAR=F. N=778. as appropriate. and both nodes in the link have valid coordinates. The Public Transport program saves the results of a loading operation to this NODES subkeyword. 1. HEADWAY=12. if specified. OWNER=11. enabling distance computation. -763. Cube Voyager Reference Guide 755 . Set link time to TIME if specified. 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. MODE=7. 3674. ONEWAY=T. 764. 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. Adjust link time using the prevailing value of TIMEFAC. 752 Calculation of line/link times You can adjust the time to lines use to traverse links with several LINE keywords and NODES subkeywords. 765. Add DELAY or DELAY_C to link time. Example LINE NAME="GMB1-24M".Public Transport Program Control statements 12 LINE keywords (continued) Keyword XYSPEED Subkeyword |R| Description Optional. DELAY and DELAY_C values.VAR for even number zones IF (I%2==0) LINKLOOP LW. You can only use LINKLOOP in the DATAPREP phase. then the program increases the NNTIME. no [LINKNO] subscript needed 756 Cube Voyager Reference Guide . but do not overlap LINKLOOP blocks with IF blocks.12 Public Transport Program Control statements 2.VAR=LW.. Adjust link times based on applicable keywords: NODES NNTIME NODES RT RUNTIME The program applies scaling to link travel time. RT. to reference the current link number.VAR*2 ENDLINKLOOP ENDIF . You may nest LINKLOOP blocks. and intersection delays exceeds the specified value. If you set PARAMETERS EXTENDRUNTIMES to true and the total time calculated from link times. You can use LINKNO. dwell times. Example Double LW. The program supplies all link arrays in a LINKLOOP block with the number-of-links dimension. or RUNTIME value to this total. ENDLINKLOOP Controls a loop for processing link records. delays. the default loop index. but retains their original settings. LINKLOOP . the LINKLOOP statement processes all link records with a loop increment of one.. The program does not scale dwell times and junction delays. By default. . If the result of the comparison is true. the program branches back to the statement following the LOOP statement.Public Transport Program Control statements 12 LOOP . You must specify a value. End. and other LOOP statements may alter the value of Var. the program goes to the statement following LOOP. The program does not protect the value of Var during the loop. You must specify a value. Incr Statement set ENDLOOP where: • Var is the required user-specified name of the loop-control variable. program. Processing of the ENDLOOP statement depends on the value of Incr: • If Incr is positive. Begin is the constant value to which the program initializes Var.. computation. and branches to the statement following the LOOP block if the comparison fails. otherwise the program goes to the statement following ENDLOOP. when the value of Var is less than or equal to End. ENDLOOP Initializes a variable. Incr is the constant the program adds to Var before processing the ENDLOOP statement. compares the variable to a constant. control is passed to the statement following ENDLOOP. End is the constant value that the program compares Var to when processing the ENDLOOP statement. but they may not overlap other LOOP blocks or IF blocks. LOOP blocks may be nested. LOOP Var = Begin. • • • Cube Voyager Reference Guide 757 . If it is false. 758 Cube Voyager Reference Guide . The program tests the ENDLOOP condition (without incrementing the variable value) when initializing the loop-control variable. You can include descriptive names in reports and graphics.2 . the program goes to the statement following LOOP otherwise the program goes to the statement following ENDLOOP.8. LOOP iter=1.4. 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. Citilabs recommends that you define the modes in use with the MODE statement. . ENDLOOP ENDLOOP MODE Defines the transit and nontransit modes that the public transport system uses.1. LOOP xyz=10. with the innermost loop executing twice for each value of variable xyz: 10. the program does not perform any statements within the LOOP block.-2 LOOP abc=1.2. Example 1 Executes the code within the LOOP block 10 times.12 Public Transport Program Control statements • If Incr is negative. ENDLOOP Example 2 A nested loop.10 . when the value of Var is greater than or equal to End. . Although not mandatory. If the test fails.6. You can also save nontransit legs in the file specified with the NTLEGO statement. and displaying. NT Specifies the format of nontransit legs in the Public Transport network. Valid values range from 1 to 999. Cube Voyager Reference Guide 759 . Optional. NUMBER must be the first keyword on the MODE control statement. The program saves nontransit legs with the public transport network when processing a NETO statement. MODE keywords Keyword NUMBER |I| Description Unique numeric identifier for a mode. NAME LONGNAME |S| |S| Optional. 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. You can use this format for reviewing and editing. reporting. You can feed the saved nontransit legs back to the modeling process when inputting the public transport network with a NETI statement. You can use the output for modeling. Use to supplement NAME.Public Transport Program Control statements 12 Input MODE statements in the public transport system data file. specified with SYSTEMI. Unique string identifier for a mode. You can feed these saved nontransit legs back to the modeling process with a NTLEGI statement. Second unique string identifier for a mode. of the nontransit leg. for each combination of A-node. Valid values are great than or equal to 0. Length. Possible values: • A — Add the input leg.12 Public Transport Program Control statements NT keywords Keyword LEG |S| Description Nodes defining a nontransit leg. R — Replace an existing leg in the table with the input one. B-node. NOTE: LEG must be the first keyword in NT control statements. to traverse the nontransit leg. The table stores only one leg. Useful for eliminating nontransit legs from the network. 760 Cube Voyager Reference Guide . This crowd-modeling data accounts for constraints that bottlenecks impose in the public transport network. Valid values are great than or equal to 0. Valid values are great than or equal to 0. ACTION |S| Optional. generated or input. String that designates how the program merges input nontransit legs with generated nontransit legs. Directional flow-metered passenger volume (total number of flow-metered passengers that the loading models assigned to the nontransit leg).01. Specify the starting node number followed by the ending node number. and nontransit mode. 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. separated by a hyphen. The program merges the legs from each GENERATE statement. Optional. in user-specified units. if it is shorter than a matching one in the table. or if it does not already exist in the table. No action is taken if leg is not already in the table. in user-specified units. the one with the least cost. if it exists. Only one leg can connect any two nodes. The Public Transport program maintains a single table of nontransit legs. only if it is shorter than the existing one.01. • • • Default value is A. into this table. D — Delete the leg from the table. COST DIST FMVOL |R| |R| |R| Cost. that the transit vehicle traverses the nontransit leg. Optional. Valid values are great than or equal to 0. Valid values are great than or equal to 0. Example A selection of nontransit legs generated by the Public Transport program. Speed. Enter the same value for FMVOLT for leg A-B and leg B-A. Directional passenger volume (number of passengers that the loading models assign to the nontransit leg).Public Transport Program Control statements 12 NT keywords (continued) Keyword FMVOLT |R| Description Optional. Flag indicating whether nontransit leg is a one-way leg. Enter the same value for VOLT for leg A-B and leg B-A. Optional. Valid values range from 1 to 999. List of nodes between the start and end nodes in a nontransit leg.92 DIST=39.01. VOLT |R| Optional. Valid values are great than or equal to 0.40 DIST=53. Nondirectional passenger volume (total number of passengers that the loading models assign to the nontransit leg in both the forward and reverse directions). This crowd-model data accounts for constraints that bottlenecks impose on the public transport network. Valid values are great than or equal to 0. MODE ONEWAY |I| |?| Mode of the nontransit leg. LEG defines the start and end nodes. NT LEG=6-800 MODE=5 TIME=1.00 ONEWAY=T XN=792 Cube Voyager Reference Guide 761 . XN |S| 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). VOL |R| Optional. Possible values: • • SPEED |R| T — Nontransit leg is a one-way leg F — Nontransit leg is a two-way leg Default is T.00 ONEWAY=T NT LEG=6-2054 MODE=5 TIME=5. in user-specified units per hour. 35 DIST=52. NAME LONGNAME |S| |S| Optional. specified with SYSTEMI.52 DIST=41. The OPERATOR control statement associates descriptive names with operators.00 ONEWAY=T OPERATOR Defines the operators in the public transport system. Supplements NAME. Although not mandatory. All lines belong to operators and refer to them by their numeric identifiers. Must be the first keyword coded with the OPERATOR control statement.00 ONEWAY=T LEG=8-814 MODE=5 TIME=0.12 Public Transport Program Control statements NT NT NT NT NT NT LEG=6-2056 MODE=5 TIME=5. OPERATOR keywords Keyword NUMBER |I| Description Unique number that identifies a transit operator.00 ONEWAY=T LEG=7-806 MODE=5 TIME=8.00 ONEWAY=T XN=800 LEG=7-803 MODE=5 TIME=1.88 DIST=12.16 DIST=29. Unique string that identifies a transit operator.92 DIST=43. Unique secondary string that identifies a transit operator. Optional. Input OPERATOR statements in the public transport system data file. 762 Cube Voyager Reference Guide .35 DIST=29. Valid values range from 1 to 999.00 ONEWAY=T LEG=9-812 MODE=5 TIME=1. Citilabs recommends that you define the operators in use with the OPERATOR statement.00 ONEWAY=T XN=2058 LEG=7-2058 MODE=5 TIME=4. You can include these names in reports and graphics. • Default value is F. Flag that specifies whether to print messages for excessive calculated travel times. • F — When two routes share a common sequence of stopping nodes. PARAMETERS keywords Keyword AONMETHOD |IK| Description Optional. Possible values: • • • CHANGEATLASTSTOP |?K| 0 — Use latest available algorithm 3 — Use algorithm from version 3. Citilabs recommends this setting only when required for consistency with earlier runs. Possible values: • T — Method from version 3. Default value is F. DWELL. Cube Voyager Reference Guide 763 . DELAY. DWELL_C. Flag that indicates how transfers between routes occur.2 and earlier releases: When two routes share a common sequence of stopping nodes.Public Transport Program Control statements 12 PARAMETERS Specifies global parameters for the Public Transport run. EXTENDREPORT |?| Optional. NODES NNTIME.2 4 — Use algorithm from version 4. using data in keywords such as TRANTIME. Optional. NNTIME. When calculated travel times exceed the travel time limits imposed by the RUNTIME. F — Program does not print messages for excessive calculated travel times. you might edit the LINE statement or extend the line’s run time with the EXTENDRUNTIMES keyword. transfers may occur at any of the nodes. Possible values: • T — Program prints messages when a line’s calculated travel time exceeds the values specified by RUNTIME. or NODES RT. The program determines run times along transit lines from junction delays and link travel time. DELAY_C. Integer specifying all-or-nothing path-building algorithm to use.0 Default value is 0. or RT keywords and subkeywords in the LINE control statement. transfers occur at the last stopping node in the sequence. The program calculates run times along transit lines from junction delays and link travel time. FARE |?K| Optional. or RT keywords and subkeywords set control values for travel time. Input descriptions of fare systems with FILEI FAREI. The LINE control statement and its RUNTIME. Flag indicating whether fares are included in generalized cost during the route-evaluation process. then link travel times have already been calculated and cannot be amended. 764 Cube Voyager Reference Guide . the program scales calculated values to match control values.12 Public Transport Program Control statements PARAMETERS keywords (continued) Keyword EXTENDRUNTIMES |?| Description Optional. Possible values: • T — When calculated travel times along a line exceed control values. input descriptions of fare matrices with FILEI FAREMATI. DWELL. If the program reads line data from a network file. FARE does not impact the selection of fare skims chosen with the skimming functions FAREA and FAREP. Flag that indicates whether the program automatically extends travel time along a line when it exceeds control values. If required. 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. F — Program does not include fares as part of the generalized cost during the route-evaluation process. DELAY_C. • Default value is F. NNTIME. 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. • Default value is F. using data in keywords such as TRANTIME. You do not need to provide fare data for the DATAPREP phase. Possible values: • T — Program includes fares as part of the generalized cost during the route-evaluation process. Only set EXTENDRUNTIMES to T when reading LINEI files. DELAY. DWELL_C. Valid values range from 1 to 999. HDWAYPERIOD |IK| Optional. Default value is 999. MEUSESNT |?| You can override this default setting with keywords in the FILEO SCREENLINEO statement. If not specified. You can code up to five headways for each line. Maximum index for work matrices (MWs). N — Program considers only link use of transit modes when creating intercept data. you do not specify this keyword and override default value. MAPSCALE |RK| Optional. Message 770 describes missing or inconsistent data in the FILEI FAREI. If you do not specify HDWAYPERIOD. Factor indicating coordinate units divided by distance unite. the program estimates a value from the link data. Optional. Possible values: • • • 0 — Treat as message 1 — Treat as warning 2 — Treat as error Default value is 2. Valid values range from 1 to 5. the default is 1 (HEADWAY[1]).Public Transport Program Control statements 12 PARAMETERS keywords (continued) Keyword FAREMSG |IK| Description Optional. The program uses this value in conjunction with LINE XYSPEED. Default value is Y. MAXMW |IK| Optional. Cube Voyager Reference Guide 765 . Integer indicating how the program treats message 770. Flag indicating whether program considers link use of nontransit modes. Integer indicating which HEADWAY and HEADWAY_R fields to use from the LINE control statement. The program only validates this data if fares are included in the route-evaluation or skimming processes. Possible values: • • Y — Program considers link use of all modes when creating intercept data. Normally. if more than one such field is coded. the program terminates. Default value is 10. if necessary. Generally. Number of messages the program reports for loaded zone pairs that have trips between them but no valid routes. Valid values are greater than or equal to 0.12 Public Transport Program Control statements PARAMETERS keywords (continued) Keyword NOROUTEERRS |IK| Description Optional. This setting allows the program to read an entire input file without termination due to data errors. This keyword permits you to accommodate unconnected zones. NOROUTEMSGS applies across all user classes. all zones in a public transport network are connected. 766 Cube Voyager Reference Guide . Possible values: • Y — Downgrade data errors to warnings when reading transit line data. The program terminates when the number of such zone pairs exceeds NOROUTEERRS. Default value is 5. Default value is N. Flag indicating whether to treat data errors when reading transit line data as warning. SKIPBADLINES |?| Optional. leading to program termination. When the number of zone pairs with trips but without valid routes exceeds this value. NOROUTEMSGS |IK| Optional. Valid values are greater than or equal to 0. You may override this global setting with the FILEI LINEI control statement. NOROUTEERRS applies to all user classes. Number of zone pairs that the program can process with trips between them but no valid routes. • N — Treat data errors as errors. Expression involving one or more link variables. the results are unpredictable. Examples: TRANTIME TRANTIME computed TRANTIME = LI.name = LW. you might define: TRANTIME[3] = (1.DISTANCE*60/LI. You can refine this time with the LINE control statement and the NODES keyword.SPEED) The settings in these examples apply to all modes. if mode 3 uses a different formula.name) or link work arrays (LW.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. Denote input-network link variables as LI.TRANTIME. For example. Include only input-network link variables (LI.DISTANCE*60/LI. Name of a link work array that you computed in the LINKREAD phase. LW. Denote these arrays as LW. You must enclose expressions in parentheses.name.TRANTIME was in the LINKREAD phase.name).SPEED) Cube Voyager Reference Guide 767 .14*LI. = (LI. You might specify: • Name of an input-network link-based variable that contains link transit times.name. • • NOTE: If you set TRANTIME to any other variables. You can override these settings with a mode-specific expressions. May vary per mode. MAT PARAMETERS TRIPSIJ[1] = MI.3-5. FILEI MATI[1]=TRIPS. For example: USERCLASSES=1. Numeric expression used to compute trips loaded for a particular user class.1. The index is defined by USERCLASSES. unless using the SELECTIJ phase.MAT PARAMETERS TRIPSIJ[1] = MI. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. If USERCLASSES=1.1. V4ROUTEFORMAT |?K| Optional. You must provide a value for all user classes. Delimit each number or pair with a comma. all ten user classes are available in the Public Transport network.12 Public Transport Program Control statements PARAMETERS keywords (continued) Keyword TRIPSIJ |NVu|2 Description Optional.1 Loads the cells of an input trip matrix.1.3 Loads 70% of the input trip matrix to user class 1 and 30% to user class 2.1 * 0.1 * 0. You might assign an input or generated trip matrix. you need not code the index. see “More on user classes” on page 769. List of modeled user classes. TRIPSIJ applies to all I-J pairs. TRIPSIJ[2] = MI. User classes need not be monotonic or sequential. Examples FILEI MATI[1]=TRIPS. Flag indicating formatting of route file. By default. USERCLASSES |IK| Optional. Possible values: • • T — Program writes older. 768 Cube Voyager Reference Guide . version 4-compatible route file format with FILEO ROUTEO F — Program writes current route file format Default value is F. For more information. the program can compute trips for individual or sets of I-J pairs in the SELECTIJ phase.7 Valid user classes range from 1 to 10.7. With a value of 10. For example. with a value of 1. which you model with user-class-specific cost functions. and loading processes. and links) produced by the Network program Cube Voyager Reference Guide 769 . the program writes a message for every 10 zones. Specify a larger value to reduce run times.Public Transport Program Control statements 12 PARAMETERS keywords (continued) Keyword ZONEMSG |IK| Description Optional.exe. each user class might have different behavior patterns. The program writes to the console when initiated through runtpp. u represent number of user classes Example Parameters for the data-preparation.1 PARAMETERS TRIPSIJ[2] =MI. Valid values are greater than or equal to zero. t represents number of transit modes 2. you can use user classes to stratify demand. the program writes no zonal messages. With a value of 0.1. such as by purpose or fare type. route-evaluation. Default value is 1. The Public Transport network contains several components that are common to all user classes: • Basic network infrastructure (such as zones. the program writes a message for every zone. PARAMETERS USERCLASSES=1. Value corresponds to number of zones.2 PARAMETERS TRIPSIJ[1] =MI. Frequency with which the program writes zonal timing messages to the run monitor or console. Similarly.2 NOPATHMSGS=10 NOPATHERRS=25 More on user classes You can use user classes for multiple purposes. other than TRIPSIJ. Note most PARAMETERS keywords. Program writes to the run monitor when initiated through Application Manager or voyager. are trigger keywords and need not be preceded by the control statement name. For example. 1.1.exe. nodes/stops. output with MATO. However. Skim data. FACTORI[4]=FACTSUC3. The program outputs user-class-specific enumerated routes files (ROUTEO). and line data) and that contains the factors for all user classes. input with NTLEGI. specifies level-of-service data that can vary by user class.RTE. suppose you want to define input files for user classes 1. you can point those user classes to the same FACTORI file. User class 3 and 4 use the same factors.RTE.12 Public Transport Program Control statements • • • • System data input with SYSTEMI Demand data. You define input and output files for user classes with the FILEI and FILEO control statements.RTE The Public Transport program outputs a public transport network that contains the four components that are common to all user classes (network infrastructure. FACTORI[3]=FACTSUC3. input with LINEI Other data and processes vary by user class: • • • Factor data. Routes are enumerated and evaluated by user class. nontransit legs. if there are no differences between the behavior for some user classes. system data. You must specify FACTORI and MATI files by user class. input with FACTORI. You might create the following control statements: FILEI FACTORI[1]= FACTSUC1.FAC FILEI ROUTEI[1]=ENROUTEUC1. ROUTEI[3]=ENROUTEUC3. and skims and select link analyses. 3. input with MATI Nontransit legs. Routes are input with ROUTEI.FAC. generated with the GENERATE control statement. and output with ROUTEO. ROUTEI[4]=ENROUTEUC4.FAC. For example. 770 Cube Voyager Reference Guide . matrices (MATO). or both Line data. specifies cost functions that can vary by user class. and 4. PRINTROW Specifies format for reporting work matrices to the main print file. a file. PRINTROW MW=2 FORM 10. Example Print two skim matrices. NODES |IPD| Cube Voyager Reference Guide 771 . Defines a timing point where timing data is read as sub-keywords. Specifies what day types the run operates on. No default values. ten columns per line. or both. See “PRINT” on page 66 for details about the standard Cube Voyager control statement. Reads a list of single values and/or ranges. so list is required.2 TITLE='COMPCOST' PRINTROW MW=2 FORM 10. The length of the printed line is determined by the formatting of each listed item. See “PRINTROW” on page 73 for details about the standard Cube Voyager control statement.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. The program prints one line for each PRINT statement.Public Transport Program Control statements 12 PRINT Specifies the format for data items output in a single line to the standard printed output. F — Do not produce summary report. Valid values range from 0 to 5. Flag indicating whether to generate summary report of line attributes. REPORT keywords Keyword LINES Subkeyword |?| Description Optional. Number of decimal places to include in the “Pass” and “PassDist” columns in the summary report produced by LINES. • Default value is F.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. showing attributes like number of stops. See “Transit line summary” on page 793 for an example of this report. route time. which shows passenger transfers between modes and operators. Possible values: • T — Produce summary report of line attributes. when running the loading process. and distance. Summary includes passenger distance and hours if line loads are available. More than one LINES report may be selected in a run. Default is 2. LINES DEC |I| Optional. 772 Cube Voyager Reference Guide . • Default value is F.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. F — Include all nodes in report. F — Do not report passenger loadings. • Default value is F. Valid values range from 0 to 5. report does not sort lines. Cube Voyager Reference Guide 773 . You can produce reports for individual user classes with subkeyword USERCLASSES. Flag indicating whether to report passenger 8loadings (boardings. See “Transit line loadings” on page 794 for an example of this report. Default is 2. ignore nonstopping nodes and nodes that have no passenger activity. By default. Optional. Possible values: • • • NAME MODE OPERATOR By default. LINEVOLS DEC |I| Optional. program generates single report summed over all user classes. Flag indicating whether to include only stop nodes with flows. alightings. LINEVOLS SKIP0 |?| Optional. but displays in order of input. Possible values: • T — Produce passenger loadings report only for stop nodes with nonzero flows. and flows) by line. LINEVOLS |?| Optional. Possible values: • T — Report passenger loadings by line. String specifying field that the summary report uses to sort lines. Number of decimal places in passenger loading fields. List of user classes that require individual passenger loadings reports. Possible values: • • LINEVOLS USERCLASSES |IV10| T — Produce passenger loadings report for stop nodes only.12 Public Transport Program Control statements REPORT keywords (continued) Keyword LINEVOLS Subkeyword STOPSONLY |?| Description Optional. Valid values range from 1 to 10. Delimit each number or pair with a comma. F — Include all nodes in report. Flag indicating whether to include stop nodes only. do not include nonstopping nodes. A statement’s selections apply to the reports generated by that statement. 774 Cube Voyager Reference Guide . For examples. Default value is F. summed over all user classes. By default. You may specify up to ten user classes. The statement outputs reports to the file specified with REPORTO. none are included. These basic reports help you understand the network-simplification and route-enumeration processes. REREPORT Produces reports showing the input simplified public transport network and allied data structures that the route enumeration process uses. Optional. and the program produces a single report. see “Network simplification” on page 808. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. A run can have multiple REREPORT statements. Default value is F. REREPORT keywords Keyword ACCESSLEGS |?| Description Optional. • EGRESSLEGS |?| F — Do not produce this report. while LINE=MUNI-?? selects lines that have names beginning with MUNI. Specify included nodes with N. Flag indicating whether to produce an egress-leg report. • LINE |S| F — Do not produce this report.” such as MUNICENTRAL and MUNINORTH. Flag indicating whether to produce an access-leg report. The program compares nonmasked portions of a line’s name when selecting lines. Cube Voyager Reference Guide 775 . For example. Optional. Default value is all lines. GENERATE control statements generate or input access legs. The list can contain up to 1000 comma-separated items. You can mask names with “*” and “?” to specify multiple lines. TRNLEGS3. GENERATE control statements produce or input egress legs. Egress legs connect zones to serviced alighting nodes.and any two additional characters. such as MUNI-01 and MUNI-02. Possible choices: • T — Produce a report showing access legs in the public transport network.Public Transport Program Control statements 12 None of the REREPORT keywords are “trigger” keys. List of lines included in the reports produced by LINES. Optional. and TRNLEGS4. LINE=MUNI* selects all lines that have names beginning with “MUNI. Possible values: • T — Produce a report showing egress legs in the public transport network. Default value is F. you must code all on a REREPORT statement. “*” applies to any number of characters. while “?” applies to single characters. Specify included nodes with N. Access legs connect zones to serviced boarding nodes. Default value is F. • F — Do not produce this report. Flag indicating whether to produce a line-ordered lineto-zone nontransit-leg report. Optional. Possible values: • T — Produce a report showing the line-to-line transfer legs. You might use this report to improve performance of the route-enumeration process. Default value is F. Possible values: • T — Produce a report showing transit-line attributes and the nodes the lines traverse. You might use this report to improve performance of the route-enumeration process. Flag indicating whether to produce a line-to-line transfer-leg report. Specify included lines with LINE. in line order. GENERATE control statements generate or input nontransit transfer legs.12 Public Transport Program Control statements REREPORT keywords (continued) Keyword LINES |?| Description Optional. in line order. • LINEZONLEG1 |?| F — Do not produce this report. produced with XFERLEGS. Flag indicating whether to produce a line-attribute report. 776 Cube Voyager Reference Guide . Possible values: • T — Produce a report showing line-to-zone nontransit legs. This report expands upon the direct-andnontransit-transfer-leg report. Default value is F. Optional. • LINELINELEG |?| F — Do not produce this report. This report expands on the access-leg and egress-leg reports produced with ACCESSLEGS and EGRESSLEGS. 3000-4500.Public Transport Program Control statements 12 REREPORT keywords (continued) Keyword LINEZONLEG2 |?| Description Optional. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. Used to specify start and end of transit leg (e. LINEZONLEG2. Delimit each number or pair with a comma. Default value is F. F — Do not produce this report. and XFERLEGS. 123-789 would report transit legs from 123 to 456 then 123 to 789). For example. Flag indicating whether to produce a stop-node report. Specify included nodes with N. List of nodes included in the reports produced by ACCESSLEGS. Flag indicating whether to produce a zone-ordered line-to-zone nontransit-leg report. 123-456. This report expands on the access-leg and egress-leg reports produced with ACCESSLEGS and EGRESSLEGS. The list can contain up to 1000 comma-separated items. then the selected reports will include nodes 1000 through 2000 and nodes 3000 through 4500. if REREPORT ACCESSLEGS=T. EGRESSLEGS. Default is to include all nodes. Possible values: • T — Produce a report showing line-to-zone nontransit legs. EGRESSLEGS=T. or egress. N=1000-2000. in zone order. Possible values: • T — Produce a report showing all nodes in the public transport network where transit lines stop for transfer. • TLEGS |IP| Default value is F. TRNLEGS2. access. • N |IV1000| F — Do no produce this report. STOPNODES |?| Optional. Optional. TRNLEGS1.g. You might use this report to improve performance of the route-enumeration process. Cube Voyager Reference Guide 777 . Specify included nodes with N. Flag indicating whether to produce a node-ordered transit-leg report that shows perceived costs (including BRDPEN) during route enumeration. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. Flag indicating whether to produce a node-ordered transit-leg-bundle report that shows the perceived costs (including BRDPEN) during route enumeration for all legs and that identifies a bundle’s fastest line and shows that leg’s estimated waiting time. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. sorted by node. Possible values: • T — Produce a report showing all transit legs in the public transport network. Possible values: • T — Produce a report showing transit-leg bundles in the public transport network. 778 Cube Voyager Reference Guide . Specify included nodes with N. The report calculates in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] The perceived time for the bundle’s top leg also includes the estimated wait time for the bundle.12 Public Transport Program Control statements REREPORT keywords (continued) Keyword TRNLEGS1 |?| Description Optional. • F — Do not produce this report. Optional. Default value is F. Default value is F. The report calculates perceived in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] • TRNLEGS2 |?| F — Do not produce this report. sorted by node. Set to true to obtain report of all lines/runs departing from the specified node. List of user classes included in the reports produced by the REREPORT statement. The report calculates perceived in-vehicle time as: Actual in-vehicle cost * RUNFACTOR[mode] NOTE: The report TRNLEGS3 produces includes BRDPEN. Optional. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. Flag indicating whether to produce a line-ordered transit-leg report that shows perceived costs (including BRDPEN) during route enumeration. By default. Possible values: • T — Produce a report showing transit legs and attributes. Set to true to obtain report of all lines/runs between a pair of nodes. reports produced for each defined user class. You define valid user classes with USERCLASSES.Public Transport Program Control statements 12 REREPORT keywords (continued) Keyword TRNLEGS3 |?| Description Optional. Specify included lines with LINE. 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. Optional. • TTDEPS |?| F — Do not produce this report. sorted by line. sorted by line. TTLEGS |?| USERCLASS |IPa| Cube Voyager Reference Guide 779 . This report shows actual and perceived in-vehicle time that the route-evaluation process uses. Can use sub-keyword TLEGS to specify start and end node of transit leg. Default value is F. The report calculates perceived in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] • TRNLEGS4 |?| F — Do not produce this report. Specify included lines with LINE. Default value is F. Can use sub-keyword N= to specify required nodes. The vehicle definitions provide a template that you can associate with one or more transit lines. TRNLEGS2=T. 780 Cube Voyager Reference Guide . LINES=T. Example In the REREPORT statement below.12 Public Transport Program Control statements REREPORT keywords (continued) Keyword XFERLEGS |?| Description Optional. or hovercraft. N=250-450. such as a bus. EGRESSLEGS=T. and line-based reports apply to lines with line names beginning with MUNI. GENERATE control statements generate or input nontransit transfer legs. TRNLEGS1=T. Node-based reports only apply to nodes 250-450. LINEZONLEG1=T. 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. You can amend vehicle attributes on a line-by-line basis when needed. USERCLASS=1 VEHICLETYPE Defines the main vehicle types used by the transit lines operating public transit services. LINEZONLEG2=T. TRNLEGS3=T. //The REREPORT control statement name must be coded at the beginning of the statement REREPORT. Default value is F. LINE='MUNI*'. TRNLEGS4=T. tram. ACCESSLEGS=T. ferry. train. XFERLEGS=T. A vehicle can be any form of transport that provides public transit service over fixed routes. all reports are for user class 1. • F — Do not produce this report. STOPNODES=T. By default.0. Must be greater than or equal to the value of SEATCAP. you may specify the vehicle type in the LINE statement.0 to 100. specified with SYSTEMI. Cube Voyager Reference Guide 781 .000. NOTE: Number must be the first keyword coded on the VEHICLETYPE control statement. Valid values range from 1 to 255. CROWDCURVE |IV10| Optional. Required for adjusting link travel time. Unique string that identifies the vehicle type. Optional. CRUSHCAP |I| Vehicle’s crush capacity (the sum of seated capacity and maximum standing capacity). Represents load factor at which passengers begin experiencing additional perceived travel time due to crowding. Second unique string that identifies the vehicle type (in addition to NAME). VEHICLETYPE keywords Keyword NUMBER |I| Description Unique numeric identifier for a vehicle type. model does not consider crowding and load factors. Valid values range from 1 to 20. LOADDISTFAC |R| Optional. Specify per user class. Required to adjust link travel time. The program includes no default vehicle types. vehicle has unlimited seating capacity. Required for adjustment to link travel time. LONGNAME NAME SEATCAP |S| |S| |I| Optional. Valid values range from 1 to 10. none is used. Percentage of seats occupied when standing first occurs. When transit lines operate with particular vehicle types. Crowd curve used to adjust link travel times for a particular user class. You must input VEHICLETYPE statements in the Public Transport system data file.Public Transport Program Control statements 12 You may define up to 255 vehicle types. Vehicle’s seated capacity. By default. Valid values range from 0. Valid values range from 1 to 255.000. Optional. By default. You may allocate two wait curves to each stop node with IWAITCURVE and XWAITCURVE. NOTE: Must be the first keyword coded in a WAITCRVDEF control statement. See “Generalized cost” on page 797 for a description of the wait-time calculation. You may define up to 255 wait curves. SEATCAP= 40. Unique string that identifies a wait curve. You must input WAITCRVDEF statements in the Public Transport system data file. CROWDCURVE=1 WAITCRVDEF Defines wait curves used to compute initial and transfer wait times at stop nodes based on the frequency of services. Optional. Use the mode-specific WAITFACTOR to weight the wait time. VEHICLETYPE NUMBER=1. Valid values range from 1 to 255. Second unique string the identifies the wait curve (in addition to NAME). 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. Use IWAITCURVE when the node is a trip’s first boarding point and use XWAITCURVE at transfer points. NAME LONGNAME |S| |S| Optional. specified with SYSTEMI.9. LOADDISTFAC=0. 782 Cube Voyager Reference Guide . NAME="Bus single deck". The program provides default wait curves for initial boarding and transfers at stop nodes where you do not assign wait curves.12 Public Transport Program Control statements Example Define vehicle type number 1 for a single-deck bus. CRUSHCAP=55. The X-axis shows headway and the Y-axis shows wait time. used at transfer points in the trip. Separate each pair with a comma.15. 12-6. you may assign two wait curves: IWAITCURVE. 40-15. WAITCRVDEF NUMBER=1.20 WAITCRVDEF NUMBER=2 LONGNAME="TransferWait" NAME="XferWait". 15-7.5.0.8. 4-2.Public Transport Program Control statements 12 WAITCRVDEF keywords (continued) Keyword CURVE |RKV10000| Description List of pairs of X-Y coordinates that define wait curve. used when the node is the trip’s first boarding point. CURVE=1-0. Example Defining wait curve number 1 for stops in the central business area.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. NAME="CENTRAL-AREA" CURVE= 1-0. 20-8.5. and XWAITCURVE. For example: WAITCRVDEF NUMBER=1 LONGNAME="InitialWait" NAME="InitWait". At each stop node. 27. 60-20 See “More on wait curves” on page 783 for information about default wait curves. 48.12.5. CURVE=1. 100-12. 160.5. Separate X and Y values in a pair by a comma or a dash. 16. Cube Voyager Reference Guide 783 . 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. Default wait curve for initial boarding For transit services with a frequency of 60 vehicles per hour or more. 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.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.5. Linear interpolation applies between coded points. Wait time (Y-axis) may not decrease as headway (X-axis) increases. causing the relationship between wait time and headway to break down. 784 Cube Voyager Reference Guide . The default wait curve for transfer points is half the headway of all services visiting the stop. 0.Public Transport Program Control statements 12 • The curve runs from the point (1. Cube Voyager Reference Guide 785 . • Only the route-evaluation process uses wait curves.5 minutes for headways less than one minute. Wait time is fixed at 0.5) to the first coded point. Extrapolation beyond the last coded point occurs at the same gradient as immediately below that point. You select reports using a variety of control statements. 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. 786 Cube Voyager Reference Guide . See “Network simplification” on page 808 for examples of these reports. The program writes the reports to the main Cube Voyager print file unless otherwise stated.12 Public Transport Program Reports Reports This section describes the reports that the Public Transport program produces. 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.737 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 812 -> 9 lines PLB129A Cost=19. Subsequent lines for a route show pairs of transit and nontransit legs with the names of the transit lines running on the transit legs.896 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 806 -> 806 lines PLB127B PLB129A 806 -> 812 -> 9 lines PLB129A Cost=20.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. The first line for each route shows the access leg from the origin zone to the first boarding point.737 This example shows routes from zone 1 to zone 9. it is not the cost used for evaluating routes.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. The shown cost is used for selecting potential routes. Cube Voyager Reference Guide 787 . The program writes the report to the file specified by REPORTO.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. such as a probability of use less than a user-specified minimum. reports produced with TRACEI give a tabular output detailing component costs and summaries for each mode. Reports produced with REPORTI list routes taken. The program writes the report to the file specified by REPORTO. The Evaluated Routes report (“Evaluated routes” on page 788) lists routes that are actually used between the zones. Specify the required origin zones with the REPORTI or TRACEI subkeywords and the required destination zones with the REPORTJ or TRACEJ subkeywords. the report lists all routes used and the probability of taking each of them. Some offer more than one combination of services.12 Public Transport Program Reports The program will discard some of these routes for various reasons. The following topics show: • • Example produced with REPORTI Example produced with TRACEI 788 Cube Voyager Reference Guide . or alighting and reboarding the same line. 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. When using multirouting. the program finds five (potential) physical routes between zones 1 and 9. In this example. 249 Probability=0.00468973 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 812 -> 9 lines PLB129A Cost= 14.937 Probability=0.17571 1 -> 2052 2052 -> 2058 -> 806 lines ISL-UP 806 -> 812 -> 9 lines PLB129A Cost= 19.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.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.849 Probability=0.137 Probability=0.226877 1 -> 773 773 -> 771 -> 771 lines GMB1-36A 771 -> 799 -> 799 lines GMB1-39MB 799 -> 812 -> 9 lines PLB129A Cost= 15.249 Probability=0.896 Probability=0.096 Probability=0.0468973 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 812 -> 9 lines PLB129A Cost= 17.764 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.17571 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 806 -> 806 lines PLB127B 806 -> 812 -> 9 lines PLB129A Cost= 19.121547 Cube Voyager Reference Guide 789 . 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.25 Probability=0.667) 79(0.00 39.75 -> 4249 2 5.00 20.75 9. which the program computes from the routes’ common segments for the origin-destination pair as a whole. weighted by the probability of use.75 19.95 949(1. The first line for each route shows the access leg from the origin zone to the first boarding point.00 0.00 14. along with their probability of use.000) 23.00 9.35 107.016) 80(0.11 Probability=0.75 -> 4544 2 5.000) 19.00 3.00 14.00 7 17.76 790 Cube Voyager Reference Guide . The cost shown is the generalized cost of each route in minutes.02 19.50 98.00 0.50 1.00 3.50 30 30.00 4.00 81.85 8.00 47.5248 N: 1129 Mode WaitA TimeA Actual B/XPen Percvd Dist -> 5409 30 14.03 5.00 0.00 82.00 0.85 75.78 76(0.10 Mode TimeA Dist IWaitA XWaitA 2 20.05 Total Lines(weight) 0.00 41.333) -> 4201 31 1.11 -> 4209 7 7.47521 Total Lines(weight) 0.85 31 1.35 1.85 8.03 18.00 7.70 65.92 -> 757 30 16.00 7 34.66 1359(1.30 0.50 30 30.85 0.10 Mode TimeA Dist IWaitA XWaitA 2 11.53 0.00 14.00 9.30 48.00 7.00 11.00 91.92 0.00 0.27 5.00 14.25 -> 4209 7 7.27 76(0.00 38. This cost includes walk and invehicle times.85 31 3.00 33.00 91.13 23.00 18.00 18. but not wait time.70 4.00 30.00 0.30 0.03 79(0.031) 10.12 Public Transport Program Reports This report shows multiple routes from zone 1 to zone 9.50 34.00 0. Subsequent lines for the route show pairs of transit and nontransit legs with the names of the transit lines running on the transit legs. and boarding and transfer penalties.53 -> 757 30 16.00 0.50 17.953) -> 4538 31 3.00 0.30 40. distance. travel time. starting with the access leg. If you model fares. and ending with the egress leg. followed by alternating transit and nontransit legs. and wait times. Probability of taking the route. Trip fare. in monetary units. perceived boarding and transfer penalties. For each mode used.Public Transport Program Reports 12 This report shows two possible routes from 1129 to 757. The report contains a printed line for each leg. Mode information. For each route. For each leg. wait time. the report includes the trip fare. the report lists actual travel time. the report lists: • Leg-by-leg information. and transit lines used (along with probability). cumulative perceived cost. cumulative distance. the printed line shows destination node. • • • Cube Voyager Reference Guide 791 . cumulative actual total cost. mode. distance. --.--.---.---. Sample fare-matrices report FareMatrix(FMI.--.-1: 2 3 4 5 6 J: I=4 FareSystem 3 Tot= 20 -. specified with FILEI FAREMATI and used by fare systems defined by the FARESYSTEM control statement.---------.---.---------.FROMTO) for FareSystem 3 (FAREZONE-FROMTO): -----------------------------------------------------------J: I=1 FareSystem 3 Tot= 11 -.-1: 3 4 5 1 7 J: I=5 FareSystem 3 Tot= 23 -.--.1.---------.12 Public Transport Program Reports Fare matrices You can produce a report of fare matrices with the FAREMATI keyword in the REPORT control statement.---.--.---------.---------.-1: 4 5 6 7 1 792 Cube Voyager Reference Guide .-1: 1 1 2 3 4 J: I=2 FareSystem 3 Tot= 14 -.---. The report shows the contents of the input fare matrices.-1: 1 1 3 4 5 J: I=3 FareSystem 3 Tot= 20 -. The program writes the report to the main print file. 401. The program also produces a separate report for each user class.407.25 22. as the attributes are common to all user classes.89 GMB1-55B 7 11 12 4.07 8.05 7.14 11.91 GMB1-1B 7 11 5 7.07 10.90 5.05 568.79 22.802.96 1.72 0.403.232.80 GMB1-16MA 7 11 4 8.67 2.059.28 2.165.562.992.698.308.785.409.20 438.516.92 12.15 5.35 39.77 699. If the public transport network does not include line loadings.21 GMB1-24MA 7 11 10 6.84 477.36 15.16 906.383.27 7.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.87 4.630.02 1.29 26.765.14 ISL-DN 1 1 14 13. Cube Voyager Reference Guide 793 .16 2.14 2.21 GMB1-53B 7 11 14 7.77 21.25 GMB1-1A 7 11 5 6.16 15.96 This example shows transit lines sorted by mode.836.680.35 GMB1-29AA 7 11 3 2.49 915.01 GMB1-29AB 7 11 4 3.86 202.99 4.27 3.590.755.35 19.090.20 GMB1-24MB 7 11 10 5.28 16.790.56 46.808.716.67 1.41 1.892.456.46 6.51 8.01 13.24 3.13 GMB1-49MA 7 11 5 2. Because the public transport network includes line loadings.16 GMB1-2A 7 11 5 2.527.939.497.20 GMB1-39MA 7 11 6 8.684.20 9.44 GMB1-16MB 7 11 6 10.36 3.49 17.796.561.531.07 17.25 GMB1-55A 7 11 13 5.74 GMB1-39MB 7 11 7 8.08 19.14 568.756.89 306.009.007.13 GMB1-52B 7 11 6 8. This report shows data for all user classes.384.93 2.800.50 1.51 6.202.178.61 4.56 28.119.53 31.86 0.76 31.68 9.48 1.70 8.90 23.95 GMB1-49MB 7 11 2 1.772.26 4.39 22.15 370.712.901.694.18 10.824.192.713.00 GMB1-2B 7 11 5 3.998.79 22.436.507.60 13.42 1.67 1.295.329.05 16. the program only reports transit line attributes once.320.13 4.492.23 451.797.98 7.11 5.10 44.12 3.259.26 GMB1-52A 7 11 6 8.557.60 13.540. 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.99 4.52 2.38 465.81 1. this report includes passenger distance and passenger hours.646.96 4.82 22.97 20.460.56 16.805. 95 1.817.073. This report shows only stopping nodes with some passenger activity because STOPSONLY and SKIP0 are set to T. Sample of transit-line-loading report REPORT LINEVOLS UserClass=Total Name Mode Op N ON OFF VOL ------------------------------------------ISL-DN 1 1 ----------------------2072 7. alighting.62 29.651.06 1. 794 Cube Voyager Reference Guide . alighting.234.81 6.628.37 13.383.66 2066 3.68 25.73 2052 45.03 2062 7.132.78 1.072.72 4.883.876.073.75 577. and riding through the nodes of a transit line.031.135.423.35 23. the program would supplement reports showing all user classes with columns showing the flow-metered boarding.40 7.290.39 2068 20.42 17.526.30 8. This report shows data for all user classes.737.97 15. If the program performed crowd modeling with wait-time adjustments.30 2004 8.735.78 2056 1.108.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.75 22.34 2058 1.02 -- This example report shows the number of passengers boarding.692.526.20 -7.02 2001 -8.02 7.084. and through-ridership volumes.73 2054 5.47 29. You can request a separate report for each user class.20 2070 -874.893. 94 8 -.255.476.931.45 17.06 29.Public Transport Program Reports 12 Transfers between modes When performing loading.769.346.008.60 49.91 1.008.07 47. Sample of transfers-between-modes report REPORT XFERSUM=MODE UserClass=1 MODE 1 7 8 11 33 34 ---------------------------------------------------------------------1 ----.77 7 -.22 580.60 11 116.51 33 38.346.228.51 10.723.03 124.743.96 444.88 2.629.21.77 10.326.75 58.97 17. the program automatically produces two reports showing transfers between modes: • • A report showing transfers between all modes (that is.228. 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.731.60 5.930.91 1.40 39.131.931.255.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 -.60 5.189.472.58.796.739.01 MODE names: 1 = Train 7 = Bus 8 = Underground 11 = Light Rail 33 = Access/Egress 34 = Walk Xfer Cube Voyager Reference Guide 795 .476.75 11 -.459.88 2.94 131.769.03 8 17.398.92 63.01 3.419.58 7 19.98 126.26 116.669.97 17.629.189.930.459.06 29.92 63.35 --34 36.20 21.739.24 19.849.77 10.669.35.22 580.10. Lea Valley Services 11 = BR .459.94 131.51 10.58 11 19. the program automatically produces a report showing transfers between operators.92 63.669.Upminster Branches 19 = BR .930.12 Public Transport Program Reports Transfers between operators When performing loading. The program produces this report for each user class and for all classes combined.255.77 10.06 29.01 OPERATOR names: 1 = BR .Liverpool Street .60 5.22 580.Fenchurch Street 14 = BR .629.97 17.189.931.Via Stratford 796 Cube Voyager Reference Guide .228.03 14 17.91 1.769.476.Stratford . Sample of transfers-between-operators report REPORT XFERSUM=OPERATOR UserClass=1 OPERATOR 1 11 14 19 ---------------------------------------------------1 -.21.008.346.75 58.739.88 2.60 19 116. 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 . 798 Cube Voyager Reference Guide . boarding and transfer penalties. The route enumeration process. if used. without using any transit mode You can develop walk links outside the Public Transport program and input the links to the program. and fare. the cost might include wait time. Generalized cost is a linear function of its components. using minutes as the s working units. described in “Route enumeration cost calculation” on page 801. weighted by coefficients. as part of a transfer between services Between an origin and destination zone. 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.12 Public Transport Program Theory • Cost Fare The route-evaluation process considers each component separately. at the start and end of the trip Between stop nodes. Walk time (nontransit time) Walking may occur at the following points in a trip: • • • Between stop node and zone centroid. depending on the values of keywords in the FACTORS control statement. are input in monetary terms and converted into the corresponding time units. Fares. Subsequent sections provide details about individual components and their weighting factors. uses a slightly simpler estimation. or you can develop the walk links when developing the public transport network. A trip’s generalized cost automatically includes walk and in-vehicle time. For example. You can weight the wait times with the node-specific WAITFACTOR keyword. If you do not specify any wait curves. See “Default wait curves” on page 784 for a description of the default wait curves. passengers might experience additional wait time attributable to crowding. Similarly. You assign wait curves to nodes with IWAITCURVE and XWAITCURVE keywords in the FACTORS control statement. When the program performs crowd modeling with wait time adjustments. In-vehicle time In-vehicle time is the time passengers spend travelling in a public transport vehicle for each transit leg of a trip. You model these additional wait times with a node-specific WAITFACTOR keyword in the FACTORS control statement. Specifically. you can weight the link times with the RUNFACTOR keyword. a network bottleneck might occur (where demand exceeds capacity. If a trip has more than one leg.Public Transport Program Theory 12 A link’s walk time (nontransit time) is typically the actual travel time. To convert the times to perceived values (for inclusion in generalized costs). You define wait curves with the WAITCRVDEF control statement. the value is the total in-vehicle time for all legs. and some passengers cannot proceed forward within the modeled period). the program uses default wait curves. you may specify different wait curves for initial and subsequent boardings at each node. Cube Voyager Reference Guide 799 . a transit service might be so loaded that a passenger cannot board (and must wait for a later service). the program computes wait time from wait curves that you specify. To represent passengers’ ability to control wait time at the start of a trip but not at transfer points. Wait time The program uses the combined headway of available transit services to compute the wait time at any boarding point. The program uses default wait curves at nodes where you do not assign wait curves. For transfers between the same mode. You specify boarding penalties by mode with the BRDPEN keyword. the program also weights in-vehicle time with a crowding factor. 800 Cube Voyager Reference Guide . Boarding penalty Boarding penalty is a fixed penalty applied at each boarding (that is. You can ban changes between modes by setting a high transfer penalty. which represents the inconvenience of transferring between modes. there are no penalties by default. The transfer penalty applies in addition to the boarding penalty for the subsequent transit leg. and you may weight transfer penalties with the XFERFACTOR keyword. You may add constants to transfer penalties with the XFERCONST keyword. no penalty). 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 may specify separate penalties for each mode. such as 999. for that mode-to-mode combination. The default penalty for each mode is zero (that is. even if there is walking between the two modes. at the start of the trip) and at each interchange. You specify transfer penalties with the XFERPEN keyword. The program applies this penalty at transfer points. All mode-to-mode penalties default to zero—that is. The penalty is based on a combination of alighting and boarding modes. When performing crowd modeling with link travel-time adjustments.12 Public Transport Program Theory You can weight in-vehicle time with a transit-mode-specific value specified with the RUNFACTOR keyword. Transfer penalty Transfer penalty is the transit-mode-to-transit-mode interchange penalty. and specify the input file with the FILEI control statement and FAREI keyword. Fare models describe how the program computes the fare for part of a trip or for an entire trip. the process bundles together transit legs with the same boarding and alighting points. weighted by mode-specific factor specified with the RUNFACTOR (using the value of the bundle’s fastest transit line) Boarding penalty Wait time. You define fare models with the FARESYSTEM control statement. (The process disaggregates transit leg bundles for analysis. you can include fares in the routeevaluation and skimming processes. For example. 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 WAITFACTOR and subject to a range defined by REWAITMIN and REWAITMAX • • Cube Voyager Reference Guide 801 . 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.Public Transport Program Theory 12 Fare By defining fare models.) For this reason. Data compression techniques improve the performance of the route-enumeration process. and enumerates routes only for the cheapest leg in the bundle. You associate fare models with transit lines two ways: • • Directly with the LINE statement and FARESYSTEM keyword Through their mode or operator attribute. • Walk time. When false. the process computes these times across all modes in a transit leg bundle.12 Public Transport Program Theory The route-enumeration process uses a simple estimate of wait time for each leg bundle. The process sets the wait time to half this headway. For best-path models. Wait time is calculated using initial or transfer wait curves and WAITFACTOR (as in the route-evaluation process). and XFERPEN) when identifying discrete routes. 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. • 802 Cube Voyager Reference Guide . 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. • In-vehicle time is based on the average value for lines in the transit leg bundle. XFERFACTOR. Where necessary. 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. the process computes these times for individual modes (and the value for fastest mode subsequently used in enumeration). In this case: • Calculations of wait and in-vehicle time depend on the value of FREQBYMODE: When true (default value). 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. weighted by WAITFACTOR. the route-enumeration process uses transfer penalties (based on XFERCONST. The process computes the headway for each bundle’s boarding node from the sum of the frequencies of the bundle’s legs. These other legs would also be eliminated. route evaluation. However. For both modeling methods. the program finds attractive or reasonable routes. in three steps: network simplification. and ignores transfer penalties except when modeling best paths. Modeling approach This section discusses the algorithms that the Public Transport program uses. The program supports two distinct modeling methods: multirouting and best-path. Using fares and transfer penalties with leg bundles during route enumeration could eliminate valid routes. route enumeration. (that is. 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 . 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. consider a banned transfer between transit modes 3 and 5. You can restrict modeling to consider just those routes that use a particular transit mode at some stage in the trip. suppose these legs are the top legs in bundles that contain legs of other modes. the route-evaluation process disaggregates transit-leg bundles by mode to apply transfer penalties. Instead. For example. routes that have some probability of use).Public Transport Program Theory 12 The route-enumeration process does not consider fares. The route-enumeration process adds wait time to the time of each bundle’s top leg to obtain a transit-leg cost. Routes transferring from a mode-3 leg to a mode-5 leg would be eliminated. suppose travelers waiting at node N have a choice between two routes to reach the trip’s destination. Taking these values as components of the generalized cost (without need for further weighting). There are a total of five services per hour. Assuming equal spacing of departures. For example. The Public Transport program includes two distinct methods: • • Multirouting — Evaluate multiple routes and calculate the probabilities of using each one. that is. At the origin and on completion of a transit leg. which runs every 20 minutes and takes 15 minutes to reach the destination after boarding. the combined headway is 12 minutes and average wait is 6 minutes. The second route uses line M. When on a transit line. Assuming route usage proportional to service frequency. travelers are prepared to board whichever bus comes first. you can compute an expected travel time from the stop to the destination.4 minutes. passengers must decide where to board the next transit leg. A number of possible methods. In a best-path model. 17 or 21. The cost to the destination is the wait time plus travel time. At a stop. the average time to destination is 19.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. travelers choose between the two routes and then wait for a service on the chosen transit line (ignoring any service on the other line). The first route uses line L. Either line offers an efficient effective route towards the required destination. Best-path — Identify a single “best path” route for an origindestination pair. which runs every 30 minutes and takes 11 minutes to reach the destination. passengers must choose between the transit lines that enable progress toward the destination. passengers might need to decide which stop to alight at (in order to transfer or walk to their destination). are possible at each decision point. In a multirouting model. Travelers assess attributes of each route: L 804 Cube Voyager Reference Guide . either 11+6 or 15+6. or modeling philosophies. The appropriate method might depend on externally imposed requirements or practices (for example. travelers using the best-path method would select transit line L. Network simplification To improve performance and to minimize memory and storage requirements. Model developers must decide between the two methods. with an average trip cost of 25 minutes. Many modelers prefer the multirouting method in cities with extensive. The process follows three principles: • • The trip should move progressively from the origin to the destination. Route enumeration For multirouting modeling. direct trips or trips that involve few transfers. Therefore.Public Transport Program Theory 12 has an average wait of 10 minutes and travel time of 15 minutes. Travelers prefer simpler trips. that is. the route-enumeration process finds all potentially attractive routes and enumerates them. for a total cost of 25 minutes. guidelines from government departments) or a choice regarding the suitability of each method. well-developed public transport systems. Cube Voyager Reference Guide 805 . M has an average wait of 15 and travel time of 11. for a total of 26 minutes. 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. 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. Next. alight from a service. the process establishes connectivity between transit lines. For best-path modeling. and enumerates any route which potentially could be the best route. The route-enumeration process allows for possible transfer-penalty values. For example. The program uses conventional algorithms to forecast these individual choices. Route evaluation For multirouting models. or walk elsewhere to board another service. the process identifies the route attributes—basic cost and number of transfers—and compares them. First. selecting reasonable routes for evaluation. the program uses information about the trip sequence to preclude alighting and reboarding the same service.12 Public Transport Program Theory • Travelers are unwilling to walk very long distances. This step is analogous to travelers rejecting routes that are very long relative to more direct alternatives. The route-enumeration process uses the same cost components as the route-evaluation process. the route-enumeration process identifies possible routes for the best single path between an origin and a destination. 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 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. 806 Cube Voyager Reference Guide . See “Route-enumeration process” on page 820 for a detailed description of this process. The route-enumeration process uses these principles to identify reasonable routes. The process limits routes by choosing simpler trips and trips with shorter walking distances during line-to-line transfers. with the exception of transfer penalties. When using multiroute paths.Public Transport Program Theory 12 For best-path models. The Public Transport program requires more computational time but produces more useful and better quality results. such packages cannot easily extract route-based information. Advantages of the Public Transport program for multirouting Some software packages trace paths from all zones to a particular zone or vice-versa. unlike traditional software packages. Therefore. the route-evaluation process identifies the best path using a similar evaluation method. The enumerated routes may vary widely in characteristics. such as station-to-station movements. matrices of trips using selected links or transit lines. you need not use biases. how the path reached the node or where the path came from). With the Public Transport program. perhaps having different transfer points. or mode-to-mode and operator-to-operator transfers. Cube Voyager Reference Guide 807 . However. 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. you can specify a “must-use-mode”—a mode that must be used during at least one leg of a public transport route in order for the Public Transport program’s route-enumeration process to select that route. Earlier software packages used biases to attract travelers toward one mode and away from other modes. and using different modes. Sometimes you might want routes to use a particular mode. Such paths do not retain the history of a trip at a node (that is. biasing could lead to modeling distortions affecting route costs or identification of the best route. followed by a the route-evaluation process to evaluate the routes. the Public Transport program operates at the zone-pair level rather than at the zonal level. and assigns all demand to that route. The Public Transport program finds discrete multiple routes between pairs of zones. Instead. DELACCESSMODE. the Public Transport program simplifies the network for enumerating and storing routes. and DELEGRESSMODE factors to remove legs of particular modes from the network representation. which you can examine to gain an understanding of how multirouting works in the Public Transport program. To improve algorithm performance and minimize memory and temporary disk storage. Use the DELMODE. The program does not use specified legs at any stage in the modeling. and transfer choices Modeling combination of frequent and infrequent services Network simplification Public transport networks are often quite detailed and data intensive. 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 .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. The program stores the simplified network in intermediate data structures. egress. 39 8 0 -746 12. (A trip consists of an access leg.) Use the REREPORT control statement and LINES keyword to produce a line-attribute report.54 1.Public Transport Program Theory 12 Transit legs A transit leg is a trip segment. Travel on the transit line can be over one or more links in the public transport network.55 6 0 748 7. and one or more pairs of transit leg bundles and nontransit legs.92 7 4 -745 8.33 4.00 0.00 0 10 5 GMB1-1B DisLine Stop Node Time tance Node# Node# -------------------------------------727 0.15 5 3 -881 6.10 1. the last of which is the egress leg.16 9 0 747 19. Line-attribute report REPORT: LINES Int Fare #Line #Stop Line Line# DIR Mode OP HDWAY Type Nodes Nodes Name --------------------------------------------------20 (f) 7 11 5.08 10 5 Cube Voyager Reference Guide 809 .28 0.97 0.12 2 0 -947 0.00 1 1 -897 0.80 4 2 751 5.40 2.99 0.42 3 0 875 1.15 7.36 1. that uses a single transit line. from a boarding point to an alighting point. 05 15.” 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.35 875 748 5.99 0.61 16.10 1.05 5.99 4.11 8.56 4.56 0.00 0 10 5 GMB1-1B Top ON OFF Time Time DisLeg Node Node Actual REnum tance ---------------------------------------------727 875 1. see “Transit-leg bundles.15 727 748 7.80 727 751 5.10 10.54 1.61 5.11 1.16 * Top leg of a leg bundle.16 6.15 7.55 6. • 810 Cube Voyager Reference Guide . They may or may not traverse the same links of the underlying network.28 751 748 1.55 0.92 * 727 747 19.93 * 748 747 12.77 * 751 747 13.12 * 875 747 17.15 22. 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).16 20.54 8.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.08 875 751 3. 12 GMB1-2B 875 748 5.35 GMB1-2B 875 751 3.35 RES-903R * 875 748 5.03 5.35 PLB1-113A 875 751 3.32 5.32 5.03 6.30 GMB1-24MA * 875 778 17.11 7.35 GMB1-24MA 875 751 3.53 0.55 0.03 5. 757.06 PLB1-113A 875 757 5.11 5.37 20.85 1.55 3.83 GMB1-24MA 875 753 5. the report marks the top line (the fastest line or the first line.83 PLB129A 875 753 5.06 RES-903R * 875 765 6.06 GMB1-24MA 875 757 5.55 3.35 GMB1-1B 875 751 3. including three sets of leg bundles: from node 875 to nodes 753.32 6.55 0.97 GMB1-24MA * 875 751 3.30 1. 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.Public Transport Program Theory 12 The route-enumeration process treats transit-leg bundles as single entities.53 0.55 3.26 11.91 0.35 PLB129A 875 751 3.75 10.55 4. if all have equal Cube Voyager Reference Guide 811 .35 GMB1-24MA * 875 776 13.03 0. and 751.55 0.55 4.06 PLB129A 875 757 5.32 1.95 GMB1-24MA * 875 773 8.85 1.66 GMB1-24MA * 875 774 7. The program individually evaluates each leg within a transit-leg bundle when determining “attractive” routes for loading and skimming.32 6.26 0. When multiple lines connect node 875 to an alighting node.91 0.38 1.04 4. Use the REREPORT control statement and TRNLEGS2 keyword to produce a node-ordered transit-leg-bundle report.04 16.55 3. thus simplifying and reducing the data to examine and enumerate.83 RES-903R * 875 757 5.37 5.04 0.11 1.30 9.03 6.12 GMB1-1B This sample shows transit legs from node 875.83 PLB1-113A 875 753 5.75 1.26 2.36 1. The program can generate nontransit legs with the GENERATE control statement. or do both. or multiple physical links. The program derives leg attributes from link attributes. Boarding and transfer costs apply to both types of transfers—those occurring at a node and those between two nodes connected with a physical nontransit leg. one. (Do not confuse this waiting time with the wait time calculated during the route-evaluation process.12 Public Transport Program Theory time) with “*.” All legs in a bundle have the same actual in-vehicle time.) Nontransit legs Nontransit legs are minimum-cost segments. but the REnum time for the bundle’s top leg includes an estimate of the bundle’s waiting time. 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). Such nontransit legs do not have any associated cost. See “Generalized cost” on page 797. traversed by nonmechanized modes. which allows transfers between two lines visiting the same node. The program associates a cost with these nontransit legs. 812 Cube Voyager Reference Guide . The program automatically generates a third type of “notional” nontransit leg. input user-specified nontransit legs. 12 0.43 33 Sample nontransit-leg report: REREPORT EGRESSLEGS REPORT: EGRESS LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------703 19 0. Sample nontransit-leg report: REREPORT ACCESSLEGS REPORT: ACCESS LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------1 773 2.43 33 749 3 3.19 33 709 19 0.80 0.42 33 725 22 6.30 33 735 23 2.40 0.78 33 4 750 0.24 33 721 21 1.00 0.53 33 6 2056 5.11 33 6 796 1.Public Transport Program Theory 12 Use the REREPORT control statement and ACCESSLEGS.32 33 4 2004 7.92 0.36 1.32 0.70 0.23 33 705 19 0.92 0.25 33 1 2052 8.39 33 6 2054 5.70 33 714 20 1.18 33 2 778 1.96 0.36 33 1 3674 2.52 0. EGRESSLEGS.41 33 5 959 2.38 33 6 800 1.46 33 747 24 1.56 0.92 0.68 0. and XFERLEGS keywords to produce nontransit-leg reports.96 0.70 0.70 0.52 0.12 0.24 33 728 22 0.72 0.78 33 Cube Voyager Reference Guide 813 .22 33 716 20 1.40 0.64 2.31 33 4 875 1.36 33 730 22 0.06 33 3 749 3.52 0.80 0.64 0.20 33 734 22 0.76 0. 00 -1 838 2072 3.00 0.04 34 803 803 0. the program uses all connectors to ensure identification of the best route.00 -1 838 838 0.00 0.00 -1 830 2066 4. 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. because the program selects exactly one best route.27 34 813 813 0.00 0. For best-path models.00 0.00 0.00 -1 806 2058 4.00 0. For multirouting models. overlapping segments are not possible.00 -1 806 806 0.00 -1* 702 702 0.00 -1 800 800 0.00 0.00 0.00 0.00 0.00 -1 703 703 0.00 0. 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.00 0.00 -1 813 2060 4.00 0.16 34 823 2062 4.11 34 * -1 indicates a direct transfer. without any walking. Line-zone legs During network simplification.00 0.02 34 837 837 0.00 -1 800 2056 4.12 Public Transport Program Theory Sample nontransit-leg report: REREPORT XFERLEGS REPORT: TRANSFER LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------701 701 0. the program eliminates multiple access legs by applying the following rules: 814 Cube Voyager Reference Guide .00 0.00 0.11 34 830 830 0. the program expands access and egress nontransit legs—legs from zone to stop node and vice versa—into zone to line and line to zone legs. If the cost of the “first access + riding to the next” is less than the next access. 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. 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). (Between legs of equal cost. select the leg with the least generalized cost and discard the others. • • • Cube Voyager Reference Guide 815 . the leg connected to the transit line’s latest stop). (Between legs of equal cost. If the cost of the “first access + riding to the next” is more than the cost of the next access.Public Transport Program Theory 12 • Among a set of legs accessing consecutive stops (disregarding intermediate nonstopping nodes). Always retain the last egress leg (that is. • • • • For multirouting models.” discard the leg. If the cost of an egress leg is more than the cost of “riding to the next + next egress. discard the next access. Always retain the first access leg (that is. those boarding at the first access may only ride until the stop before the next access.) If SHORTESTWALK=F then selection is based on travel time from some upstream node on the line. select the downstream leg. select the upstream leg. Each access has a stop up to which those boarding can ride.) If SHORTESTWALK=F then selection is based on lowest travel time to some downstream point on the line (rather than shortest leg cost). select the leg with the least generalized cost and discard the others. the leg connected to the transit line’s earliest stop). either to the stop before the next valid access or to the end of the line. 12 Public Transport Program Theory • Each egress has a stop that specifies the beginning of a range of valid boarding stops. 816 Cube Voyager Reference Guide . Both sets of rules apply to circular lines. this may be the stop after the previous valid egress or the beginning of the line. 52 0.80 0.78 Access GMB1-2A 22 728 0.92 0.39 Access GMB1-49MA 800 6 1.32 Egress GMB1-2B 15 852 1.Access/ Line Node Node Time tance Egress Name --------------------------------------------6 800 1.88 0.12 Access GMB1-49MA 814 8 0.97 Egress GMB1-29AA 852 15 1.80 0.52 0.52 0.39 Egress GMB1-49MA 7 803 1.41 Egress GMB1-49MA 8 814 0.Public Transport Program Theory 12 Use the REREPORT control statement and LINEZONLEG1 LINEZONLEG2 keywords to produce line-to-zone nontransit-leg reports.33 Egress GMB1-29AB 16 855 1.52 0.52 1.12 0.92 0.12 0.52 1.52 0.78 Egress GMB1-2B 4 875 1.32 Access GMB1-2B 875 4 1.41 Access GMB1-49MA 803 7 1.33 Access GMB1-29AA 855 16 1.97 Access GMB1-29AB Cube Voyager Reference Guide 817 .88 0.52 0.12 Egress GMB1-49MB 3 749 3.36 Egress GMB1-2A 749 3 3. Sample line-ordered line-to-zone nontransit-leg report (REREPORT LINEZONLEG1) REPORT: LINE ZONE I (In Line Order) Origin Dest Dis.36 Access GMB1-2A 728 22 0. 56 0.12 0.25 Egress GMB1-24MA 773 1 2.25 Access GMB1-36B 1 2052 8.56 0.31 Access RES-91R Line-line legs During network simplification.31 Access PLB129B 4 750 0.12 0.70 0.25 Egress GMB1-36B 2052 1 8. 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. direct transfers at the same stop node.25 Egress GMB1-24MB 773 1 2.70 0. When generating line-to-line legs.40 0.36 Egress ISL-DN 2 778 1.36 Access ISL-DN 773 1 2.25 Access GMB1-36A 1 773 2.Access/ Line Node Node Time tance Egress Name --------------------------------------------1 773 2.78 Egress GMB1-2B 4 750 0. the program applies the following rules: 818 Cube Voyager Reference Guide .36 1.31 Access PLB127B 4 750 0.56 0.56 0.31 Access PLB1-113B 4 750 0.56 0.40 0.25 Egress GMB1-36A 773 1 2.25 Access GMB1-24MA 1 773 2.56 0.25 Access GMB1-24MB 1 773 2.40 0.70 0. the program expands nontransit legs between stop nodes.40 0.06 Egress GMB1-24MA 3 749 3.78 Access GMB1-2A 749 3 3.36 Access ISL-UP 1 2052 8. and walk transfers between stops into line-to-line legs.06 Access GMB1-24MB 778 2 1.40 0.56 0. The route-enumeration process eliminates some transfer legs.36 1.31 Access PLB127A 4 750 0.36 Egress ISL-UP 2052 1 8.70 0.56 0.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. For multirouting. consider the following transit lines. prohibit transfers involving backtracking. permit boarding at the first node and alighting at the last node.” retain only the lowest-cost connector. then the program records two transfer locations: one at stop 1 and one at stop 4 (representing transfers at stops 3 and 4). Do not permit transfers to a transit line’s last node. If two lines traverse the same physical route with the same stop characteristics. Do not permit transfers from a transit line’s first node. the program only records one transfer location between Lines A and B instead of four—the last stop. discard the others. • • • • • Interchanges between two parallel lines In this case. such as if the node prior to alighting is the same as the one after boarding. If Cube Voyager Reference Guide 819 . if stop 2 is a stopping node for line A and not for line B. For circular lines with the same first and last nodes. The program relaxes this restriction during route evaluation to give flexibility in transfer location. especially when modeling crowding. However. among multiple connectors between consecutive stops on a “from-line” and consecutive stops on a “to-line.Public Transport Program Theory 12 • For multirouting. passengers must use the line before transferring. 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). record only one transfer location for consecutive stops. For example. See “Route enumeration cost calculation” on page 801. Use the REREPORT control statement and LINELINELEG keyword to produce line-to-line transfer-leg reports. The program measures trip cost differently during routeenumeration than during route-evaluation. Use keywords in the FACTORS control statement to control the routeenumeration process. diverging between them.12 Public Transport Program Theory two lines meet at nonconsecutive stops. 820 Cube Voyager Reference Guide . the program records a transfer location at each stop where they meet. 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. and a nontransittransfer leg between node 1572 and node 1583. the process might disaggregate a minimumcost route into one or more discrete routes. or 495. 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. 478.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. described in “Enumerating routes” on page 824. the last of which is an egress leg. 489. and one or more pairs of transit and nontransit legs. 476. See “Enumerating routes with a must-use mode specified” on page 825. Each route has an access leg. Using explicit couples of transit and nontransit legs is consistent with the multirouteenumeration process. 493. • Cube Voyager Reference Guide 821 . Triplet 1276->1572->1583 represents a transit leg between node 1276 and node 1572 on line 744 or 746. Triplet 1583->1654->100 represents a transit leg between node 1583 and node 1654 on line 399. Because the process starts with transit-leg bundles rather than individual transit legs. 486. and an egress leg between node 1654 and node 100. Finding minimum-cost routes The route-enumeration process finds minimum-generalized-cost routes between zone pairs to establish a baseline cost. 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. This is a reason to prefer multirouting.12 Public Transport Program Theory The route via lines 744 and 399 will have the best travel cost. the route-enumeration process uses the number of transfers from the minimum-cost routes along with EXTRAXFERS1 and EXTRAXFERS2. You can specify a “spread. 822 Cube Voyager Reference Guide . EXTRAXFERS1. and specify function parameters with the SPREADFACT and SPREADCONST keywords. The route minimizes the generalized cost. 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. not the number of transfers. identified routes might have more than MAXFERS transfers. the route-enumeration process generates a set of connectors that describe available connections with other transit lines. which includes both the direct and indirect routes in the full list of enumerated routes. Minimum-cost routes minimize some combination of userspecified trip attributes. the other routes may have the same or slightly longer vehicle travel time. However. to set the maximum number of transfers permitted on “reasonable” routes to a destination. If a destination’s minimum-cost route uses more than MAXFERS transfers and the route-enumeration process has identified no other routes. Establishing connectivity between lines For each transit line. Select the function for calculating the spread with the SPREADFUNC keyword. and EXTRAXFERS2. Similarly. Passengers might not select such routes. you can reflect the impact of transfers in the generalized cost with sensible boarding penalties. Therefore.” an upper cost limit for routes between an O-D pair when using multirouting. Connectors are subject to constraints imposed by the keywords MAXFERS. at this stage the process only requires the number of transfer points and the lines reached.Public Transport Program Theory 12 Each connector consists of a set of lines: the “from” line. the “to” line. 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 . the number of transfers) is controlled by the three keywords mentioned. The process stores connectors in a very compressed form. The process examines alternative transfer points between lines when enumerating the route—in the next stage. Simple public transport network illustrating line connectivity For this network. and intervening lines required to reach the “to” line. consider the illustrated public transport network. The connector’s length (that is. 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 process treats lines like nodes and treats line-to-line connections like links in a network. The default configuration specifies all zones. For example. and the process builds connectors for all lines. When generating connectors. • Output valid routes Examine expanded routes to find routes that link to nontransit legs terminating in zones. and destination-zone selection (ROUTEO J) criteria. Repeat the process for the subsequent lines in the connector set until connections have been fully expanded. the routeenumeration process enumerates routes for each selected origin zone connecting to the line via a valid access leg. Enumerating routes After generating the connectors for a transit line. Examine the transfer points between the first two lines of the connector. If the complete route between the O-D pair meets the spread. Examine each interchange between the two lines in the same way. between lines A and B and lines A and D. extend the route by the transfer. 824 Cube Voyager Reference Guide . transfer. and the number of transfers meets the constraints set by MAXFERS. If the transit leg used on the first line is the bundle’s top leg. the sum of time for transit and nontransit legs) is within the spread established earlier. EXTRAXFERS1 and EXTRAXFERS2. output as a route between that O-D pair. and the time to the next boarding point (that is. The process uses two steps: • Expand routes with viable connections Record the beginning of the first route: origin zone and nontransit (access) leg. between lines A and B and lines B and C.12 Public Transport Program Theory Line-to-line legs handle all transfers—direct. and by walking. Enumerating routes with a must-use mode specified When enumerating routes required to use a particular transit mode. 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. Cube Voyager Reference Guide 825 . the process enumerates any route that uses at least one of the modes. consider the connector.” shown in the example in “Establishing connectivity between lines” on page 822. “line A to line C via line B. The route-enumeration process generates the routes in the following table. the process calculates a cost limit using spread factors as described in “Finding minimum-cost routes” on page 821. For a particular origin-destination pair. When establishing the minimum-cost route. If you specify two or more must-use modes. If this value exceeds the total of the cost (along the minimum-cost path) plus MUMEXTRACOST. the process considers all possible routes. regardless of whether they use the specified transit modes. shown in italics. The limit on transfers is based on the number of transfers on the minimum cost route. EXTRAXFERS1 and EXTRAXFERS2. the route-enumeration process uses a similar procedure. then the process reduces the cutoff value to this total.Public Transport Program Theory 12 For example. ) Starting at the origin. The route-evaluation process eliminates routes that do not use the specified transit mode. Passengers continue. passengers choose between one or more transit alternatives for the next stage of the trip. passengers might use one or more access legs (first-level branches).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 removes routes that alight and reboard the same service. Route-evaluation process The route-evaluation process calculates the “probability of use” for each of the enumerated routes between zone pairs. (The process compresses data for efficiency. such as routes with a probability of use less than the minimum specified by CHOICECUT. The process enumerates routes if at least one line in the bundle uses the specified mode. The process discards enumerated routes that fail to meet certain criteria. Before computing probabilities. At a stop. 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. See “Generalized cost” on page 797 for a description of the trip cost used in route evaluation. One or more second-level branches linked to the first-level branch represent the available choices. making 826 Cube Voyager Reference Guide . The expected (generalized) cost to destination is the cost along a discrete route. When making transit-line choices. and calculates the probability of choosing each discrete route. If routes have a must-use mode. the composite cost obtained from skimming is identical to the route’s generalized cost. The calculations of the servicefrequency model are described in “Deriving cost used” on page 828. This is simply the product of all conditional probabilities along the route.) The second pass starts at the origin. the route-evaluation process checks to ensure that all routes satisfy the condition. “Models applied at decision points” on page 830. but assigns all demand at any decision point to the cheapest alternative. the process does not support the servicefrequency-and-cost model. For multirouting models. When the decision tree includes walking or alternative alighting choices. (The routeenumeration process only ensures that at least one line in a transitleg bundle satisfies the condition.) Like the calculation of hierarchic logit models. All routes arrive at the same destination. passing through the data tree twice. the process uses the servicefrequency model. the first pass starts at the destination zone and calculates the conditional probabilities of each alternative at any decision point in the tree structure. For best-path models. until reaching their destination.Public Transport Program Theory 12 choices from additional branches. Because demand along a discrete route is not divided among alternatives. the route-evaluation process calculates routes in two steps. though they arrive via different branches. Conditional probabilities define what proportion of the trips arriving at a node proceed along each alternative branch. the process selects the cheapest route to the destination and discards all other alternatives. (Trips arriving at the node may proceed towards the destination along any of the alternative next-level branches. and Cube Voyager Reference Guide 827 . the process uses the two-pass algorithm. the process allocates routes assuming “all reasonable lines forward from a node” (as with multirouting). without separating by mode. and wait times. the costs are usually simple. the process computes the expected cost to the destination for each leg. the process computes the expected cost to destination. For multirouting models. 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. the calculations consider all lines in a transit-leg bundle. at the start of the egress leg. the process computes service-frequency-model calculations for identical-mode lines in a transit-leg bundle. For example. the cost includes walk. working away from the destination. the process uses this generalized cost for calculating the probability that passengers will use alternative routes. Often called composite cost. the process allocates specific routes. but for best-path models. At points close to the destination. where there are alternative routes.12 Public Transport Program Theory “SFM and SFCM examples” on page 836. Computed at decision points using the composite-cost formula. Adding new services or improving existing services does not increase the cost—improving service enhances passenger utility. At points further from the destination. transit. the process combines the costs to form a single value for the expected cost to destination from a single point. For each route forward. For multileg trips. By default. However. 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. when FREQBYMODE is set to F. the cost of the leg is the cost to reach the destination. 828 Cube Voyager Reference Guide . This set of services is known as the basic choice set. 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.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. In calculating the transit element of the expected cost to destination. 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. producing a single value that represents the set of alternatives: – 1. Specifically. The logit composite cost formula combines costs. Cube Voyager Reference Guide 829 . the process uses logit models. the process applies an additional condition to ensure that adding (or improving) services does not increase costs. Then.Public Transport Program Theory 12 At choices between walking and alighting transit.0 C ( comp ) = --------. 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). board a different line at that stop. For example. This model has a logit structure: i ai e P ( walktoi ) = ----------------------------------------------– λ ( CW i + αECD j ) e – λ ( CW + αECD ) ∑ j 830 Cube Voyager Reference Guide . when passengers leave the origin or alight from a service. or walk to another stop for the next transit leg.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 route’s decision points. they might walk to their destination. 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. is the expected (generalized) cost to destination from j. is the expected (generalized) cost to destination from i. the process subtracts this value of choice from the average cost (evaluated with ALPHA set to 1.0. Next.0) to estimate the nondiscounted (true) composite cost. A value of 1 indicates that the walk and onward costs have equal weight. the process uses ALPHA to calculate the value of choice for the walk-choice model. or the benefit travelers gain from choosing between available alternatives. calculated as part of any logit model. represents the true cost to the destination (or trip cost). lower values indicate that the walk cost has more influence than onward cost in the traveller’s choice. the cost from the end of the walk leg to the destination is discounted.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). and has a different numeric value from the discounted form. specified by ALPHA. a traveller’s willingness to walk may relate to familiarity with the network. The composite-cost specification. When the ALPHA value that the walk-choice model uses is less than 1. First. the process estimates a composite cost consistent with the nondiscounted cost to the destination.0. shown above. To adjust for an ALPHA value less than 1. CWi α ECDi ECDj Composite cost adjustment for ALPHA The difference between the average and composite cost values. represents the value of choice. Cube Voyager Reference Guide 831 . more trips are allocated to the best route. 0. 832 Cube Voyager Reference Guide . The curve for LAMBDAW = 0.2. Thus.6% of the total trips. With a scaling factor of 0. low scaling factors produce trips spread over a wider range of alternatives. The diagram plots three different values for the scaling factor: 0. the longer route gets 26. Large the scaling factors produce a smaller spread of trips between alternatives—that is.9% of trips. and 1. longer routes get a larger share of the trips as the scaling factor is reduced. but with a scaling factor of 1. Conversely.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.5 shows that a choice five minutes longer than the best would be allocated 7. and the time by the best service. ECDbest. ECDi.67% of trips. Impact of the different values of scaling factor LAMBDAW The X-axis shows the difference between the time by service i.0.5. the longer route gets only 0. The Y-axis shows the proportion of trips allocated to the longer choice when a binary choice is available.2. and that the traveller is less willing to use slower alternatives. See “SFM and SFCM examples” on page 836 for examples that show how the two models treat transit choices at a stop.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). 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 ∑ k where: P(use line l) is the probability of using line l. the servicefrequency model calculates the conditional probabilities of the individual lines in proportion to their frequency. Service-frequency-and-cost model The service-frequency-and-cost model is an extension of the service-frequency model. which may be different from the basic choice set described in “Deriving cost used” on page 828. Frequency(line k) is the frequency of line k (in services per hour). The model assumes that travellers have knowledge of the travel time to the destination associated with each of the alternative routes. This model defines its own set of transit choices. Cube Voyager Reference Guide 833 . Frequency(line l) is the frequency of line l (in services per hour). Service-frequency model Applied at stops with a basic set of transit choices. SFM considers only service frequency while SFCM also considers the cost to the destination. If that line passes the validity test. then the line is always a valid choice. • • As the probability of use varies between lines. the model selects the line with lowest expected cost to the destination. If the excess time is greater than zero but no more than the expected cost of waiting. as follows: Frequency ( combined ) = ∑ P(use l) Frequency(line l) l 834 Cube Voyager Reference Guide . the model considers the next fastest line. The validity test computes the line’s “excess time” — the difference between its time to destination and the average value for the lines already selected (excluding wait time at the stop). travellers are better off ignoring this line and waiting for the next service from the selected set. one minus this proportion defines the probability of using the line when its service arrives at the stop. the line is valid some of the time. excess time divided by the cost of waiting defines the proportion of time that travellers are better off ignoring the line. considering the next fastest line.12 Public Transport Program Theory To define a set of transit choices. then the line is not valid. Once a line fails the validity test. Next. the model adds the line to the set of selected lines and repeats the process. If the excess time is more than the expected cost of waiting. the line is no slower than those already selected). The test compares the line’s excess time to the expected cost of waiting (which is based on the headway of the combined services already selected. the process terminates and the model uses the set of lines currently selected as possible routes to the destination. Therefore. and any wait factors): • If the excess time has a value of zero (that is. the frequency of the combined services takes account of probability of use. Specifically. Frequency(combined) is the combined frequency of a set of selected lines (in services per hour). During loading. is the frequency of the line l (in services per hour). 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 ∑ j Cube Voyager Reference Guide 835 .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. For an example. the walk-choice model allocates demand between true walk alternatives and an imaginary alternative that represents the transit services available at the node. ECDi ECDj is the expected (generalized) cost to destination via alternative alighting point i. 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 . First.12 Public Transport Program Theory where: P(alight at i) is the probability of alighting at stop i. NOTE: LAMBDAA affects the choice of alighting points just as LAMBDAW affects walk choices. is the expected (generalized) cost to destination via alternative alighting point j. Opportunities for transfer At transfer points between transit services. Next. the service-frequency model allocates the transit demand to the various services at the stop. the route-evaluation process applies a combination of models. see “Impact of the different values of scaling factor LAMBDAW” on page 832. λ is the scaling factor for the model (LAMBDAA). 0 5.5 * Wait Factor Column (6) = (2)*(3).333 (8) Travel + Wait Times 32.0 26. Line 5 is excluded from the basic choice set because including it makes the time to destination worse.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.429 0. A wait factor of 2 was used to weight the waiting times.0 Cum Travel Time 100 226 270 294 320 (7) Average Travel Time 20 20.0 Cube Voyager Reference Guide 837 . the overall time to destination improves.0/(4) * 0.385 25.286 25.143 0. 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.615 4. with the addition of each line.0714 0.769 21 21.545 20.455 4.357 0. Column (5) = 60.333 (9) Include Line Y Y Y Y N Notes: • Lines 1-4 are included in the basic choice set because.286 4.0 25. 326 - 12 5.798 Notes: • • • • • Example uses a wait factor of 2 to weight the waiting times.1) Column (8) = (2)*(7). Column (7) = 1-MIN( (5)/(6)).52 20.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.917 0.52 20.714 5.868 - 20 20.48 3.202 12 5.707 20.293 5.0/(7) * 0. accumulated over lines Column (9) = 60.983 12.714 5. accumulated over lines) / (8) 838 Cube Voyager Reference Guide .5 * Wait Factor Column (10) = ((2)*(3)*(7).342 0 5 10.798 1 1.868 1 0.500 11.007 4.742 0.707 20.007 4. operational statistics.326 (5) Proportion of trips 0.120 0. Cube Voyager Reference Guide 839 .446 0.500 11. the program can provide several skims.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.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.343 (4) Cum frequency at stop 5 10. Because the Public Transport program finds multiple routes between zone pairs.406 0.483 0.983 12.500 1. 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. 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. To enable you to model demand or evaluate schemes. the value-of-choice skim computes the value of choice. The skim calculates composite costs from each decision point in the trip to the destination. 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. a measure of the extent to which travellers can choose between alternative routes. the composite-cost skim computes the composite cost.12 Public Transport Program Theory Composite-cost skim For each zone pair. the skim ensures that adding new routes or improving services does not lead to an increase in the cost. 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 is equivalent to the difference between the composite-cost skim and the average-generalized-cost skim. 840 Cube Voyager Reference Guide . With more low-cost choices. whereas lower values indicate a lack of route choice. the system can continue functioning following the failure of one or more components. also referred to as the expected cost to destination (see “Deriving cost used” on page 828 for a description of how they are derived). Higher values indicate travellers can choose between routes of similar costs. or the total utility of the trip including the choices available to the traveller. The route-evaluation process uses composite costs. You can extract average skims for all components of the trip. average skims weighting each route according to its probability of use. hours.Public Transport Program Theory 12 Average skims Average skims compute the costs a typical traveller incurs while making a public transport trip. Within each route set. and revenue. Cube Voyager Reference Guide 841 . Best-trip skim For each zone pair. the time if travellers make the best choice at every decision point). Several average skims can compute either actual values—true measures of the cost—or perceived values—the cost’s contribution to generalized cost (usually a product of the cost and a weighting coefficient). Average skims compute component costs at network and route-set level. Average skims are appropriate for model validation and skimming operational statistics. average skims can compute costs other than wait time by mode. the best-trip skim computes the actual time for the best route (that is. such as passenger miles. There are three broad areas: • Time Walk (nontransit) Wait In-vehicle • Inconvenience Boarding Transfer • Cost Fare Because multiple routes might connect zone pairs. 842 Cube Voyager Reference Guide . therefore. using the combined frequencies of all acceptable lines from the node towards the destination. The process assigns the zone pair’s trips to the available routes according to each route’s probability of use. The skim computes wait times from the appropriate wait curve. Loading process The loading process (assignment) allocates trips. See “Walk time (nontransit time)” on page 798. to services (transit lines) and nontransit legs. The skim bases the wait time and the transit-leg time on the lowest expected values. The skim computes transit-leg times from the fastest line in the leg-bundles used. NOTE: At present. the one used to construct them (perceived time). The loading process considers one origin-destination zone pair at a time. walk (nontransit) legs have only one time attribute. either computed or from the input trip matrix. and is. the skim does not reflect traveller behavior. calculated during the route-evaluation process. The loading process uses routing and travel time information obtained from the route-evaluation process.12 Public Transport Program Theory Because the skim uses actual values for all trip components. inappropriate for demand modeling. 028 1 -> 2052 2052 -> 2004 -> 875 lines ISL-DN 875 -> 749 -> 3 lines GMB1-2B Cost=31.631438 1 -> 773 773 -> 759 -> 759 lines GMB1-24MB 759 -> 875 -> 875 lines RES34R 875 -> 749 -> 3 lines GMB1-2B Cost= 28.142594 1 -> 2052 2052 -> 2004 -> 875 lines ISL-DN 875 -> 749 -> 3 lines GMB1-2B Cost= 30. All routes meet the evaluation criteria.628 Probability=0.225968 The first report shows three bundles of enumerated routes from zone 1 to zone 3.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. The enumerated-routes report shows used costs. 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.Public Transport Program Theory 12 For example. Cube Voyager Reference Guide 843 . consider the reports of enumerated and evaluated routes between zones 1 and 3.668 Probability=0. The second report lists the routes with their probability of use.04 Probability=0. none are eliminated.668 1 -> 773 773 -> 759 -> 759 lines GMB1-24MB 759 -> 875 -> 875 lines RES34R 875 -> 749 -> 3 lines GMB1-2B Cost=34. However. all trips arriving at node 773 board this service. The time via 764 is less than the time via 759. At 764. 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. GMB1-24B. 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. The loading process considers two walk choices from zone 1: to nodes 773 and 2052. From node 751.774032. there is a single transit service.631438 and the probability of using node 759 is 0.225968.12 Public Transport Program Theory the evaluated-routes report shows the average cost for the route bundle. There are two alighting points: nodes 764 and 759. travelers go to zone 3 via node 749 and line GMB1-2B. and then to transit line GMB1-2B for the trip to node 749 before ending at zone 3. These are saved for the nontransit (egress) leg 749-3. The loading process splits trips at node 773 between the two alighting points and saves the trips for the two transit legs. PLB129B. The process saves the number of trips assigned to the four transit legs for each leg. and PLB127A in proportion to their relative frequencies for trips to node 751. the loading process assigns travelers to transit line ISL-DN for the trip to node 875.142594. • At node 2052. not the composite costs used to calculate the probability of use. All trips from zone 1 to 3 use line GMB1-2B as the last transit leg in the trip. reflecting the shorter time via node 773. At node 759. while the probability of going to node 2052 is 0. Thus the probability of using node 764 is 0. and alight at node 749 where they walk to zone 3. The route-evaluation process determined that the probability of going to node 773 is 0. 844 Cube Voyager Reference Guide . the loading process assigns arriving trips to lines PLB1-113B. Cube Voyager Reference Guide 845 . To incorporate fares. 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. it is import to incorporate fares fully into the Public Transport modeling process. Fares This section describes how to model fares in the Public Transport program. 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. Therefore. and computing the total trips using transit and nontransit legs on the underlying network links.Public Transport Program Theory 12 The loading process is complete after assigning trips between all (selected) origin-destination zone pairs. you might exclude fares from the route-evaluation process and skim and calculate revenue from the evaluated routes. To reduce run times. that uses a single transport line. the program assumes integrated or through ticketing and calculates fare for that sequence of legs. You define fare system attributes with FARESYSTEM keywords and subkeywords: • • Unique numeric and character identifiers (NUMBER. You can specify fare systems and value of time by user class. To model fares. FAREFROMFS) • 846 Cube Voyager Reference Guide . If multiple consecutive legs have the same fare system. from a boarding point to an alighting point. the Public Transport program requires a programwide “fare system” that describes each transit line’s individual fare system. A transit leg is one part of a trip. and the cost of transferring between fare systems (IBOARDFARE. (STRUCTURE. LONGNAME) Unit of measure for trip length. The program calculates fare for a single leg of the trip. FROMTO. either directly or through its mode or operator. HILOW. or boarding-alighting fare zones. Transit legs are the basic unit the program uses to calculate fares. In fact.12 Public Transport Program Theory The Public Transport program must accurately represent the fare systems that passengers face. DISTANCE. number of fare zones crossed. you can represent different types of fare systems within a single public transport network. its data requirements. COUNT. or ACCUMULATE) Boarding costs at the initial boarding and subsequent transfers. with possible values: FLAT. such as distance. and how it interfaces with other lines. The program assigns each line to a fare system. You define fare systems with the FARESYSTEM control statement and input fare systems with the FILEI FAREI file. The Public Transport program provides a framework which you can use to directly represent or approximate most fare systems. You might do this to use readily available ticket type data to segment and model demand by ticket type. NAME. 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. by selecting skimming functions FAREA and FAREP in the SKIMIJ phase. which may be specified with a coefficient per unit measure of the trip. FARETABLE. or matrix (UNITFARE. each line must have an assigned fare system. whether or not they are included in route-evaluation. Requirements can vary from minimal to substantial. FARETABLE. Include fares in the route-evaluation process by setting PARAMETERS FARE to T. Cube Voyager Reference Guide 847 . The following table provides a quick reference to the various fare systems and their data requirements. as it could be included in the FAREMATRIX. a table. The program assigns fare systems to transit lines indirectly through the line’s mode and operator with the FACTORS FARESYSTEM keyword or directly with the LINE control statement.Public Transport Program Theory 12 • Trip cost. 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. FAREMATRIX) Rules for computing costs when transferring to the same fare system and interpreting fare tables (SAME. and FAREMATRIX). Skim fares. 3 Permitted but use is questionable. When modeling fares. Fares derived by leg using the boarding and transfer costs specified with IBOARDFARE and FAREFROMFS. Description of trip-length units Value of STRUCTURE FLAT Method for calculating trip length and fare Trip length not used for fare calculation. Fares based on: • • • Boarding and transfer costs. You specify the trip-length unit with the FARESYSTEM keyword STRUCTURE. Trip-length units might be based on legs. extracted from the fare matrix specified with FAREMATRIX (rows contain the lower fare zone.12 Public Transport Program Theory Trip length The units for measuring trip-length is a key attribute of the fare system. actual distance. and columns contain the higher fare zone) • 848 Cube Voyager Reference Guide . Each value results in a different method for calculating trip length and fare. specified with IBOARDFARE and FAREFROMFS. Fares calculated by leg or for sets of consecutive legs using the same fare system. DISTANCE Trip length measured as in-vehicle distance. Trip cost obtained from the fare table specified by FARETABLE. HILOW Trip length measured by the highest and lowest fare-zones crossed. Fares calculated by leg or for sets of consecutive legs using the same fare system. Trip cost computed by multiplying in-vehicle distance by UNITFARE. There are six possible values. The value of INTERPOLATE determines whether the program uses linear interpolation or a step function between coded points. Fare zones are single nodes or groups of nodes. Appropriate for an annular fare-zone structure. specified with IBOARDFARE and FAREFROMFS (boarding costs are added to the fare matrix) Trip cost. Fares based on: • Boarding and transfer costs. or fare zones. in user-specified units. Fares based on: • • Boarding and transfer costs. and columns contain the higher fare zone) • ACCUMULATE Trip length measured by accumulating fares associated with each fare zone traversed. FROMTO Trip length measured as function of the boarding and alighting fare zones. Best suited to a sequential zone system.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. Fares calculated by leg or for sets of consecutive legs using the same fare system. specified with IBOARDFARE and FAREFROMFS Trip cost. specified with IBOARDFARE and FAREFROMFS Trip cost. where program counts the number of fare zones traversed to compute fare. Trip cost. the program interpolates the fare table as a step function. Fares calculated by leg or for sets of consecutive legs using the same fare system. Differs from COUNT. Fares based on: • Boarding and transfer costs. Fares based on: • • Boarding and transfer costs. Best suited to a sequential zone system. Fares calculated by leg or for sets of consecutive legs using the same fare system. extracted from the fare matrix specified with FAREMATRIX (rows contain the lower fare zone. Best suited to a sequential zone system. The fare table has a fare for each fare zone in the system. extracted from the fare table specified with FARETABLE. In this case. specified with IBOARDFARE and FAREFROMFS (boarding costs are added to the fare matrix). Cube Voyager Reference Guide 849 . extracted from the fare table specified with FARETABLE. You specify boarding and transfer costs with FARESYSTEM keywords: • • IBOARDFARE — Fare incurred upon boarding the first transit leg of a trip. Boarding and transfer costs Boarding and transfer costs are key attributes of the fare system. 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. Trip costs Trip cost is a key attribute of the fare system. Only available when STRUCTURE is DISTANCE. See “FAREFROMFS” on page 689. COUNT.12 Public Transport Program Theory Multiple fare systems For public transport networks with multiple fare systems. the program multiplies UNITFARE by in-vehicle distance of a leg or a sequence of consecutive legs using the same fare system. the program always calculates the fare separately for each leg. Used when STRUCTURE is DISTANCE. or ACCUMULATE. 850 Cube Voyager Reference Guide . FAREFROMFS — Fare incurred when transferring from lines using other defined fare systems. FARETABLE — Table of fares. Define FARETABLE with a • list of paired X and Y coordinates. See “IBOARDFARE” on page 692. The program determines trip cost using one of three methods: • UNITFARE — Coefficient used to calculate fares. If two consecutive legs of a trip use different fare systems. To obtain fare. where X is the trip length and Y is the fare. Some graphic examples follow.Public Transport Program Theory 12 See “FARETABLE” on page 690 for more information about coding FARETABLE. Fare table for STRUCTURE=DISTANCE and INTERPOLATE=T Fare table for STRUCTURE=DISTANCE and INTERPOLATE=F Cube Voyager Reference Guide 851 . but a fare system must have only one zone scheme. Fare zones Fare systems that have the STRUCTURE set to HILOW. A public transport network might have multiple fare-zone schemes. a node can be in only one fare zone. To report on fare matrices. See FAREMATRIX for information about coding fare matrices. Used when STRUCTURE is HILOW or FROMTO. FROMTO. You code fares in monetary units. Input matrices with FILEI FAREMATI in either standard Cube Voyager binary matrix format or as text records. COUNT.12 Public Transport Program Theory Fare table for fare-zone based fare systems • FAREMATRIX — Matrix of fares. 852 Cube Voyager Reference Guide . Therefore. The program converts fares to generalized costs using the FACTORS keyword VALUEOFTIME. or ACCUMULATE require fare zones. use the REPORT keyword FAREMATI. Fare zones are either groups of nodes or single nodes. Display the network in Cube. Display the network in Cube. Cube Voyager Reference Guide 853 . b. or ACCUMULATE structure 1. a. 3.Public Transport Program Theory 12 The HILOW structure requires an annular fare zone system while the other structures require sequential fare zones. Use the Polygon menu to define fare zones. one at a time 4. type FAREZONE and click OK. To identify and code fare zones for fare systems with a FROMTO. COUNT. and choose Add. From the Node menu. such as FAREZONE. 2. point to Attribute. 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. Add a new node attribute to store the fare zone. In the Add Note Network Variable dialog box. Example of an annular zone system 854 Cube Voyager Reference Guide . In the Add Note Network Variable dialog box. such as FAREZONE. type FAREZONE and click OK. Use the Polygon menu to define a ring separating the outermost fare zone from the other zones. 5. a.12 Public Transport Program Theory 2. Associate the number of the outermost fare zone to the new fare-zone attribute of all nodes. b. and choose Add. 4. Add a new node attribute to store the fare zone. 3. From the Node menu. point to Attribute. 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. STRUCTURE=DISTANCE. SAME=CUMULATIVE. NAME=’Distance Underground’. NAME=’Distance British Rail’.2. NAME=Flat Fare British Rail’.75. IBOARDFARE=100. STRUCTURE=DISTANCE. 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. STRUCTURE=FLAT. FAREFROMFS[1]=0. 0 FACTOR FARESYSTEM=1. FAREFROMFS[1]=0. UNITFARE=60 FARESYSTEM NUMBER=3. 10. MODE=2.0.Public Transport Program Theory 12 Examples This section shows how fares are calculated for a four-leg trip using different fare models. 5. for transferring from FARESYSTEM 1 to = = 0 {FAREFROMFS[2] for C-D. NAME=’Distance Bus’. MODE=1 FACTOR FARESYSTEM=2.0. which is the sum of fares for each leg. IBOARDFARE=100. all with STRUCTURE set to DISTANCE but with different unit cost for trip length. IBOARDFARE=50. 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. 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 Underground+Bus’. FAREFROMFS[1]=50. FARETABLE=1. 100. 0. STRUCTURE=DISTANCE.50. individually and in combination. 100. STRUCTURE=FLAT. 100.0. FAREFROMFS[1]=75.3 FARE(A-E) = 175 pence. UNITFARE=50 Cube Voyager Reference Guide 855 .50 FARESYSTEM NUMBER=2. IBOARDFARE=100. FARESYSTEM NUMBER=1. 100 FARESYSTEM NUMBER=2.0. FAREFROMFS[1]=100.3. IBOARDFARE=50. 50. 0. 12 Public Transport Program Theory FACTOR FARESYSTEM=1. which is the sum of fares for trip legs.FAREZONE FACTOR FARESYSTEM=1. MODE=1 FACTOR FARESYSTEM=2. Example 3: FROMTO fare system FARESYSTEM NUMBER=1.FAREZONE.FAREZONE(A) and column NI. legs B-C and C-D have the same fare system and SAME is set to CUMULATIVE. SAME has no effect in this case because UNITFARE is used rather than FARETABLE. 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. so the fare is calculated for B-D. 856 Cube Voyager Reference Guide .5. MODE=2 FACTOR FARESYSTEM=3. depending upon the setting of SAME.1.FAREZONE(E). There is no cost for transferring from fare type 2 to another leg using the same fare type. STRUCTURE=FROMTO. There are no boarding costs or costs for transferring between the same fare system. FAREMATRIX=FMI. NAME=’Trip Based’. defines the fare zones for stops A through E. In this example. MODE=1-3 FARE(A-E) = 350 pence. FAREZONES=NI. and the program extracts the fare from fare matrix number 5. MODE=3 FARE(A-E) = 950 pence. row NI. NI. The node variable. input on FAREMATI[1]. 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. the fare can be calculated for each leg separately or cumulatively. 1. UNITFARE=50. NAME=’Bus’. STRUCTURE=DISTANCE. NAME=’Underground’.UndGrnd. as calculated during route evaluation. row NI. -25. 50.2.” The program multiplies the crowding factor by in-vehicle time to determine the perceived “crowded in-vehicle time.Public Transport Program Theory 12 FARESYSTEM NUMBER=1. FAREZONES=NI.FAREZONE(B). column NI.1. 0 FARE (A-E) = 525 pence.BritRail. FAREFROMFS[1]=50.FAREZONE(A). IBOARDFARE=50. column NI. NAME=’British Rail’.FAREZONE(D)) Leg D-E = 50 + 1*50 (FAREFROMFS[2] + trip cost) Crowding An iterative process. FAREZONES=NI.” Cube Voyager Reference Guide 857 . which is the sum of fares for legs. SAME=CUMULATIVE. 0. crowd modeling enables a public transport system’s capacity to influence the system’s travel times and thus the routes found and their probability of use. STRUCTURE=FROMTO.FAREZONE FARESYSTEM NUMBER=3. 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 passenger’s perception that travel time is more onerous when standing (rather than sitting). calculated as: Leg A-B = 250 (FAREMATRIX FMI. Specify this adjustment with a “crowding factor. row NI. FAREFROMFS[1]=-25. or when in crowded vehicles. FAREMATRIX=FMI.FAREZONE FARESYSTEM NUMBER=2. STRUCTURE=FROMTO. FAREFROMFS[1]=0. 0.UndGrnd.BritRail.2.FAREZONE(B)) Leg B-D = -25+200 (FAREFROMFS[1] and FAREMATRIX FMI. FAREMATRIX=FMI. 0. Example of crowding factor values (as a function of vehicle load) 858 Cube Voyager Reference Guide .85 (standing occurs when more than 85% of 40—that is. the crowding factor might increase slowly from 1.0 for the first few standing passengers. 34 seats—are occupied).12 Public Transport Program Theory For example. and load distribution factor of 0. Once standing starts. then more steeply once vehicle loading exceeds 40. suppose a vehicle has a seating capacity of 40. crush capacity of 50. as a function of utilization Crowd factors are 1. the percentage of standing places occupied. Crowding curve definition. Derived from the crowd-factor curve.0 in uncrowded conditions. crowding curves show utilization on the X-axis.4 for seated passengers and 1. The corresponding crowding curve is shown below. c ( U ) where: Tc Tu is the crowded link travel time is the link travel time (in uncrowded conditions) CCrvv.Public Transport Program Theory 12 The Public Transport program uses crowding curves.5 to 3.c (U) is the crowd curve value (where the curve is specific to a vehicle type. v.0 for standing passengers when the vehicle is fully loaded with standing occurring.0 to 1. and typically rise to values in the ranges 1. c) for utilization U U is the utilization measure (as a percentage) Cube Voyager Reference Guide 859 . can vary between 0 and 100. Utilization. and a user class. The program calculates crowded link travel time as: T c = T u CCrv v. 12 Public Transport Program Theory The utilization measure. If the values of seating capacity and crush capacity are identical for any line. is the seating capacity (per hour) for the line. then utilization is 100% whenever demand exceeds the seating capacity. incurring additional wait time at the boarding node. (Note: the LDF value specified in commands is coded as the corresponding percentage. 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 travellers will choose the first appropriate service that has available capacity. Wait-time adjustment The wait-time adjustment reflects the ability to board a service. some travellers will wait for the next service. U. this becomes less realistic. indicating that standing occurs before all seats are used. this is the total of seated and standing capacities. It may be less than 1. and 0% otherwise. CrushCap is the crush capacity (per hour) for the line. 860 Cube Voyager Reference Guide . As loadings on services increase.0. is defined by the expression: P – ( LDF v SeatCap ) U = -----------------------------------------------------------------------CrushCap – ( LDF v SeatCap ) where: P SeatCap is the passenger demand (per hour).) 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). Using measures of demand and available capacity. As loads increase this is the proportion of seats occupied when standing starts to occur. With heavily loaded services. the wait-time adjustment computes the probability of being able to board a service. LDFv is the load distribution factor for the vehicle type. the program can calculate the proportion of flow-metered demand (that is. thus demand at any downstream point reflects the number of travellers who can reach that point. Cube Voyager Reference Guide 861 . demand unable to reach its destination due to network bottlenecks). those travelers experience additional delays. The additional wait time might make this route less attractive. and the number of trips affected. or service-frequency-and-cost model (SFCM). Flow metering removes the excess demand from later stages in the trip. If demand exceeds capacity and no alternative routes are available. resulting in diversion of demand to other enumerated routes for the origin-destination pair.Public Transport Program Theory 12 Without crowding. 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. The program reassigns this excess demand to other lines with spare unused capacity. The demand remaining at the end of the modeled period would discharge once peak travel volumes subside. 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. “Flow metering” handles the bottleneck effect and the inability of demand to pass through that point. those travellers incur additional wait time. which form a second component to the wait-time adjustment. For any origin-destination pair. the program assigns demand with the servicefrequency model (SFM). then this transit leg acts as a “bottleneck”—not all of the travel demand is able to use the service during the modeled period. oscillation is more likely in highly overloaded networks. as demand switches toward less congested routes.12 Public Transport Program Theory The crowding process is viewed as a stochastic assignment. those routes might become more heavily loaded. 862 Cube Voyager Reference Guide . In turn. or might continue oscillating. Crowded networks might cause instabilities in the loadings between iterations. These changes might converge toward a solution. and thus less attractive at the next iteration. 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. and results are obtained from the final iteration. Screenline data files specify the links that compose each screenline and contain associated data. See Cube Analyst Reference Guide for detailed information about the methods used. Matrix estimation requires an intercept file. or text-file editors. based on data values stored in the input network Cube Voyager Reference Guide 863 . 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.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. A run of the Public Transport program produces the intercept file. such as link counts and confidence levels. which provides data on routes crossing the defined screenlines for each origin-destination pair. Confidence levels determine how much each input influences the estimation process. Confidence levels reflect the accuracy of count data and affect the weighting during the estimation process. You can create a screenline file with: • • Cube. Cube Analyst uses screenline count data to update a “prior” matrix. and read the file in to the Public Transport run Public Transport run. and not in the script file. and NTLEGS). OPERATOR. the software may save just a screenline output file without performing any route evaluation. and CROWDCRVDEF LINE NT 864 Cube Voyager Reference Guide . Alternatively. These are present in the main script file. along with either a FILEI SCREENLINEI or a FILEO SCREENLINEO command. Use control statements to define input and output data items (that is.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). transit plus nontransit use of all links). OPERATOR. use the MEUSESNT keyword on PARAMETERS and FILEO SCREENLINEO commands. LINE. MODE. These are usually contained in files defined by FILEI and FILEO. WAITCRVDEF. VEHICLETYPE. For a Public Transport run to produce matrix estimation data. and confidence level. All control statements available in the Public Transport program are described in “Control statements” on page 653. Defining input and output files You define input and output files for the Public Transport program with control statements FILEI and FILEO. link count. To configure the intercept file to contain only transit use of the links. or all demand (that is. 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. This section shows which files contain which data items. the script must specify a FILEO INTERCEPTO command. because Highway assignment does not support turn-based preloads. link delay. though provisions like bus-only lanes can reduce or eliminate such delays at particular locations. transit-line run times are influenced by the highway network’s congestion levels. For networks with congestion.Public Transport Program Using the Public Transport program 12 Linking Highway and Public Transport models In studies that model both highway and transit demand. a typical highway model estimates delays on links and at junctions. you can link the two models. Link travel times include link delays. which provide control values. You might use control values in base-year models to ensure that the line’s travel time matches an expected value. LINE definitions can include RUNTIME. junction delays. TRANTIME and junction delays are network components. and include these delays in the run times of transit lines. When junction delays are included. and trip time also includes junction delays. and dwell time values. and delay and dwell time are line components. Cube Voyager cannot import transit-vehicle turn volumes from Public Transport to Highway. The program scales the line’s travel times up or down to match these control values. Cube Voyager can export junction delay data from Highway program runs. However. To model bus-only lanes or other provisions designed to reduce transit-line delay at junctions. Cube Voyager Reference Guide 865 . The Highway program can export delays for turning movements to a TURNPENO file. The Public Transport program can then read this file. or NNTIME keywords. 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. The Public Transport program calculates a line’s travel times using TRANTIME (a global parameter that represents link travel times). Junction delays can affect transit vehicles. Transit vehicles travel through junctions and take some of the junction capacity. RT. any changes reflect increases and decreases in junction delay along the route. The program applies these factors and the forecast-year junction delays to compute the line’s travel times in the forecast year. links. the program adds the entire junction delay to the travel time of the link approaching the modeled junction. This network can contain any node and link attributes you choose. When reading LINE data from a network file. you cannot code the time as part of the line. The program calculates the line’s travel times for the base year. Instead. each with its own MAXDELAY variable (to reflect possibly different bus-lane provisions each year). even though the vehicle does not pass through the node. and compares these times to the control values to generate scaling factors for the increase or decrease in travel times. Coding network times/speeds The Public Transport program requires a network that provides the basic infrastructure over which public transport services operate— zones. The program applies scaling to link travel times and delay values. the program determines travel times with an incremental approach. when you do not know the line’s travel time. The method uses two sets of TURNPENI data. Typically. modeled stops are close to a junction node. You might model turning delays at a transit line’s last node. Because the program does not scale these travel times to control totals. You should configure the model to read the TURNPENI file at the same time as the LINEI files. The program accounts for such delays as occurring before the line reaches its final stop.12 Public Transport Program Using the Public Transport program For forecast years. the program does not scale dwell times and junction delays. nodes/stops. Therefore. the program has already calculated link travel times and cannot amend turn penalties. produced specifically for modelling a public transport system 866 Cube Voyager Reference Guide . The program adds that node’s lowest turning delay to the travel time along the final link. Possible sources of the network include: • Network program. Possible techniques include: • Set a link’s transit time to the congested time resulting from a highway assignment: TRANTIME = LI. in which case only the network information is used (the public transport element is discarded) The network must provide basic link attributes that support the Public Transport program’s modelling functions: link distance. as described in “LINE” on page 745. and walk and transit times or speeds. to skim distance from routes. • Cube Voyager Reference Guide 867 . The program uses link distance to calculate link times when you provide only speeds. 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. and to calculate fares for distancebased fare models. Create a network variable that stores transit speeds with the Network program.DISTANCE or another variable from which distance can be derived). Link distance is required (specified by LI. (You can factor each line’s base linktime in a variety of way. This is supplied to the program with PARAMETERS TRANTIME.Public Transport Program Using the Public Transport program 12 • • Existing highway network produced by the Network or Highway programs Public Transport program.) You can use different techniques to specify a link’s transit time.TIME_CONGESTED (assuming the links contain a variable named TIME_CONGESTED). you must ensure that you use costs—perceived or actual—consistent with the cost components that the routeenumeration and route-evaluation processes use.SPEED endif ENDPHASE PARAMETERS TRANTIME=LW. you might need to precede the GENERATE statement with a script that manipulates link attributes. When developing the nontransit network outside the Public Transport program. However.SPEED * 1.) • Set array(s) of working link values in the LINKREAD phase and use those arrays in the TRANTIME expression. As in the LINKREAD phase. Input the TRIPS link records directly to the Network program to create a Cube Voyager network. Nontransit times/speeds You can develop nontransit legs outside the Public Transport program. The Network or Public Transport programs can derive transit and nontransit link times from the link record’s link-type field and the LTYP data in the lines file.TTIME = LI.DISTANCE*60/LI. Regardless of the process. you can exclude those links from highway assignments by setting those links’ path value to a negative value and their capacity to 0. Keywords in the GENERATE statement set the method for obtaining nontransit legs. you can loop through all the links in the network and set desired link values.TTIME = LI. For example: PHASE=LINKREAD if (link condition…) LW. or some combination. you must use GENERATE statements within the DATAPREP phase to develop a nontransit network.2 else LW.TTIME • TRIPS users only.12 Public Transport Program Using the Public Transport program (If the highway network stores public transport links. 868 Cube Voyager Reference Guide .DISTANCE *60 / LI. See “Example 2: Preparing a public transport network from TRIPS link data” on page 878. inside the Public Transport program. 66 DIST=2.NTCOST = LI. Travellers access the transit system through nontransit legs generated with two GENERATE statements.03 ONEWAY=T XN=4227 4006 4007 3963 3965 3966 NT LEG=1-4000 MODE=2 COST=1.TIME*3. EXCLUDE=(LW.96 DIST=0.39 ONEWAY=T XN=4268 4269 4270 4271 15687 8710 8709 4273 4315 4314 4316 4319 Cube Voyager Reference Guide 869 . resulting in poor quality routing. egress.NTCOST * 2.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.12 DIST=2. Example 1: Drive-walk nontransit legs Consider the routes from zone 1 to zone 11 in the network shown.Public Transport Program Using the Public Transport program 12 Example: PHASE=DATAPREP LINKLOOP if(link condition…) LW.NTCOST = LI.6 else LW.27 ONEWAY=T NT LEG=1-4263 MODE=2 COST=3.8 endif ENDLINKLOOP GENERATE COST=LW.66 ONEWAY=T XN=4268 4269 4270 4271 15687 8710 8709 4273 4274 NT LEG=1-4309 MODE=2 COST=2.39 DIST=3. However.03 DIST=2.DISTANCE * 1.66 ONEWAY=T XN=4005 4004 15646 4003 15647 3961 NT LEG=1-4143 MODE=2 COST=3.12 ONEWAY=T XN=4268 4269 4307 4306 4308 NT LEG=1-4322 MODE=2 COST=3. NT LEG=1-3967 MODE=2 COST=2.20 ONEWAY=T XN=4226 4267 4266 4265 4302 4303 4301 4144 4773 NT LEG=1-4227 MODE=1 COST=12. for modes 1 (walk) and 2 (drive).20 DIST=3.87 DIST=3.66 DIST=1.5. and transfer legs.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 network—access. misuse can generate unnecessary legs. generated by a GENERATE statement. the algorithm will not enumerate that route.40 DIST=3.36 DIST=0. The all-or-nothing process.” finds that 1->4276 is the best access leg to the public transport system for zone 11.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. Although a nontransit-only route. (Where transit alternatives are either not available or not feasible. Because travellers cannot cannot walk directly to 11 from 4276. they ride a transit line to 4278 and walk to 11 from there.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.) 870 Cube Voyager Reference Guide . NT LEG=4276-11 MODE=1 COST=3.12 Public Transport Program Using the Public Transport program NT LEG=1-4386 MODE=2 COST=3. which marks base times for the routeenumeration “spread. 1->4276->11 exists. the process will find no routes between the two zones.40 DIST=0.07 ONEWAY=T NT LEG=4278-11 MODE=1 COST=14. AM4L18 4325 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 30.8287 Probability=0. raising questions about the quality of the evaluated routes.Public Transport Program Using the Public Transport program 12 Because the program found a route.AM4L18 4280 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 30.0959 1 -> 4322 4322 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 19.3364 The fourth route in the list accesses and egresses the transit system at node 4276 and takes a transit line in between. You develop a nontransit network through an iterative process.83 Probability=0.AM4L89 4280 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 34. In this case. the program finds base times at nodes and enumerates and evaluates routes. Rather than being an algorithmic problem. remove the drive accesses and connect zone 1 to the transit system only with walk legs.AM4L89 Cost= 31. validating and refining the network produced by the GENERATE statements over a few cycles. Cube Voyager Reference Guide 871 .98 Probability=0.62 Probability=0. if you allow drive access from zone 1 to 4276.2803 1 -> 4322 4322 -> 4325 -> 4325 lines AM4L5 AM4L6. REval Route(s) from Origin 1 to Destination 11 1 -> 4322 4322 -> 4280 -> 4280 lines AM4L5 AM4L6.2803 1 -> 4276 4276 -> 4278 -> 11 lines AM4L12. A good nontransit network is essential for identifying good quality routes. even a nonsensical one. this arises due to the quality of the input data.0071 1 -> 4276 4276 -> 4280 -> 4280 lines AM4L12. Removing routes that access and egress the transit system at the same node would alleviate just one symptom rather than the underlying cause.42 Probability=0. Otherwise. then you should consider generating a drive-walk nontransit-only route between zones 1 and 11. Nontransit-only routes might be much faster than expected transit routes. Thus.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. 872 Cube Voyager Reference Guide . Thus the program will not connect zones by transit. for no apparent reason. the program will not enumerate the transit routes either. If the cost difference between the two is outside the range of the route-enumeration SPREAD. they have to be dealt with. and zones may appear unconnected when they are not. the last of which is the egress leg. and one or more pairs of transit leg bundles and nontransit legs. nontransit-only routes never get enumerated. Even when nontransit-only routes are not of interest. 68 DIST=0.16 ONEWAY=T NT LEG=81-1109 MODE=12 COST=1.20 DIST=0.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. Therefore.53 DIST=0. No drive-drive routes are generated. including a drive egress: NT LEG=1109-99 MODE=12 COST=1. NT LEG=81-1092 MODE=11 COST=19.47 ONEWAY=T VOL=430 VOLT=430 XN=1104 The transit time from 1109 to 1092 is just under a minute.41 DIST=0. The program generates several nontransit legs at 1109. the all-or-nothing process determines that the best stop to access line MAIN is 1109.65 ONEWAY=T XN=1108 1105 Cube Voyager Reference Guide 873 .40 ONEWAY=T XN=1094 NT LEG=81-1104 MODE=11 COST=7. TONODE=99 This statement generates short drive-only routes between zones that cost 5 units or less. Therefore. the route-enumeration and route-evaluation processes enumerate that route: REnum Route(s) from Origin 81 to Destination 99 81 -> 99 Cost=2. However. However.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. If you are not interested in nontransit-only routes. zones 81 and 99 will appear unconnected. NT LEG=81-99 MODE=14 COST=2. when validating a network. NTLEGMODE = 14. skims.19 REval Route(s) from Origin 81 to Destination 99 81 -> 99 Cost= 2. making any transit-based routes even less competitive. because the NT statement identifies the drive-only route.OFFPSPD. If.19 DIST=0. because this is a nontransit-only route neither the all-or-nothing process nor the enumeration process will enumerate the route. Further. FROMNODE=81.0000 874 Cube Voyager Reference Guide . the program will not enumerate the transit routes either. MAXCOST[1]=5. 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).19 Probability=1. COST=(li. then drive-only connections between zones should be generated: GENERATE. because the route is so much faster than any of the possible transit routes. nontransit-only routes are required. and loads. you can leave such zone pairs unconnected. however.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. However.DIST * 60) /li. you might establish why zone pairs do not connect. unless you define a very large route-enumeration SPREAD. the program only uses the drive-only route.19 Probability=1. Cube Voyager Reference Guide 875 .19 REval Route(s) from Origin 81 to Destination 99 81 -> 99 Cost= 2. the transit routes are much slower than the driveonly one. The route-evaluation process discards the other routes because they cannot compete with the drive-only route. Undetected. nontransit-only routes can result in poor quality routing as described in “Generating nontransit access and egress legs” on page 869. Although the program enumerates transit routes. and are only enumerated when SPREADFACT is 1.95 81 -> 1109 1109 -> 1107 -> 99 lines SMAIN Cost=59.0000 You must carefully consider how to model short.5.Public Transport Program Using the Public Transport program 12 In this example. REnum Route(s) from Origin 81 to Destination 99 81 -> 1109 1109 -> 569 -> 569 lines SMAIN 569 -> 1107 -> 99 lines SMAIN SMAIN Cost=58.61 81 -> 99 Cost=2. fast nontransitonly routes when there are transit alternatives. 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. 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. providing the basic infrastructure of zones. 876 Cube Voyager Reference Guide . Parameter TRANTIME provides the location of transit time in the link record.12 Public Transport Program Examples Examples This section contains examples showing different ways to run the Public Transport program. You can only code GENERATE statements in this phase. The script explicitly codes the DATAPREP phase. LIST=T. and loading analyses.TrnsTime PHASE=DATAPREP .WalkTime>0. MAXCOST[1]=16*20. You can save this network and for subsequent use by the Public Transport program for route enumeration. TONODE=26-4000 ENDPHASE ENDRUN Cube Voyager Reference Guide 877 . FROMNODE=26-4000.WalkTime>0 .NET .Prepare a Public Transport Network RUN PGM = PUBLIC TRANSPORT .generate access/egress links list='\nGenerate Zone Access/Egress Legs' GENERATE.Output files FILEO REPORTO = LDPRN00A.NET .Globals PARAMETERS TRANTIME = li. You can also display the network in Cube.Public Transport Program Examples 12 This script produces a public transport network.PTS FILEI FACTORI[1] =FACTORLD. loading.PRN FILEO NETO = LDNET00B.Input Files FILEI SYSTEMI = PTSYSTEM. COST=li. NTLEGMODE=33. skimming. containing validated input and the described generated components. NTLEGMODE = 34. MAXCOST[1]=16*15. . ONEWAY=F.LIN FILEI NETI = LDHWN00A. COST=li. INCLUDELINK = li.generate xfer non-transit legs list='\nGenerate Transfer Legs' GENERATE. route evaluation. LIST=T. INCLUDELINK = li.WalkTime.FAC FILEI LINEI[1] = ISL_PTLINES.WalkTime. The script uses three phases: • • NODEREAD reports the number.Prepare a Public Transport Network from TRIPS data RUN PGM = PUBLIC TRANSPORT . and transfer links.y ENDPHASE 878 Cube Voyager Reference Guide . The LINKREAD phase produces walk and transit time fields for each link. “transit” only.GLOBALS PARAMETERS TRANTIME = li. For links where only one activity can take place.NTL FILEO REPORTO =LDPRN00A. ni.Output files FILEO NETO =LDNET00B. and X. identified by link type. PHASE=NODEREAD print list=ni. that are “walk” only. ni. or “both” walk and transit.PTS . The generation process only includes links with a walk link-time greater than zero.and generate node variables Nw.TrnsTime . the other field contains a zero. DATAPREP produces some diagnostics and generates access.Input files FILEI LINEI[1] = \ISL_PTLINES.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. Can access network node variables N. TRIPS networks have links.NODEREAD phase loops over nodes.PRN .xxx. egress.FAC. • .n.NET FILEO NTLEGO = LDNTL00A.NET FILEI FACTORI[1] = FACTORLD.and Y-coordinates of all nodes in the input network. LIST=T FILEI SYSTEMI = PTSYSTEM. .x. You can input the TRIPS network directly into the Network program to prepare the base network. LINKREAD calculates walk and transit times for all links in the network.LIN FILEI NETI = LDHWN00A.xxx. 31.WalkTime(8.convert TRIPS distance and speed/time fields from 100dths to units lw.RSPDTIME) endif list =li. lw.29.TrnsTime(8.STFLAG ENDPHASE .29.30.2) li.TrnsTime = 0.LType == 10.LType == 18) lw. li.DISTANCE/100.this phase is used to generate walk and transit times for . lw.31.31.WalkTimePT = 0 if(li. li.WalkTimePT=lw.the links of a TRIPS Public Transport network . If no walk or transit links.28.32 are walk only lw.TrnsTime = lw.LType(3). .Public Transport Program Examples 12 .transit links. lw.RDIST/lw.ltype == 10.TrnsTime =(60.WalkTimePT = 60.RDIST=li.* lw.29.RDIST/4. li.RDIST/lw.RSPDTIME elseif(li.SPDTIME/100. or links with invalid .WalkTimePT(8.links with LT codes 10.28. walk only and both walk and .RSPDTIME elseif(li.2). PHASE=DATAPREP .LINKREAD phase loops over links.generate link variables Lw.B(9).18. li.xxx.32 && li.32) lw.time.2).xxx and .DISTANCE(8. lw.* lw.* lw. the run is aborted with a suitable message .0 && li.A(9).28.0 else lw.Count & report number of transit only.LType == 10.RSPDTIME endif if(lw.STFLAG == 'T') lw.32 && li.li.STFLAG == 'S') lw.STFLAG == 'S') lw.31. 28. Can access network link variables L.2).DATAPREP is the non-transit leg generation/input phase.WalkTimePT = 60. . PHASE=LINKREAD . endif if(li.29.RDIST(8.2).2).accessed and manipulated and non-transit legs are generated.TrnsTime(8.RSPDTIME=li.(This demonstrates the use of the command LINKLOOP which loops over links) WalkLnkCnt = 0 TrnsLnkCnt = 0 Cube Voyager Reference Guide 879 .Network and line variables can be .TrnsTime != 0. 0 && lw.12 Public Transport Program Examples BothLnkCnt = 0 ErrLnkCnt = 0 LINKLOOP if(lw. lw. ONEWAY=F.0 && lw. LIST=T. FROMNODE=26-4000. WalkLnkCnt.b.0) TrnsLnkCnt = TrnsLnkCnt+1 elseif(lw. li. NTLEGMODE = 33. BothLnkCnt. '\n' . MAXCOST[1]=16*20.WalkTimePT>0. MAXCOST[1]=16*15. COST=lw.Generate access/egress links list='\nGenerate Zone Access/Egress Legs ' GENERATE. '\nNumber of walk and transit links = '. LIST=T. NTLEGMODE = 34.Generate xfer non-transit legs list='\nGenerate Transfer Legs ' GENERATE.TrnsTime endif ENDLINKLOOP PRINT LIST = '\nNumber of walk only links = '. '\nNumber of transit only links = '.WalkTimePT.WalkTimePT. INCLUDELINK = lw.WalkTimePT == 0. TrnsLnkCnt.WalkTimePT > 0.TrnsTime > 0.TrnsTime == 0. TONODE=26-4000 ENDPHASE ENDRUN 880 Cube Voyager Reference Guide .Note if and 'if' statement does not fit on one line and closing 'endif' . COST=lw.0) BothLnkCnt = BothLnkCnt+1 else ErrLnkCnt = ErrLnkCnt+1 PRINT LIST = li. INCLUDELINK = lw.TrnsTime > 0.a.WalkTimePT > 0. lw.0 && lw.WalkTimePT.WalkTimePT>0 .0) WalkLnkCnt = WalkLnkCnt+1 elseif(lw.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 . Skim functions select the skims for extraction. DISTNTM. avg .MAT. perceived. TIMEATM. NAME = Compcost. which the script must explicitly code.transfer wait time.time for all modes. BRDINGSTM.Public Transport Program Examples 12 Public transport skimming This example extracts skim or level-of-service matrices. and saves them to the file indicated by MATO[1].PRN FILEO MATO[1] = LDMAT00E. DISTAM. IWAITA. IWAITP.value of choice MW[4]=IWAITA(0) MW[5]=XWAITA(0) MW[6]=IWAITP(0) MW[7]=XWAITP(0) MW[8]=TIMEA(0. .) The SKIMIJ phase selects skimming.RTE . TIMEPTM.NET . DISTTM. MO=2-9. A previously prepared public transport network is input with NETI.Input files FILEI NETI = LDNET00B. The ROUTEO file indicates that the script will enumerate routes.composite cost MW[3]=ValOfChoice(0) . TIMEPAM. avg .11-23. (Skimming automatically invokes the route-evaluation process. ValOfChoice. XFERPENAM. XFERPENTM. You must enumerate and evaluate routes before extracting skims. actual Cube Voyager Reference Guide 881 . actual.SKIMIJ loops over IJ pairs. TIMEAAM.) The optional MATO phases reports skims. XWAITP. evaluated and skimmed before this phase. reports them. you could input routes prepared in an earlier run with ROUTEI. TIMEPNTM. BRDINGSAM.ALLMODES) . DEC=22*2 FILEO ROUTEO[1] = LDRTE00B. (Alternatively. perceived. BESTJRNY. . XWAITA.Skim Route Attributes from a previously prepared Public Transport network RUN PGM=PUBLIC TRANSPORT . avg .initial wait time. actual.initial wait time.transfer wait time. PHASE=SKIMIJ MW[2]=COMPCOST(0) . BRDPENTM. avg . Skim are saved in working matrices. BRDPENAM.Output files FILEO REPORTO = LDPRN00A.Routes are enumerated. 7.avg MW[14]= BRDPEN(0. .2 FORM=10. BASE1=T. avg .walk/ride time for non-transit modes. TITLE='XWAITP'. avg .TMODES) avg MW[16]= XFERPENA(0.MATO loops over J for each I. TITLE='IWAITP'. avg MW[11]=TIMEP(0.NTMODES) modes.-35) .12 Public Transport Program Examples MW[9]=TIMEA(0.avg .TMODES) modes. .11) actual.in-vehicle distance for transit .2 882 Cube Voyager Reference Guide . BASE1=T. avg MW[17]= XFERPENP(0.time for all modes.walk/ride distance for non-transit . ALLMODES) actual.33.1.perceived. TITLE='XWAITA'.ALLMODES) MW[12]= TIMEP(0.11) perceived. FORM=10.ALLMODES) avg MW[22]= BRDINGS(0. . avg MW[21]= BRDINGS(0.8.TMODES) perceived. BASE1=T.-8.above. .ALLMODES) MW[19]= DIST(0. same as . avg .best travel time . MW[13]= TIMEP(0. > > > > 0) 0) 0) 0) PRINTROW PRINTROW PRINTROW PRINTROW mw=4 mw=5 mw=6 mw=7 TITLE='IWAITA'.boarding penalty for transit modes. FORM=10. avg . 1.in-vehicle time for transit modes.distance for all modes. BASE1=T.number of boardings for transit . All skims extracted above are reported PHASE=MATO if(ROWSUM(2) if(ROWSUM(3) FORM=10.TMODES) modes.number of boardings for all modes.transfer penalty for all modes. avg MW[23]=BESTJRNY ENDPHASE .boarding penalty for all modes. avg MW[20]= DIST(0. . BASE1=T.2 > 0) PRINTROW mw=3 TITLE='ValOfChoice'.ALLMODES) MW[15]= BRDPEN(0.2 FORM=10.2 FORM=10. .2 if(ROWSUM(4) if(ROWSUM(5) if(ROWSUM(6) if(ROWSUM(7) > 0) PRINTROW mw=2 TITLE='Compcost'.transfer penalty for transit modes. BASE1=T. MW[18]= DIST(0. .in-vehicle time for transit modes. perceived.7. 2 if(ROWSUM(22) FORM=10. TITLE='TIMEP NTMODES'. TITLE='TIMEP TMODES'.2 if(ROWSUM(15) FORM=10.2 if(ROWSUM(21) FORM=10. BASE1=T.2 if(ROWSUM(23) ENDPHASE ENDRUN > 0) PRINTROW mw=8 > 0) PRINTROW mw=9 TITLE='TIMEA ALLMODES'. TITLE='BRDINGS TMODES'. > 0) PRINTROW mw=18 > 0) PRINTROW mw=19 > 0) PRINTROW mw=20 TITLE='DIST ALLMODES'. TITLE='BRDPEN TMODES'. BASE1=T. BASE1=T. TITLE='DIST TMODES'. > 0) PRINTROW mw=21 > 0) PRINTROW mw=22 > 0) PRINTROW mw=23 TITLE='BRDINGS ALLMODES'. BASE1=T.2 if(ROWSUM(17) FORM=10. > 0) PRINTROW mw=11 > 0) PRINTROW mw=12 > 0) PRINTROW mw=13 TITLE='TIMEP ALLMODES'. BASE1=T. BASE1=T. FORM=10. BASE1=T. BASE1=T. TITLE='XFERPEN ALLMODES'. BASE1=T.2 if(ROWSUM(9) FORM=10. on to a previously prepared public transport network.2 if(ROWSUM(16) FORM=10.2 if(ROWSUM(19) FORM=10. BASE1=T. BASE1=T.2 if(ROWSUM(12) FORM=10. > 0) PRINTROW mw=14 > 0) PRINTROW mw=15 > 0) PRINTROW mw=16 > 0) PRINTROW mw=17 TITLE='BRDPEN ALLMODES'.2 if(ROWSUM(14) FORM=10. BASE1=T.2 Public transport loading This example loads a trip matrix. TITLE='BESTJRNY'. Cube Voyager Reference Guide 883 . BASE1=T.Public Transport Program Examples 12 if(ROWSUM(8) FORM=10.2 if(ROWSUM(20) FORM=10. BASE1=T.2 if(ROWSUM(13) FORM=10.2 if(ROWSUM(11) FORM=10. TITLE='TIMEA TMODES'. input with MATI[1].2 if(ROWSUM(18) FORM=10. TITLE='XFERPEN TMODES'. BASE1=T. TITLE='DIST NTMODES'. NET . you can input routes prepared in an earlier run with ROUTEI. (Loading automatically invokes the route-evaluation process.NET FILEO ROUTEO[1] =LDRTE00C. enumerates and evaluates routes.1. The ROUTEO file indicates that the script will enumerate routes. 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 . SORT=MODE.Globals this invokes Loading PARAMETERS TRIPSIJ[1] = MI. skims.12 Public Transport Program Examples You must enumerate and evaluate routes before loading trips. STOPSONLY=T. (Alternatively.) TRIPSIJ[1] indicates that loading is to be performed. LINEVOLS=T. SKIP0=T ENDRUN Public transport user classes This example prepares a public transport network.MAT FILEI NETI =LDNET00B.PRN . First.) The REPORT statement selects two loading reports—line summary and passenger loading.RTE FILEO REPORTO = LDPRN00B. Essentially. /*Load a previously built PT Network & Produce Loading Analyses Reports */ RUN PGM=PUBLIC TRANSPORT .1 . and loads for two user classes.Input files FILEI MATI[1] = OD.Output Files FILEO NETO = LDNET00C. this example performs the main functions of the Public Transport program for two user classes.Selection of Loading Reports REPORT LINES=T. Loading — Loads trip matrices input on any MATI file (not necessarily the one subscripted by the user class) to the evaluated routes.PTS FILEI FACTORI[2] =FACTORUS2. the script performs the following functions for each user class: • • • • Route enumeration — Saves routes on ROUTEO[1] and ROUTEO[2]. saves on MATO[1] and MATO[2].RTE FILEO ROUTEO[1] = LDRTE00A. Evaluate Routes.MAT FILEI MATI[1] = MSMAT00B. The script codes the MATO phase to report the output skim matrices.MAT FILEI SYSTEMI = PTSYSTEM. Finally.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. Enumerate. Next.FAC Cube Voyager Reference Guide 885 . a mandatory phase for public transport network development. and reports. .Generate Non-transit network. RUN PGM=PUBLIC TRANSPORT :Output Files FILEO REPORTO = LDPRN00A.FAC FILEI FACTORI[1] = FACTORUS1.NET :input FILEI MATI[2] = MSMAT00B. 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.RTE FILEO NETO = LDNET00E. Skim and Load for two User Classes. Route evaluation Skimming — Extracts composite and value-of-choice skims.PRN FILEO ROUTEO[2] = LDRTE00D. Routes are enumerated. FORM=10.WalkTime.TrnsTime USERCLASSES=1.NET . LIST=T. TONODE=26-4000 ENDPHASE ' . FORM=10. NTLEGMODE = 34.01. BASE1=T.1 TRIPSIJ[2] = Mi.composite cost MW[2]=ValOfChoice(0) . Skims are reported for each user class PHASE=MATO if(ROWSUM(1) > 0) PRINTROW mw=1 TITLE='Compcost'. INCLUDELINK = li. COST=li. MAXCOST[1]=16*20.2 TRIPSIJ[1] = Mi.WalkTime. ONEWAY=F.12 Public Transport Program Examples FILEI LINEI[1] = ISL_PTLINES.Globals PARAMETERS PARAMETERS PARAMETERS PARAMETERS TRANTIME=li.MATO loops over J for each I.WalkTime>0. MAXCOST[1]=16*15.WalkTime>0 . NTLEGMODE = 33.generate xfer non-transit legs list='\nGenerate Transfer Legs ' GENERATE.LIN FILEI NETI =LDHWN00A.1 PHASE=DATAPREP .generate access/egress links list='\nGenerate Zone Access/Egress Legs GENERATE. FROMNODE=26-4000. LIST=T. BASE1=T.SKIMIJ loops over IJ pairs.2 ENDPHASE 886 Cube Voyager Reference Guide .02. skimmed and loaded for each user class . Skims are saved in working matrices in this phase PHASE=SKIMIJ MW[1]=COMPCOST(0) .2 if(ROWSUM(2) > 0) PRINTROW mw=2 TITLE='ValOfChoice'. evaluated. COST=li.value of choice ENDPHASE . INCLUDELINK = li. 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 . 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 is an alternative to the Public Transport program for modeling public transit.13 TRNBUILD Program 13 TRNBUILD Program This chapter discusses the TRNBUILD program. Imported from TP+. Both terms have the same meaning. • Times and distances are only accurate to the second decimal place. code 1. For example. Use the MATRICES statement to define the total number of O/P matrices in the MATO file.235 as 124. TRNBUILD reports times in real units in the print file.TRNBUILD Program Using TRNBUILD in Cube Voyager 13 Using TRNBUILD in Cube Voyager Developed for TP+. TRNBUILD documentation refers to non-transit links as either support links or non-transit. TRNBUILD stores times and distances as 16-bit integers with an implied scale of 100 and a maximum value of 65. including the decimal point included.4. TRNBUILD supports a maximum of 255 modes. For example. To increase efficiency. TRNBUILD has some unique differences from other Cube Voyager programs.530. NOTE: This applies to script statements only. When coding TRNBUILD scripts. and stores a time of 1. Enter time and speed as true values. You can only use a limited number of variables or values in matrix calculations. TRNBUILD displays distances reported in the print file or any output files in hundredths of units. enter any distances in control statements in hundredths of distance units without any decimal point. • • Cube Voyager Reference Guide 891 . Expressions cannot reference the values from other matrices. with decimal points included) on the networks.4 minutes as 1. Important differences include: • • • TRNBUILD supports a maximum of 64 transit lines through the same common stop node. TRNBUILD stores a network distance 1.001 as 100.5 miles as 150. and code 1. NETI values are • real: Enter distances in true units (miles or kilometers. TRNBUILD outputs times in hundredths of units in LINKO and MATO. except for the LINESTRING report and the TRACE summary. 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 . and line combinations—a more complex process than path development for highway processing. Types of support links include walk. which modechoice models use (in a separate process). the program must consider mode transfers. Citilabs recommends that you set a standard for defining modes and use that standard consistently. The program requires a background highway network as the starting point for support links and lines. and basic information about distance and highway travel. the program uses support links to model people walking to. Lines are userdefined transit routes. and for driving from zones to transit. When developing paths for transit processing. A transit network contains lines and support links. Every support link and every transit line must have a mode number. but usually the program computes support-link travel times with a separate process. from. For transit lines that do not use separate guideways. such as buses. Support links—nontransit links that provide connectivity between different transit lines and between zone centroids and lines—are necessary to support the transit system. but more complex. Traditionally. and transfer. and between transit stop nodes. mode weighting. 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. park-and-ride. The program also uses paths to assign trips to the network. You must enter support links with control statements. the program must form a transit network and develop paths between zones.TRNBUILD Program Introduction to TRNBUILD 13 Introduction to TRNBUILD Transit processing is similar to highway-network processing. The program treats modes assigned to transit lines as transit modes and treats all other modes as support modes. During transit processing. the program computes the line’s speed as some function of the highway distances and speeds on the links used. The program uses paths to extract level-of-service (LOS) data. You may assign mode numbers as desired. The highway network provides the location of nodes. Support links can use the distances from any related highway links. TRNBUIILD has no predefined Cube Voyager Reference Guide 893 . Mode numbers can range from 1 to 255. you can also restrict the number of highway links that paths traverse. You might prefer to further stratify transit access by grouping some transit modes. This requires saving three modes for these access links. The program assigns modes globally. global values are not compatible with transit-network editing in Cube Base. The program can generate links from a zone. The program has a built-in process to generate zonal access support links automatically. With properly structured data. and to change the global setting before reading various line records. transit. You must initiate zonal access with the ZONEACCESS control statement. Citilabs recommends that you not use global values. However. Therefore. you can assign modes. or from a zone and to a zone. If the program uses a special highway network. and drive). you can easily change mode assignment. 894 Cube Voyager Reference Guide .13 TRNBUILD Program Introduction to TRNBUILD specifications of support links and their modes. For maximum flexibility. rather than from the zone to a stop node at the link’s B-node. The program generates a support link from the zone to each stop reached within the specified distance. You can vary the distance by mode. You can also provide access links that cause the program to develop the path from the zone to the link’s A-node. TRNBUILD allows you to assign a global value for modes. and can limit the number of links by mode. 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. to a zone. 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. When defining support links. Cube Voyager Reference Guide 895 . When building highway paths. PNR access development differs from zonal access development. Specifying the maximum-time parameter can reduce the path development time. Only the zones explicitly defined with the PNR node can access the node. the program must keep the best path into each node for each active mode at the node. Because there may be restrictions (usually mode oriented) out of the node. Transit path building has considerably more variables than traditional highway path building. the program considers the first node to be the PNR node.TRNBUILD Program Introduction to TRNBUILD 13 PNR control statements trigger a similar built-in process to generate drive-access support links. which is similar to highway path building. You cannot suppress this access development process if there are PNR control statements in the input. Saving the single best path will reduce path-development time by about sixty percent. this method may not obtain true minimum paths if there are mode-change factors or prohibitions. This requires considerable computer resources. If you code PNR node as a link. You can enter the generated links as either one.or two-way. The program will generate an access link from each specified zone that is within the specified distance of the PNR node. TRNBUILD allows you to invoke many factors at various points in the process. Path building The program builds transit paths using a special algorithm. The program develops the zone-toPNR-node link using a minimum-time path-development process. Though the algorithm can develop paths by saving just the single best path into a node. usually you will code drive-access links as one-way. Rather than simply developing the single best path between two zones. The PATHSTYLE parameter sets the alternate option (see “PARAMETERS” on page 928). These processes only use the links in the highway network. The algorithm determines the best path to each node. and then extracts individual zone-to-zone paths. the program develops a path set for an origin zone. and generates an additional lot link between the two nodes. the transit system likely offers some synchronization and the wait time may differ from the traditional wait time. transfers occur at any boarding other than a path’s initial boarding. The program applies these perceived factors based on modes. IWAITMAX. you can also set a minimum wait time. As the path moves from one segment to another. it can be zero. Before choosing a path segment. and transfers. you might invoke a maximum initial wait time. most travelers are somewhat knowledgeable about what time they can board the line. a 60minute line would normally have a 30-minute wait time. The program builds paths based on perceived times. Therefore. TRNBUILD also allows you to factor times on various segments of a trip. you might cap the wait time. the modes of the from. 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. However. Boardings occur when accessing a transit segment. During segment-to-segment processing. a line’s wait time is calculated as one-half of its headway. the program converts the actual time to perceived time based on the action considered. But when the line is the first in a trip. In most cases. creating perceived times that differ from actual times. For example. Similarly. depending upon the 896 Cube Voyager Reference Guide . To ensure that wait time accounts for boarding time. IWAITMIN. The program considers a segment to be either a support link or a contiguous portion of a transit line.and to-segments determine how the program processes the path. you input transit-line data in some period-specific basis. which may be inconsistent with the processed period. wait time. You can specify maximum and minimum wait times at transfer points with XWAITMAX and XWAITMIN. for transferring passengers.13 TRNBUILD Program Introduction to TRNBUILD Usually. you might include a line with a 90-minute headway in an analysis for a 60-minute period. Traditionally. segment connections have some associated perceived time. the program adds a value to the path time. The program obtains the added value from the XPEN and XPENFAC arrays. Because the program is not time specific. For example. the program assumes that any line is available at any of its stop nodes. With this option. You can prevent certain mode-to-mode combinations with NOX factor switches. if MULTIACCESS MAXTIMEDIFF=3. if zone I has four outbound links and zone J has four inbound links. During assignment. the program compares each of the I-J possibilities to the best path between the zones. the trace will show the various paths that would be used during assignment. the program might consider up to sixteen paths between I and J. considering all possibilities would take an inordinate amount of computer resources. The values are mode-to-mode specific. of the best I-J path. Note that the multiaccess process does Cube Voyager Reference Guide 897 . there are other reasonable possibilities. TRNBUILD has an option to calculate additional path sets based on the accesses at the zones. Those specifications define time differences. then the assignment program will use any I-J path that is within 3 minutes. If the to-segment is transit. Thus. However. or 10 percent. and include all modes. if an application traces paths. However. In basic mode. 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. The program uses all the selected paths in assignment. and considers only those that fall within the MULTIACCESS specifications. the program also multiplies the wait time by the XWAITFAC factor and possibly adds a boarding penalty. 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.TRNBUILD Program Introduction to TRNBUILD 13 segment modes (see “FACTOR” on page 905). For some zone combinations. Specify this option with a MULTIACCESS control statement. the program works with only the set of best paths between two zones (I-J). You can use the boarding penalty to add larger perceived values to the path time as the number of boardings increases. For example. The program considers the XPEN value to be an actual value. BOARDPEN. MAXPCTDIFF=10. The program computes the perceived segment time by multiplying the actual segment time by the segment’s MODEFAC factor. specified as both actual minutes and relative time. which is modified during path selection by the XPENFAC factor to obtain a perceived value. discouraging excessive transit boardings. 898 Cube Voyager Reference Guide . In many cases. the run times for the lines vary. the spread may be only between the access links. For example. if three outbound access links connect to the same line. so a method must be employed to compute a weight for each line’s run time. and dividing by two. 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. Select the best line. If there is another access link to another line. but there are scenarios where this could result in rather strange values. It would seem that the average run time could be used. A typical scenario would be at a station where there are numerous local lines (low headways) that run at slow speeds. The spread depends on the access links at a zone. based on the total time (sum of wait time and run time) between the two points on each line. that link might get a smaller share because the program spreads the trips across the four links. Save lines that have a total time within the mode’s COMBINE criteria.13 TRNBUILD Program Introduction to TRNBUILD not necessarily create a good spread for the assignment. TRNBUILD considers perceived times and completes the following steps: 1. and an occasional express line (high headway) that runs at a high speed. TRNBUILD’s line-combining process combines only lines with the same mode. 2. 3. Compute combined wait time by dividing the total number of vehicles available per hour into sixty minutes. 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. The multiaccess process increases path-building time because the process must build more paths. To illustrate the process. But.TRNBUILD Program Introduction to TRNBUILD 13 A new wait time is computed for each line by subtracting the best run time from the line’s total time. This value is restricted by the wait factors (IWAITMIN. These new wait times are used to compute an equivalent headway. which in turn. the process is reasonable in most situations. is used to compute an estimated combined wait time. 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. Each line’s run time is given a weight based upon the ratio of the estimated wait time to its new wait time. IWAITMAX. the actual link time or the actual waiting time to board). if there is a COMBINE IF expression which is satisfied for the line. Cube Voyager Reference Guide 899 . All other lines are then evaluated to determine if they should be combined with the best line. The total run time is weighted sum of all the line run times. Perceived value (P) — Compute by factoring actual value by an appropriate weighting factor Arun — Actual run time Await — Actual wait time (headway/2). 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. The line with the lowest Ptt is considered as the best line. XWAITMIN. define the following terms: • Actual value (A) — Determine directly from line links and frequencies (that is. or. A line will be combined with the best line if its Ptt does not exceed the sum of the B(Ptt) + MaxDiff. the program does not build path sets for origin zones without trips. If the assignment option is true.69 B 15 15 18.60 Not combined Perceived Path Values: Wait= 5.75 24.5 Line Freq Run Pwait Prun Ett RWait Wt Rtime A 10 22 12. The program accumulates link volumes and node boardings and exits. ( (60 / VehAvail / 2) * WAITFAC). The perceived path wait time is computed as one half the headway based upon vehicles available and factored by the appropriate wait factor. 900 Cube Voyager Reference Guide .60 47.392 4.90 .70 C 20 10 20.00 12.75 .291 7.70 D 60 23 20.75 18. but only processes the selected I-J pairs with trips.90 26. Each line is given a weight based upon its revised wait time relative to the other lines’ revised wait times. A revised perceived wait time for each line is computed as the difference between the line’s Ptt and the B(Prun). The perceived path run time is the sum of (weight * perceived run time) for all lines.00 32.13 TRNBUILD Program Introduction to TRNBUILD After the program obtains a list of the lines to be combined.45 Rtime= 18.09 Trip matrix processing TRNBUILD can assign trips from a trip matrix to the paths. This can reduce computation time considerably.40 38.00 36. When using a trip matrix. See “FILEI” on page 910. You can requests several types of reports showing assignment results. and MaxDiff = 10.00 27.00: IWAITMAX=8 IWAITMIN=2 MODEFAC=1. the program assigns trips to the appropriate I-J paths. Example: Assume the following conditions for an initial boarding between a node pair. the program generates the path set.2 IWAITFAC=2.00 . If there are any trips for any of the I-J pairs selected (explicitly or implicitly).317 5.00 20.50 26. it determines how the trips will be distributed among the lines. See also “FILEO” on page 912. the trace includes a list of its basic elements. However. Cube Voyager Reference Guide 901 . first and last transit nodes. boardings. access and first transit modes. In those segments. See also “MULTIACCESS” on page 927. See “FILEO” on page 912. an option lets you restrict the output to only stop-to-stop links (omitting the intermediate non-stop nodes). These elements include times. 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. distance. the extracted element is the sum of (line weight * network value) for all lines in the segment. The transit running times and distances may be not exact for the transit legs where the path is split amongst several lines. You can extract most elements by mode. If an assignment is made. If the program traces an I-J pair.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. or combinations of modes. and fares. the program writes the extracted values in matrix format to the specified file. You can combine elements with user expressions. and exits at each link’s nodes. If the you specify the FILEO MATO keyword. the file will contain link volumes. number-of-boardings. The program can write a DBF file containing the nodes and links. Output network This version of TRNBUILD does not write an explicit transit network. The TRNBUILD network will automatically include all the nodes in a transit line. the input network (designated on the FILEI statement) is opened. 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 . PHASE1 Level 2 statements: LINE. SUPPORT. At the first occurrence of any level 2 statement. If these rules are violated. and the program can’t adjust itself at that time. so that certain memory allocations can be made at the appropriate times. XY. The order of statements is not important except that the level 1 statements must be read before any level 2 statements. PNR. fatal messages may be issued. The following control words are available in the TRNBUILD module. LINK. SELECT. certain memory allocations (specifications obtained from PHASE1 statement values) are made.13 TRNBUILD Program Control statements Control statements TRNBUILD has several levels of control statements. Some statements must be input before other statements. and most level 1 statement values are no longer acceptable. ZONEACCESS All other statements can be input at any time. Level 1 statements: FILEI. There are exceptions. but the fatal messages can be avoided if the rules are adhered to. 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 . If the result is true. If the difference does not exceed the MAXDIFF value for the mode. If the difference exceeds MAXDIFF and there is no IF. IF selections result in either a true or false value. the lines will be combined. If the difference exceeds MAXDIFF. 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. and there is an IF selection for the mode.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. the line is deleted. The IF selection expression must be enclosed within (). the program looks first at the differences in total times (the line vs. See the description concerning combining lines for details of the combining process. But.” Then every other line is compared to the best line to determine if it should be considered in combination with the best line. it is possible that some travelers would use one line and others would use the other lines. if it is false. and which. In line choice situations the program determines which line (simply on its own merits) provides the best path and saves that as the “best. best line). the line will be combined with the best line. If the line’s total time does not exceed best time + MAXDIFF. There may be one MAXDIFF value and one IF selection for each mode (combining is possible only within the same transit mode). In such a cases the program must determine the allocation of users between the lines. the IF is evaluated. lines should be combined. At each boarding node the program examines all the stop nodes that are accessible via the lines that stop at the boarding node. the line is deleted from consideration at this node. the line will be combined with the best line. 904 Cube Voyager Reference Guide . If a downstream node is accessible on more than one line. To make this combination decision. first a decision must be made to see if. The COMBINE MAXDIFF and IF selections are used to help make that combining decision. 00 && (time . Example COMBINE MAXDIFF = 255*0 . Factor to convert initial wait time for a mode to perceived wait time.7002 && (((WAIT+RUN)–MINTIME) <=3.00) ). [2] is added to the second.25 ). Minimum actual initial wait time allowed. The value is in actual time and must be 0-60.25)) || (I=1-100.minwait) <= 2. 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. Value to be added to the path time at each node. mode factors.TRNBUILD Program Control statements 13 You may specify MAXDIFF and an IF for each mode. IWAITFAC IWAITMAX IWAITMIN MODEFAC NOX |KRV255*| |KRV255*| |KRV255*| |KRV255*| |K?V255[255]*| XPEN |KRV255[255]*| Cube Voyager Reference Guide 905 . Used to preclude a path from going directly between links which have certain modes. mode 1 (((WAIT+RUN)–MINTIME) <= 3. A true value is used to preclude the path. COMBINE IF[1]=( (N1=5000 && N2==6000-6010. .mintime) < 3) || (((WAIT+RUN)–MINTIME) <= 5. BOARDPEN[1] is added to the first boarding. There may be up to 15 values. modes 3-7 . but you must provide any IF selections. It is used primarily to discourage multiple boardings. no IFs for modes 8-10 FACTOR Wait. Factor to convert link time to perceived time.500 && (wait . etc. Default process. . The program provides a default MAXDIFF of 0 for each mode. xfer. mode 2 5 * ( (wait-minwait)<=2 && (run-minrun)<= 2) . Maximum actual initial wait time allowed. The value must be greater than 0 and less than 180. Maximum actual transfer wait time allowed. Factor to convert transfer wait time to perceived wait time. that node is ignored. for those keywords. and XWAITMIN to account for discrepancies in the general use of line frequencies when computing wait time at a node. If a explicit or implied value exceeds the highest stop node number. All these keywords are used to enter values into arrays where the index corresponds directly with the mode. The keywords with double dimensions (NOX. and the second index implies the to mode.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. Thus. Minimum actual transfer wait time allowed. Nodes where the most prior MAXWAITTIME value is to be applied. The English short name is MWT. XWAITMAX. Use IWAITMAX. If. IWAITMIN. the second index is assumed to be 1. This keyword may be specified more than once on a statement. The English short name is N. The purpose of this keyword is to specify transfer nodes where the line arrival/departure times are synchronized. a line may have a headway of 60 minutes. XPENFAC) are based upon mode-to-mode activity. MAXWAITTIME NODES |IPV| Use FACTORS to account for certain types of activity based upon either the mode of the link being entered. <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). and the average wait for the line would be 30 minutes. where the first index implies the from mode. 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 . only one index is specified. NODES=500-1000000 can be used to set all nodes. or upon the mode of the link being exited in combination with the mode of the link being entered. XPEN. Note that this value is not considered when calculating initial board time. For example. 901-903 . Example IWAITFAC=255*2. same as previous line FARE Fare values MODEFARE XFARE Cube Voyager Reference Guide 907 .n.. there may be shuttle busses running at every minute. so additional wait time would be required. Use IWAITMIN and XWAITMIN to effectively cause a wait time greater than the computed minimum to be used.. all initial wait factors are 2.00 5.3*6 . values. In a busy grid.5. NOX 12->12 and 12->15 XWAITMIN=10*0.5 MAXWAITTIME=5.n. In all likelihood.50 6. Use IWAITMAX and XWAITMAX to set somewhat tighter controls on that aspect. the transfer could not be made within the normal 30 second wait time.y .TRNBUILD Program Control statements 13 reasonable limit. NODES=800. beginning at mode 3: 4.5. NOX 11->1 and 11->4 NOX[12][12] = y. XWAITMAX=10*12.00 6..00 NOX[11]= y.. N=800.00 6.55 XWAITFAC=2.y . values separately from XWAIT. thus. you can set IWAIT.n.5. It is generally considered that a knowledgeable user will arrive at his first boarding node at a time that minimizes the wait time.0 . 901-903 MWT=5. At some nodes the east-west busses may arrive at the same time as the north-south busses.n.9*2.0 IWAITMIN[3]=4. 13 TRNBUILD Program Control statements FARE keywords Keyword MODEFARE |KIV255*| Description An array of fares based upon mode. The MODEFARE and MAXMODEFARE variables can be accessed via the MATRICES statement. Other users may wish to code non-transit links with a MODEFARE. Most likely. Because users code networks with different techniques and have different fare computation processes. The summary and maximum value variables may not be less than 0. 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). The array is dimensioned as 255 (from_mode) * 255 (to_mode). only the prior_transit to the boarding transit mode XFARE value is used. The XFARE and MAXXFARE variables can be accessed via the MATRICES statement. or transit boarding) is assessed a fare based upon the mode of the segment. and the highest XFARE is saved in the MAXXFARE variable. but that combination may be useful for certain networks. the XFARE values used are accumulated into the XFARE variable. Some users may wish to have an XFARE for all 255 x 255 possibilities. An array of transit fares that are to be assessed each time a transit segment is boarded. The array is used only when transit is boarded. XFARE |KIV255*255| The fares are all entered as signed integer units within the range of -32767 to 32767. each path segment (every non-transit link. During path extraction. These fares are accumulated for the path and stored in the MODEFARE variable. and there is no single way to compute fares. MODEFARE and XFARE would not be used in the same application. 908 Cube Voyager Reference Guide . and for subsequent boardings. The highest MODEFARE encountered for a path is stored in the MAXMODEFARE variable. During path extraction. 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). but not all values used. or greater than 65535. and not use XFARE at all. Any negative values are set to zero at the end of the path extraction. the non-transit to transit XFARE value is used. In that case. For the first boarding. consecutive non-transit links could cause a problem. TRNBUILD Program Control statements 13 Example FARE MODEFARE=3*50.0 . Suppose that the path from I-J splits between two lines: A and B. A total of all such fares is accumulated during I-J path tracing (done only when LOS matrices are being accumulated). The fare-link total can be either negative or positive. However.0. all fare links that are traversed are used in the accumulation. Fare links on multi-path segments of the path can cause strange results. During the trace and accumulation. XFARE[12] = 10*50. cause an additional fare to be added to the I-J mode-based fare. FARE MODES L ONEWAY Fare links are links. that when traversed in a path. FARELINKS Set fare links. there is no logical combination of the links other than full addition. At the end of the trace. sets transit fares for modes 1-10 XFARE[11] = 10*50. If line A has a fare link and line B does not. it will be reset to zero. then the fare from the fare link on line A will be factored according to the portion of Cube Voyager Reference Guide 909 . if the final total fare (mode-based + fare-link) value is negative.0. the fare-link total is added to the I-J fare accumulated in the normal fashion.4*75. the fare link might indicate a fare of 100 should be assessed. Links entered as A-B and B-A. ONEWAY |?| Example FARELINKS FARE=20 MODES=1-3. False — Default value. Use the keyword ONEWAY to specify if the links are entered only one way.510-511 MODES=15 . need not be transit FILEI Input data files 910 Cube Voyager Reference Guide .7 L=1000-1001. Thus. A-B. Code links as A-B.13 TRNBUILD Program Control statements the trips that would be assigned to line A between the points of divergence. MODES=9 FARELINKS FARE=25 L=500-510. Flag that indicates whether links are entered as A-B and B-A: • • True — Links entered in A-B direction only. 2000-2001 FARELINKS FARE=-10 L=8000-1010 ONEWAY=TRUE. but only a portion will be. Code the links directionally. Modes for which the specified links apply. FARELINKS keywords Keyword FARE MODES L |R| |IVP| |IVP| Description Fare assessed to the links on the statement. Each statement must specify at least one valid mode. Links specified as fare links. etc. ” which means that the fare is applied only in the direction of FromNode -> ToNode. 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). If there is an entry. ToNode. Direction is optional and has meaning only if it is a “1. The file record format is: FromNode. Fare. a search will be made to determine if Cube Voyager Reference Guide 911 . Otherwise (without Direction. or Direction != 1). 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.TRNBUILD Program Control statements 13 NETI MATI FAREMATI FILEI keywords Keyword NETI MATI FAREMATI |KF| |KF| |KFV255| Description Name of the input network file. a search is made for the boarding node to the exit node where the path changes mode. See “TRIPS” on page 945 for details. (FAREMATI[3]=filename will enter the data records from the file to be applied to mode 3. This statement will cause the program to read a file of stop-to-stop fares for the mode of the index of this keyword. In this example. the fare will be applied. Name of the input trips matrix file. the first search is node 100 (board mode 2) to node 103 (exit mode 2). a reverse fare entry is also made. Direction. If there is no entry.) The index should be a transit mode. . Different FAREMATI keywords may point to the same file.net -. FAREMATI[2] = myfare. The values can be obtained in the MATRICES MW statements: MW[] = faremat(modes.) Example FILEI NETI=?hwy. The following node-node combinations would be searched. If no valid combination is found. 101-102. The following combinations were be searched for mode 2: 100-103 100-102 and 102-103 100-101 and 101-103 100-101.system prefix = ALTA MATI = mytrip. r:\work\ALTA\vase. ? will be replaced by current system prefix. no fare assessed.13 TRNBUILD Program Control statements there are entries for any combinations of the modes 100-101-102103.fil . 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). referenced by TRIPS statement. and the next mode is processed.net .mat FILEO Output files MATO NETO (MODES STOPSONLY) – Currently Disabled! SUPPORTO (MODES FIXED ONEWAY) LINKO 912 Cube Voyager Reference Guide . NETI = r:\work\?\base. Mode mixing can not occur.net .. If a search combination is found the fare is assessed.) (0 is the total of the modes. in order to enter the same structure for different modes. Note that there will not be search for 103-308 because the path has a mode change between the segments. that would cover the entire string. Specify the format of the file with the FORMAT subkeyword. Frequency. It may be any length. Cube Voyager Reference Guide 913 . TotalBoardings. Specifies the format for writing LINEVOLO records.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. the program writes a record for each LINE containing the following fields: Name. LineDistance. Mode. Owner. If an assignment is undertaken and this file is specified. but will be truncated to 10 characters if FORMAT=T. T — Indicates fixed-length fields (default value). LINEVOLO FORMAT |S| ID that the program writes as the last field in the LINEVOLO records. LineTime. ID. PassengerMiles. PassengerHours. Possible values: • • • LINEVOLO ID |S| TXT CSV (or any word that begins with C) — Indicates comma separated values. BA_ values reference A and B in a true sense. 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. Plot. BA_BRDA references A for this link (not the A of the reverse link). [Volume. 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. If specified. program writes a record for each LINK containing the following fields: A. Distance. LINKVOLO |KF| Name of the text file where program writes link summary records. (Plot is either a 1 or a 0 to indicate this is the best record for this A-B to plot. 914 Cube Voyager Reference Guide . Owner. B. Mode. StopA. such as Cube Base. You can process this file with other software. StopB. Time. the XITA and BRDB values are not related to the VOL.) Specify the format of the file with the FORMAT subkeyword.] ID.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. Volume is not written if assignment is not in effect. 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. Name. If no modes are designated. Use the SUPPORTO keyword to write all the support links to a single file and in a consistent format. T — Indicates fixed-length fields (default). Use the subkeywords to reduce the number of links. The program writes a binary network of transit links. Name of the file where program writes support links in the format of the SUPPLINK control statement. Flag that indicates the types of transit links the program writes to the NETO file: • • True — Program writes transit links that connect stops only. this file (with all nontransit modes). False — Program writes transit links coded on the LINE control statements. SUPPORTO |KF| Cube Voyager Reference Guide 915 . along with the LINE file(s) and the input highway network constitute a complete transit network. Name of the file where program writes MATRICES. You might use this file to add additional coordinates in other software. the program includes all modes by default. Possible values: • • • LINKVOLO MATO NETO ID |S| |KF| |KF| TXT CSV (or any word that begins with C) — Indicates commaseparated values. This option is currently disabled. NETO NETO MODES STOPSONLY |IVP| |?| NODEO |KF| Name of a database file where program writes node records with coordinates. Modes included when writing links to the NETO file. Name of the file where the program writes transit network.TRNBUILD Program Control statements 13 FILEO keywords (continued) Keyword LINKVOLO Subkeyword FORMAT |S| Description Specifies the format for writing LINKVOLO records. Essentially. 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. After creating a valid support links file. such as the Cube Base. ID that the program writes as the last field in the LINKVOLO records. 5 ONEWAY=Y SUPPLINK N=3-7592 MODE=11 DIST= 133 SPEED= 2.5 . ID=ASSIGNB.5 SUPPLINK N=7-7688 MODE=11 DIST= 16 SPEED= 2. . FORMAT=CSV FILEO LINKVOLO=linkvol. . and flags one-way links as one-way. output link file FILEO MATO = ?los. FORMAT=text SUPPORTO = D:SUPPORT MODES=11-16 ONEWAY=N FIXED=Y Result: SUPPLINK N=1-7783 MODE=11 DIST= 30 SPEED= 2.dbf .txt.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.5 ONEWAY=Y SUPPLINK N=3-7592 MODE=11 DIST=133 SPEED=2.dbf . True — Indicates fixed-length fields.5 ONEWAY=Y SUPPLINK N=3-7593 MODE=11 DIST=20 SPEED=2. Flag that indicates how the program writes support links: • • SUPPORTO MODES |IVP| Support modes that program selects when writing to SUPPORTO file.5 ONEWAY=Y SUPPLINK N=7-7688 MODE=11 DIST=16 SPEED=2.5 . . but requiring more disk space. the program will issue a fatal message. providing easier browsing. output transit LOS values FILEO LINEVOLO=linevol. True — Indicates program writes each support link as A-B.5 ONEWAY=Y . 916 Cube Voyager Reference Guide .5 ONEWAY=Y . output node file FILEO LINKO = trnlink. Example FILEO NODEO = trnnode. If you designate no modes. SUPPORTO=D:SUPPORT MODES=11-16 ONEWAY=Y FIXED=N Result: SUPPLINK N=1-7783 MODE=11 DIST=30 SPEED=2. False — Indicates program writes truly two-way support links in low-high format.5 SUPPLINK N=3-7593 MODE=11 DIST= 20 SPEED= 2.csv. SUPPLINK N=1007-7689 MODE=11 DIST= 26 SPEED= 2. SUPPLINK N=1007-7689 MODE=11 DIST=26 SPEED=2.mat . ID=ASSIGNB. 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. FREQUENCYR |RV5*| Cube Voyager Reference Guide 917 .5 ONEWAY=Y . If you do not supply any FREQUENCYR values (from either global or statement keywords). • COLOR FREQUENCY |I| |RV5*| Color that Cube Base uses to display the line. or TRNBUILD will not include the line in this transit network. . Frequency for the line in the reverse direction. LINE Defines transit lines. There must be a FREQUENCY[n]. where n is the frequency period as defined by PARAMETERS FREQPERIOD. the program sets the entire FREQUENCYR array equal to the FREQUENCY array. Time between arrival of vehicles on this line (also called the headway). False — Program examines explicit node designations.TRNBUILD Program Control statements 13 SUPPLINK N=7593-3 MODE=11 DIST=20 SPEED=2. Duplicate line names will cause a fatal error. COLOR. FREQUENCY. CLEAR=Y. Mode for this line. the program sets initial values for many of the above variables from the line global area. When reading each line. but not save the line work parameters in the line global area. Citilabs recommends that you not use global values. The variables set in the line global area are: ONEWAY. ALLSTOPS. code: GLOBAL=N. but with the “-” character appended to it. XYSPEED. 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. MODE. Thus. then it is also included in the global area. The program truncates longer names and issues a warning. TIMEFAC. Therefore. Name of the line. it may not conflict with support modes used. It may be up to 12 characters in length. To clear the global values.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. you cannot use a hyphen as the last character in a line name. and must be unique. NOTE: If ONEWAY is false for the line. the program generates a reverse image line with the same name. NOTE: Global values are not compatible with transitnetwork editing in Cube Base. If FREQUENCYR is set in the LINE statement or in the input global area. MODE NAME |I| |S| 918 Cube Voyager Reference Guide . NODES NODES DELAY DELAY_C |R| |R| Additional time delay added to the link time. negative-numbered nodes are considered as stops. the program joins the last node of the previous node string and the first node of the current node string to form another link. NODES ACCESS |I| Restricts access at the previous node.TRNBUILD Program Control statements 13 LINE keywords (continued) Keyword NODES Subkeyword |IV| Description List of nodes that the line passes through. otherwise. or hyphens. Positivenumbered nodes are stop nodes. Cube Voyager Reference Guide 919 . However. until the program encounters another ACCESS_C or ACCESS subkeyword. Citilabs recommends coding the NODES keyword as the last keyword for the line. or one of the NODES subkeywords. the line may become useless. If NODES appears multiple times for the line. To simplify the coding in such cases. commas. too. Follow each node by another node. Two adjacent nodes—even if there are intervening subkeywords—form a transit link. If you insert any of the NODES subkeywords in the string of node numbers. until program encounters another DELAY_C or DELAY subkeyword. NODES ACCESS_C |I| Restricts access at the previous node and at the following nodes. you must re-enter the NODES keyword following the subkeyword value. NOTE: When applying ACCESS_C. you must make sure that the last node of a line has exit access (0 or 2). Possible values: • • • 0 — No restriction 1 — Boarding only 2 — Exit only This access restriction is inverted for the line’s reverse direction. if ALLSTOPS is true for the line. You may separate node numbers with spaces. Code DELAY between two nodes. Additional time delay added to all subsequent links. negative-numbered nodes are non-stopping nodes. you may use the word N as an alias for NODES. Resets the LINE TIMEFAC value from the current link until the program encounters another TF subkeyword. XYSPEED must be great than zero. until the program encounters another SPEED or TF subkeyword.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. If used. If there is an RT value after the last node and a RUNTIME value. Only specify SPEED within a node string. False — Program saves both the specified line and its reversed counterpart. the program makes subsequent adjustments from the node of prior adjustment. or there is an RT and a RUNTIME. NODES NODES NODES TF TIME XYSPD |R| |R| |R| 920 Cube Voyager Reference Guide . NODES SPEED |R| Sets the speed for all subsequent links in the line (from the input network or any LINK records). the program reflects RT values are reflected in the reverse direction. and adjusts all accumulated times to downstream nodes to account for the adjustment at the node. RT values on a line must be increasing. The program adjusts the accumulated time to the node to meet this value. RUNTIME prevails. Resets the LINE XYSPEED value from the prior node until the program encounters another XYSPD subkeyword. If there is more than one RT. If the line is not one-way. the program cannot compute operating characteristics for links that have a value of zero. but makes the adjustment relative to the end of the line in the reverse direction. Sets the operation time for the link surrounding this keyword. RUNTIME must be greater than the last RT. ONEWAY |?| Flag that indicates how the program saves a line: • • True — Program only saves the specified line. Indicates the speed along any subsequent links that are not in the input network and that are not in any LINK statements. use TF to modify this multiplier.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. The program uses the last value of TIMEFAC before NODES. and set global ONEWAY to true. If CLEAR is true (no matter where it is specified on the record). Rather than using RUNTIME. Both methods result in the same overall line time. clear the line global parameters. but both nodes of the link have valid coordinates (allowing the program to compute distances). if GLOBAL is true. the program saves the current line parameters in the line’s global area for use by subsequent lines. After reading a LINE statement without errors. After specifying NODES. or SPEED keyword. the program adjusts the time on all the links in the line so that the total of the line’s link times matches this value. XYSPEED |R| When reading a LINE statement. Speed for a line’s link if the link does not exist in the input network and does have a LINK statement. You must place TIMEFAC before NODES. TF. Set the line’s working parameters equal to the line’s global parameters. and set global ONEWAY to true. the program initializes LINE processing with the following steps: • • • If this is the first LINE statement. clear all global values. The program applies this multiplier until encountering another TIMEFAC. Citilabs recommends placing an RT value at the end of the NODES definition. If specified. TIMEFAC |R| Multiplier used to compute times along the line’s links that have base times determined from the input network or any LINK statements. NOTE: RT values will alter the way the program adjusts values. If all Cube Voyager Reference Guide 921 . The program can use a LINE statement with no NAME and no NODES to reset the line’s global area. but using RT is consistent with other adjustments. basic values N= 801-802-803 SPEED=23 N=804 805 -1805 806 807. . so produce an error Example LINE GLOBAL=y CLEAR=y MODE=3 ONEWAY=y TIMEFAC=1.2 . 922 Cube Voyager Reference Guide .15. setup global LINE NAME=abc FREQUENCY=5.905. the program resets FREQUENCYR to FREQUENCY after saving to global. DELAY=3 N=902. 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.5 NODES=804 805 806.5 ONEWAY=n. -901. set link time to X-Y distance/XYSPEED Else produce an error • Else the link can not be determined. 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).13 TRNBUILD Program Control statements FREQUENCYR values are zero.20. set link time to TIME If XYSPEED 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.1006 LINE NAME=with_times NODES=801 802 803 RT=21. and modes. speed. Flag that indicates whether the program saves link values into the link’s global area. DIST GLOBAL |I| |?| NODES ONEWAY |IVP| |?| Cube Voyager Reference Guide 923 . You may code any combination of modes that does not conflict with the used transit modes. The value must be 1-9. The global area contains time. See SPDCODE for more details. LANES MODES |I| |IVP| Number of directional lanes on the link. If GLOBAL is true. spdcode. lanes. the program uses all the specified modes.000. the program initializes link values from the link’s global area. Flag that indicates which links the program saves: • • True — Program saves A-B and B-A. Indicates the nodes that compose the link. False — Program only saves A-B. The value may not exceed 20. and then updates current values based on the statement’s keyword settings. the program updates the link’s global values from the current link values. See “Using TRNBUILD in Cube Voyager” on page 891 for notes about the use of GLOBAL. Applies no matter where CLEAR appears on the statement. Distance for the link.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 link’s global area to all zeroes before beginning any other statement processing. Specifies the modes for the link. usually considered as hundredths of miles. When reading the statement. oneway. or kilometers. If you code the keyword more than one time on the statement. Code the link as a pair of nodes separated by a dash. Because the program searches every link on a LINE statement. 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. If specified. in minutes. The value must be 0-999. If specified. Time.3015 ONEWAY=y MATRICES Output matrix definitions NAME MW[ ] 924 Cube Voyager Reference Guide . for the link. the program does not use any keywords associated with speed. the program can compute the link speed by using the internal SPDCAP table stored in the input NETI network. The program stores these links separately does not consider them to be part of the network. The SPDCAP is synonymous with SPDCLASS in the Network program. With speed and distance (DIST) determined. 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. SPEED |R| Speed for the link. Because the program stores these links with other data.13 TRNBUILD Program Control statements LINK keywords (continued) Keyword SPDCODE |I| Description SPDCODE for the link.5 LINK DIST=250 TIME=15. The value must be 1-99. the time for the link can be determined.5 NODES= 2003 . Example LINK GLOBAL=y CLEAR=y MODES=1-10 ONEWAY=n LINK NODES=1001-1002 DIST=100 SPEED=22. and a specified mode. Every link must have at least a distance. The value must be 0-999. If you specify SPDCODE and LANES. the program does not use SPDCODE and LANES for speed computations. searching for them can be inefficient. a time (or speed). TRNBUILD Program Control statements 13 MATRICES keywords Keyword NAME |SV| Description Name of extracted level-of-service matrix written to FILEO MATO. Cube Voyager Reference Guide 925 . Must be unique. There must be an odd number of arguments to the function. the first X. 100. or more. Ranges are not allowed. The program skims each I-J path to obtain certain values from the path. they are treated as numeric subtraction. arguments: the arguments indicate which modes are to be added to form the result. or equal to. For example: TIME(1. If the value is less than.3. Thus coding TIME (1-5) will be an error. TIME (5-1) will result in TIME(4).2. and 5. The primary purpose of this function is to extract distance or time based fares. or 300. ** Requires one. 926 Cube Voyager Reference Guide . 1001 (all transit modes). because the parser will treat that as TIME (-4).5) will return the sum of time for modes 1-3. Specifically. or 0 (same as 1000). MW[8] in the example below illustrates how to extract fares based upon distance.Y curve that is supplied in the function arguments. but it might have other uses.13 TRNBUILD Program Control statements MATRICES keywords (continued) Keyword MW |NV| Description Specifies an expression solved for a matrix row. 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. it may be 1000 (all modes). The mode 4 distance will be checked against the X. and the X values must be ascending. The result will be either 0. If a single argument is used. 200. which the expression may use. the argument is mode. The value most likely will be one of the above names with appropriate arguments. 150. The function will determine which X increment the value falls within and return the Y associated with the lower X. 1002 (all non-transit modes). *** 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. ) is valid and could also be coded as (dist(4)+dist(5). 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.01. MW[2] = TIME(1.4.8. mode of access MW[6] = NODE0(8).100.15). TOTAL_DIST.300). 100. . and any distance greater than 500 will result in 300.2.6. 200. MAXPCTDIFF |R| Cube Voyager Reference Guide 927 . .10).5. total walk time MW[4] = (IWAIT + TIME(0) + XWAIT(0) + XPEN) * 0.TRNBUILD Program Control statements 13 MATRICES keywords (continued) Keyword Description the result will be 0. 500. total transit time MW[3] = dist(11.9. TOTAL_TIME. NAME[6] = RAIL1. ACCESS.7..14. . first boarding rail station MW[7] = NODEL(8). or equal to.150. RAIL2 MULTIACCESS Multiaccess assignment keywords.13. MAXTIMEDIFF MAXPCTDIFF The presence of either of these keywords triggers the multiaccess process discussed in “Path building” on page 895. 300.5). TTIME_MIN. 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. Example MATRICES MW[1] = BOARDS. last alighting rail station MW[8] = STEPFUNC(DIST(4).. (dist(4. ..). the default is 1). .3.fare. 300 will result in a fare of 150. A boarding fare could be assessed by coding the first point as 0. . .. NAME = BOARDS. In the example. Each MW must have an index (if not specified.. total time MW[5] = NODEI. a distance greater than 200 but less than.200. any I-J path within 3 minutes of the best time will be included . False — Subsequent statements not listed to system printer file. False — Program skips the ILOOP and builds no paths. You can reduce computing time by precluded excessively long routes from examination. Program does not save paths that exceed this value. The value may not exceed 655. Because the pathbuilding routine processes many combinations of lines. LISTINPUT |K?| Insert this keyword to reduce volume printed by suppressing certain types of input. Program processes the ILOOP and builds paths.13 TRNBUILD Program Control statements Example MULTIACCESS MAXTIMEDIFF=3. Default is 1. The program issues a warning for lines with run times that exceed this value. paths with rather long times will be examined. MAXPCTDIFF=5 . 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. Flag that controls the printing of control statements: • • True — Subsequent statements listed to system printer file. MAXPATHTIME |KR| Perceived time limit for path selection. MAXRUNTIME |KR| 928 Cube Voyager Reference Guide . Default is 120. Maximum run time length. Process only uses the lines that contain a FREQUENCY[FREQPERIOD]. Specifies the processed period of the day. The value must be 1-5. due to transfer penalties. Flag that controls RUNTIME and RT values in LINE control statements: • • True — Default value. or restricted. but that cannot be guaranteed. this method can produce problems if certain modeto-mode combinations are precluded. unless you are processing relatively small network. and MAXPATHTIME is set rather low. Though useful for debugging. The value must be 2000-32767. Normally. this can take excessive time. 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.TRNBUILD Program Control statements 13 PARAMETERS keywords (continued) Keyword ONLINE |KI| Description Controls the listing of statements to the console during input reading. • SEQSIZE |KI| Number of cells used in the path-building sequencing table. False — Program ignores RUNTIME and RT values. set to a larger value to reduce the number of statements. Program implements RUNTIME and RT values. • 0 — Default value. With a value of 1. Changing the value might result in somewhat faster pathbuilding times. Selects paths by saving the best paths to every node for every mode that accesses the node. it should not be revised. However. Larger values result in more memory use (3 bytes per value). the program lists every statement. PATHSTYLE |KI| Path selection method used. For large input files. USERUNTIME |K?| Cube Voyager Reference Guide 929 . The value must be 0. even if the keyword is input prior to the reading the network. walk speed in kph USERUNTIME=n . and. You can input the values in any order. You may change the value dynamically. The program computes the value by dividing the sum of the link coordinate distances by the sum of the link distances. no paths greater than 3 hours WALKSPEED=4. the program writes a message for every zone. with a value of one. if they appear multiple times. The program uses for LINE and SUPPORT links when appropriate. Conversion factor for coordinate distance to network distance. you need not code the control word PARAMETERS. Example PARAMETERS MaxRunTime=120 . The program automatically sets this factor when it reads the input network. The keyword value takes precedence over the network-computed value. The program only applies this factor to those situations that follow the input of this keyword.1 .5. flag long lines MaxPathTime=180 .13 TRNBUILD Program Control statements PARAMETERS keywords (continued) Keyword WALKSPEED |KR| Description Speed used for walk links in the nontransit segment of the network. with a value of 10. the program only uses this value for links with a distance but no time. For example. the program uses the latest value. Larger values of ZONEMSG can reduce running times when running the system in console mode. XYFACTOR |KR| ZONEMSG |KI| The keywords on this statement are all “trigger” keys. for most of the keywords. Specify frequency as number of zones. Default value is 2.1-99. Default value is 1. This keyword is relevant only for those who start the system with RUNTPP. the program writes a message for every 10 zones. Because there is no specific walk mode. Frequency that the system writes zonal timing messages to the console. ignore LINE RUNTIME and RT values PHASE1 Initial parameters 930 Cube Voyager Reference Guide . 761. time = dist/speedtab(lanes.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. WORKRAM |KI| Cube Voyager Reference Guide 931 .xx minutes. if it is to have node numbers higher than the input network. LINKDUMP MAXNODE |KI| |KI| Specifies the number of links to be printed for inspection.000. End if The program maintains the time as an integer value. and if insufficient. But some situations may require a larger initial allocation. The value must be 10.000. the program terminates with a message indicating the need to restart with a larger allocation.000-500. When more initial allocation is needed. Highest node number in the transit network. In most situations. Default value is 300. Amount of RAM initially allocated to certain work areas. Else (HWYTIME not specified) if TIME is in the network time = TIME*100 else time = 0. the program tries to internally adjust it. The value must be larger than the highest node in the input network and less than 32. the default is adequate. assumed as xx.spdclass) else time = 0 Else if HWYTIME=SPEED time=distance/speed Else if HWYTIME=network variable time = variable * 100. The program uses the following logic to obtain each link’s time: If HWYTIME=SPDCLASS if LANES is in the network. Used primarily for debugging purposes. The method for obtaining the actual link time depends on the name of the variable specified. cost. the program updates global values from the current values. When reading the statement. If a potential link between a zone and a PNR node exceeds this value. oneway. If GLOBAL is true. Example MAXNODE=22000 HWYTIME=trantime . This is a general parameter. and then updates current values based on statement keywords. the program does not connect the zone to the node. The global area contains time. distfac. the program sets the values from the link global area. you need not code the control word. the program only uses the last value input. Maximum time for any generated zone-to-node links. 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. LOTMODE MAXTIME |I| |R| Mode assigned to the lot link.13 TRNBUILD Program Control statements The keywords on this statement are all “trigger” keys. and lotmode. The value must not conflict with any transit modes being used. you must input them early in the input stream. These keywords are valid only prior to the opening of the input network. increase highest node PHASE1 MAXNODE=2100 PNR Specifies park-and-ride link generation. Appropriate values might reduce path-building time in the PNR access-development phase. See “Using TRNBUILD in Cube Voyager” on page 891 for notes about the use of GLOBAL. 932 Cube Voyager Reference Guide . GLOBAL |?| Flag that indicates whether to set PNR values into the PNR global area. Therefore. Reset happens regardless of the location of CLEAR in the statement. PHASE1 need not be coded. mode. That process builds the best highwaytime path from each designated zone to this NODE using only links that exist in NETI. NODE is a transit stop node. the program cannot generate a path to it. or the entrance to a parking lot associated with a transit-stop node. In either case. and LOTMODE values. the first node should not be a transit stop node. The program will issue warning messages if the inputs violate these rules. 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. but if the first node does not have NETI connections.TRNBUILD Program Control statements 13 PNR keywords (continued) Keyword MODE |I| Description Mode assigned to the zone-to-node support link developed. and the second node should be. The value must not conflict with any transit modes being used. In the two-node option. Normally. The program internally maintains each zone-to-node link and each generated lot link as a support link. To accommodate the latter scenario. the NODE might not be a stop node. NODE |IVP| Cube Voyager Reference Guide 933 . the program generates an additional support (lot) link between the two nodes. Node to which the program generates an access link from each zone specified in ZONES via the PNR accessdevelopment process. append a second node to the first NODE value (NODE-NODE). The program obtains the lot-link parameters from the statement’s TIME. the nodes must exist in the highway network. simply having coordinates for the nodes will suffice for generating the lot link. at some locations. However. but merely a drop-off node. ONEWAY |?| Flag that indicates whether to configure generated (zoneto-node and lot) links as one-way. ONEWAY. 138-173 PNR node=9001-10001 ZONES=16-47. The program assigns the generated link’s mode from MODE and its time from the path. 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. establish general global values for subsequent PNR's PNR NODE=8001 ZONES=1-15. the program generates a SUPPLINK between the zone and the NODE. However. • TIME ZONES |R| |IVP| Time assigned to the lot link. the program automatically tries to generate PNR access links. the select array selects all zones for I or J. You can input these links directly via SUPPORT statements. you need not input PNR statements to enter PNR-access and lot links in the transit network.13 TRNBUILD Program Control statements PNR keywords (continued) Keyword SELECT |?| Description Flag that indicates whether to limit access-link generation. Example PNR MODE=12 LOTMODE=13 ONEWAY=Y MAXTIME=30 GLOBAL=Y . For zones that can reach the NODE within the MAXTIME. After reading any input PNR statements. The program builds a set of highway-time paths from each of the zones. False — Program generates access links for all zones.125. Zones that the PNR access development process connects to the NODE.358 REPORT Report requests CAPACITY LINES LINESTRING LINEVOL (LINESORT MODES STOPSONLY) LINKVOL (FULL MODES STOPSONLY) 934 Cube Voyager Reference Guide .48. rt. passenger distance. The program reports line strings in a three-column format: node accum_time accum_dist. The report lists each line along with a summary of the line’s boardings. Speed. to see all lines. Enter a mask comprised of characters. For example.in the mask. Volumes. Report fields include: Name. LINEVOL |?| Flag that indicates whether to produce line-volume report showing line boardings. and passenger hours. but large networks can generate a very large report if many lines are selected. The program selects the number of characters equal to the lesser of the length of the mask or the name. Cube Voyager Reference Guide 935 . Frequency. #. and *: • • • # indicates any digit ? indicates any character * forces a match. Dist. Boarding and XFER volumes. and exits resulting from trip assignment. time. Time. LINES |SV| LINESTRING |S| To include * or . String mask for lines included in the line-strings report. enter a single ?.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 network’s SPDCAP table. The line-node listing shows all the trip activity (Boards. enclose the mask within " ". etc. ?. enter A??3. The summaries depend on the assignment options. Mode. Exits) at each stop node. Indicate fields to sort on or specify “Order” to present report in original input order. volumes. Rows with empty nodes indicate an embedded parameter (speed.) The report prints the lines side-by-side to reduce print volume. To report lines that begin with the letter A and have a 3 in the fourth position. Sort order of transit-line summary report. False — Line-volume report includes all links. The report provides totals at each node and for the network. and line. False — Default value. Report only includes links with values unless you set FULL to true. and exits resulting from trip assignment. Flag that indicates whether to include all links—even zero-volume links—in the link-volume report: • • True — Include all links. • LINKVOL |?| Flag that indicates whether to produce link-volume report showing link volumes. 936 Cube Voyager Reference Guide . report includes all transit modes. the report does not consider intermediate nodes to be link nodes False — Link-volume report includes all links. If not specified. The program sorts the report by node. If the program does not accumulate boards and exits during assignment. report includes all transit modes. • NODEVOL |?| Flag that indicates whether to produce node-volume report showing boarding and exiting activity at nodes. Include only used links. the report does not consider intermediate nodes to be link nodes. mode. the program automatically sets this keyword to true. If not specified. LINKVOL FULL |?| LINKVOL LINKVOL MODES STOPSONLY |IP| |?| Transit modes included in link-volume report. boards. 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.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. 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. NOTE: Some reports can be quite voluminous. NOTE: The program always produces this report for lines with a run time that exceeds MAXRUNTIME. Cube Voyager Reference Guide 937 . LINESTRING=MU?## . STOPSONLY=n LINES= Name. False — Do not produce report.TRNBUILD Program Control statements 13 REPORT keywords (continued) Keyword NODEVOL RUNTIMEADJ Subkeyword MODES |IP| |?| Description Transit modes included in node-volume report. some reports will be incomplete. If not specified. The REPORT statement specifies which reports the program prints and suppresses. LINESORT=y. boards. If you restrict assignment (do not accumulate all volumes. or exits). Produce report. Example REPORT REPORT REPORT REPORT REPORT REPORT CAPACITY=n SPDCODE=y RUNTIMEADJ=y LINKVOL=y FULL=y .report all MUNI numbered lines NODEVOL=y MODES=1. SPEED |?| Flag that indicates whether to produce a report of the speeds stored in the input highway network’s SPDCAP table. Flag that indicates whether to produce report showing network time versus runtime for lines with a coded RUNTIME: • • True — Default value. LINEVOL=y.3-7.list all links in the network. Mode.10 SEGLIMITS Limits nontransit travel segments during path building (not during network construction). report includes all transit modes. Some reports are automatically suppressed if the program does not complete trip assignment. ORDER. No mode 212 link > 6 miles SELECT Zone and miscellaneous selection 938 Cube Voyager Reference Guide . For example. Example SEGLIMITS MODES=101. Any combination of mode 101 and mode 13 will be restricted to 22.5 . you might consider a walk time of 15 minutes to be acceptable. the path could use the links successively and generate a 30-minute walk segment. Modes that comprise the segment. the program generates two segment limits. While each link itself has an acceptable time or distance. This may be especially true for walk links. During path building.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.5 minutes SEGLIMITS MODES=212 MAXDIST=600 . A SEGLIMITS statement can preclude this from happening. and either a MAXDIST or MAXTIME limit. If the statement specifies both MAXTIME and MAXDIST. Each statement contains the restricting modes. If the network connects two 15-minute walk links. Maximum time (in minutes) allowed in a segment.13 MAXTIME=22. some paths may tend to use a successive series of nontransit links. the sum of successive link times may not be acceptable. You may specify up to 20 SEGLIMITS statements. Modes not included in path building. the program processes all I zones.and drive-mode outbound links. the program also lists LOS values following the path.55. For example. Specific zone-to-zone paths be reported. J=1-99. you can restrict path development to just one of those types by specifying the desired mode with ACCESSMODES. Use to specify which modes may be used for initial access.387 && BOARDS > 2) ) SELECT SKIPMODES=12 . If the program traces a path and statements request level-of-service matrices. If not specified.387 && BOARDS > 2) || (J=1-10 && I=50-75. J and BOARDS. IJ=( (i=1-5 & j=100-120) || (i=100-120 & j=1-5) ) SELECT ACCESSMODES=11-16.83.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. Destination zones to be processed. Specified values must be valid nontransit modes. origins and destinations specified in I and J). I J IJ |KIPV| |KIPV| |Ks| Origin zones to be processed. TRACE |Ks| Zone-to-zone paths to be reported. if the zone has both walk.512 SELECT TRACE=( (I=1-10 && J=50-75. The expression may include any combination of I. The expression may include any combination of I and J.37-50. SKIPMODES |KIPV| Example SELECT I=1-20. If not specified. Use to preclude a certain type of access. all zone connect modes compete Cube Voyager Reference Guide 939 . BOARDS is the number of transit boardings made during the path. the program processes all J zones. The program reports only processed I-J pairs (that is. Mode assigned to the link. 940 Cube Voyager Reference Guide . This statement is compatible with Cube Base transit line editing. This section lists the supported keywords. Citilabs recommends using this statement for single links rather than using SUPPORT. The value may not conflict with transit modes being used. Nodes of a support (nontransit) link. 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. ONEWAY |?| Speed used for computing the link time. False — Default value. Save the generated links as twoway links (a-b and b-a).13 TRNBUILD Program Control statements SUPPLINK Direct input of nontransit links. See “Logic for obtaining link distance” on page 944 for a description of the logic used to obtain the distance. SUPPLINK is a subset of SUPPORT. The link must have a valid distance. 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). N is an alternate form for this keyword. whereas SUPPORT is not totally compatible. SUPPLINK does not support some of the SUPPORT keywords. The program writes FILEO SUPPORTO records as SUPPLINK records. XYFAC |?| Flag that indicates whether to obtain link distances from coordinates if other methods fail: • True — Default value. False — Generate a fatal error if other distance-obtaining processes fail (that is. Example SUPPLINK MODE=13. N=21-22 DIST=300 SUPPLINK NODES=21-22 MODE=15 DIST=500 TIME=20 SUPPORT Direct input of nontransit links. SPEED=60. even if the link exists in the input network. the program sets link time to TIME rather than calculating link time from DISTANCE and SPEED. Compute link distances from the node coordinates if the other distance-obtaining processes fail.TRNBUILD Program Control statements 13 SUPPLINK keywords (continued) Keyword TIME XYALL |R| |?| Description Travel time for the link. otherwise use distance specified by SUPPLINK DIST. Flag that indicates whether to obtain link distances from coordinates: • • True — Compute link distances directly from the coordinates. See “Logic for obtaining link distance” on page 944. Determine distance from the input network if the links in the input NETI network. 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. Cube Voyager Reference Guide 941 . False — Default value. Occurs no matter where CLEAR appears on the statement. The global area contains DIST. LISTLINK. DIST GLOBAL |I| |?| Distance assigned to a link generated in a node string. NOTE: Global values are not compatible with transit-network editing in Cube Base. if the string generates only one link. Modes assigned to the generated links on this statement. CItilabs recommends that you not use global values. and XYFAC. ONEWAY. LISTLINK MODES |?| |IV| Flag that indicates whether to list all the generated links. Use primarily for debugging. 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. MODES. 942 Cube Voyager Reference Guide . XYALL.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. SPEED. Therefore. The values must not conflict with transit modes being used. False — The program retains values in the support global area. A node string terminates at the end of the SUPPORT statement or at the next keyword. See “Logic for obtaining link distance” on page 944.TRNBUILD Program Control statements 13 SUPPORT keywords (continued) Keyword NODES |IV| Description String of nodes (links) used as support (nontransit) links. 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. if you input 100 -101 -102 103 104. Within a node string. Save the generated links as twoway links (a-b and b-a). False — Default value. Cube Voyager Reference Guide 943 . and 102-103. the program generates a link from each positive node to the next positive node in the string. Speed used to compute the link times for all generated links. the program generates links 100-103 and 103-104. Input another node string with another NODES keyword. Each link in the string must have a valid distance. 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). 101-102. The program computes the distance and time for link 100-103 from links 100-101. Negative nodes indicate intermediate nodes that the program only uses for computing distance and time. For example. See “Logic for obtaining link distance” on page 944. then: If nodes have valid coordinates. • 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. False — Generate a fatal error if other distance-obtaining processes fail (that is. Generate link error End if 944 Cube Voyager Reference Guide . • Logic for obtaining link distance • • If DIST specified (or set in global area) and there is only one link in a string. even if the link does exist in the input network. if XYALL=F and the link is not in the input network and SUPPORT DIST is not defined). From A-B link in network 2. then set distance = DIST. compute distance from the coordinates Else generate link error • Else XYALL=N so the program computes the distance using the first successful method: 1. False — Default value. If XYFAC=Y. Else if XYALL=Y. otherwise use distance specified by SUPPORT DIST. From B-A link in network 3. compute distance from the coordinates 4.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. Determine distance from the input network if the links in the input NETI network. If the subkeyword is not coded. there is no zonal filtering.TRNBUILD Program Control statements 13 Example SUPPORT MODES=13. you must specify the desired matrix by number. For non–TP+ input files. 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. MI. You may specify the file name using two methods: • • MI. For either method.#.m — Program obtains file name from the one MATI file specified. m specifies the name or number of the processed matrix. Program obtains file name from the FILEI MATI[#] value. Cube Voyager Reference Guide 945 .m — Preferred method. SPEED=60. the program assigns trips to the network. 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. If the subkeyword ASSIGN is true. -300. You may specify support links. and only some lines in the segment use a selected link. the program sets the default values of its subkeywords to the same value as ASSIGN. BOARDS |?| EXITS |?| Flag that indicates whether to accumulate separate boarding volumes for each stop node. ASSIGN has several subkeywords: VOLUMES |?| Flag that indicates whether to accumulate link volumes during assignment. the program restricts assignment to trips assigned to those lines. 400. the program observes any settings of other subkeywords. If ASSIGN is set to false. When set to true. MATRIX ASSIGN (continued) Link nodes must be adjacent if on a line. OLINKS=200-400 would be invalid if LINE NODES is 100. the program does not process any trip matrix. The program does not check if the links exist before processing. When the program encounters the MATRIX keyword. Specify one or more required links as node pairs. But. because 200 does not connect directly to 400. Trip processing restricts paths to only those zonal pairs with actual trips. If a path segment consists of combined lines. 200. You cannot specify modes or lines. A trip must contain the specified links for the program to assign that trip. Flag that indicates whether to accumulate separate exit volumes for each stop node.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. Thus. OLINKS=200-300 would be valid. the program 946 Cube Voyager Reference Guide . OLINKS |IPV| Required links in a trip. Without a TRIPS control statement. program sets all its subkeywords to true by default. If ASSIGN is set to true. 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 sets the default values of ASSIGN and its subkeywords to false. If the program also encounters ASSIGN. TRNBUILD Program Control statements 13 ignores its subkeywords. The program generates a distance for the support link and computes the time from WALKSPEED. XFERGEN keywords Keyword MODE MAXDIST |I| |RV255| Description Mode assigned to the generated links. A typical statement might be: Cube Voyager Reference Guide 947 .MINUTP notation ASSIGN=Y. Maximum distance to search for a stop node for the mode.3. same XFERGEN Generate transfer support links. stop 200 services mode 3 and 6. Only set the values of ASSIGN subkeywords differently than the ASSIGN value if you have insufficient memory to accumulate all data at one time. If MAXDIST[3]=25 and MAXDIST[6]=50. MATRIX=MI.3. the program uses the last value.5100--5101 . The largest MAXDIST of any of the serviced nodes defines the limit for a connection. OLINKS=5000-5001. The keyword’s index [i] indicates the mode.EXITS=n matrix 1 from xxxx14. BOARDS=n. Example TRIPS TRIPS TRIPS TRIPS MATRIX=MI.5100-5101. ASSIGN=y.1. MODE MAXDIST Given this statement.1. The value must be a nontransit mode. Example: Suppose stop 100 services modes 1 and 3. the program generates support links of the specified modes using only NETI links.3.5101-5100 ASSIGN=Y. OLINKS=5000-5001. The program builds paths from each stop node to all other stop nodes within the specified distances. and the stops are 50 distance units apart. The program generates one support link for each connection. If you use multiple XFERGEN statements or repeat a MAXDIST keyword. if a path from stop 100 to stop 200 uses four NETI links. the program will connect these stops. MATRIX=MI.1. MATRIX=?14.DAT -.1 . the program generates one support link from 100 to 200. For example. allow longer walk to Mode 8 Use care when specifying MAXDIST. use a SUPPORTO statement to induce the program to write a file of SUPPLINK records. To examine the generated links.Same as above 948 Cube Voyager Reference Guide .327500 234123. Indicate the first node in the index and set the keyword value to pairs of commaseparated coordinates (X-coordinate. NODE NODE XY X Y |I| |I| |IV| Example XY NODE=137. The value must be between 1 and MAXNODE (or highest node in the network). Vector of coordinates for one or more nodes. The link paths will pass through centroids.327510 . XY Insert or revise coordinates NODE (X Y) XY XY keywords Keyword NODE Subkeyword |I| Description Node for which the statement defines coordinates. MAXDIST[8]=50 . Y=327510 XY XY[137]= 234123. MAXDIST=10*33. X=234123. The value must be 12147483647. if that is the best path between nodes. you could generate more links than TRNBUILD can handle. X=234123. NODE=138. The value must be 12147483647. X-coordinate for NODE. Y-coordinate for NODE. Ycoordinate). Use this keyword as alternate to the NODE keyword. uses spaces to separate additional pairs of coordinates.13 TRNBUILD Program Control statements XFERGEN MODE=11. Y=327500. The program automatically increments the node for additional coordinates. 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. In most cases. Because this list could be a rather. The value must be 1-30. Flag that indicates whether to list generated links as they are generated. 2 — Program generates links from node to zone (destination access) only. You only need to restrict the path builder if you developed the input network with a specific coding scheme that requires limited searching. but a reasonable value for MAXLINKS can also possibly reduce path-building time. 3 — Default value. Direction of all zonal-access links: • • • GENERATE LIST |?| 1 — Program generates links from zone to node (origin access) only. You can also use the FILEO SUPPORTO statement to write a file with these links. the list shows the zone. Cube Voyager Reference Guide 949 . node. Default value is 20. GENERATE MAXDIST |IV255*| Maximum distance of a zonal access link between a zone and an access node. Program generates both origin and destination links. Default value is 33. Citilabs recommends generating the list only with small networks. The value must be 0-500. MAXDIST will help to reduce path-building time. You may enter a distance for each transit mode. GENERATE MAXLINKS |I| Maximum number of links searched beyond the origin zone during zonal-access path building. and accessible modes at the node. time. or in conjunction with SELECT. distance. Useful for debugging. and gives them the appropriate distance. Use this statement to specify zonal-access generation and to specify special zonalaccess links. GENERATE MODE |I| Mode assigned to the generated links. Do not include any specified links in SUPPORT statements. The ZONEACCESS statement controls access development. You must code this keyword. The functions are independent: Even if the statement 950 Cube Voyager Reference Guide . defaults to the mode specified by GENERATE MODE. • False — Program processes all zones. The value may not conflict with transit modes being used. Default value is 5. The value must be 0-20. If DIST is not coded. • True — Program limits zonal-access link generation to the zones in the array specified with the SELECT control statement and I and J keywords. False — Default value. Specified links are two-way.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. mode. LINK |IV| Links accessed during zonal-access development. Mode assigned to the specified links. the array specifies all zones for I or J. NOTE: If the SELECT statement specifies no I or J. GENERATE SELECT |?| Flag that indicates whether to limit link generation to selected zones. The program adds the specified links as support links to the system. If not specified. and time. Flag that indicates direction of specified links: • • True — Specified links are one-way. program treats link’s distance as 0. Setting to true can possibly speed up zonal-access link generation. During access development. LINK LINK LINK DIST MODE ONEWAY |I| |I| |?| Distance assigned to all the specified links. the program builds minimum-distance paths from selected origin zones to transit stop nodes. the program ranks all accessible nodes (stop nodes and/or ZONEACCESS LINK A-nodes) by their distance from the zone.2. the program generates access links according to the restrictions of the MAXDIST and MAXSTOPS values.maxstops=1. To use the statement properly. (The program will not build a path further than the highest MAXDIST from the zone.7. Citilabs recommends using separate statements for each purpose. the statement will add specified zonal-access links to the network. nor will the path traverse more than MAXLINKS links from the zone to reach a node. it could be what you intend. violating this criteria is not an error. according to the value of DIRECTION. the program enters the generated access links SUPPLINK statements. However. the program treats each link’s A-node as an equivalent stop node to the transit modes that stop at the link’s B-node.MODE=14 dist=050 Cube Voyager Reference Guide 951 . Example ZONEACCESS generate=y.43-40.TRNBUILD Program Control statements 13 does not generate zonal access. During access generation. The program then generates a zonal-access link directly from the origin zone to the link’s A-node. Next. That is usually the case. the transit stop at the link’s B-node should be inaccessible to the access-path-building routine.3*4. Finally. The longest MAXDIST and the value of MAXLINKS restrict the access-generation path builder.8. when you use access links to isolate the mode-of-arrival at a node.10. maxdist=10*150 mode=11 ZONEACCESS link=43-22.6.) After completing the path building. txt . input transit trips FILEO NODEO = trnnode.LOS matrices are to be skimmed and written MATRICES NAME= TRANTIME.4.5.1.\.ODTRIPS.net . input highway network FILEI MATI = .use the speed/cap table in network for link speeds HWYTIME = SPDCLASS .. output node file FILEO LINKO = trnlink.. output transit LOS values . ----.read the transit route records from an external file READ FILE= .specify a matrix of trips to be used TRIPS MATRIX= MI. */ RUN PGM=TRNBUILD FILEI NETI = .10). ASSIGN= TRUE .request reports REPORT LINES=Name..generate zonal access links using the highway network .\dtown\troute. links as possible walk links ZONEACCESS GENERATE= TRUE MAXLINKS=4 MAXDIST= 255*100.\dtown\od. MW[1]=TIME(1.mat . ---..dbf .8. ----.dbf .3. MODE=100 . ----. MW[2]=DIST(4) . ----.9.6. LINESTRING='*' REPORT LINEVOL= Y LINESORT= Y LINKVOL= Y FULL= Y ENDRUN 952 Cube Voyager Reference Guide . ----.DIST4.request to see certain transit paths (must use transit links) TRACE=(I=1-5 && J=1-5 && BOARDS>0) .\.mat .\..\dtown\dtown.. It writes a transit DBF that can be viewed with Viper. It then builds paths and loads trips onto the transit links.2.13 TRNBUILD Program Example Example /* This step builds a transit network from the input files. ----. output link file FILEO MATO = trnlos.7. you can convert LINE records to TRNBUILD format. and preclude full processing. you can segregate the LINE data into separate files. LINE records are the largest part of the programs’ data. When TRNPTH encounters a TRNBUILD statement. Using TRNPTH. found in MINUTP. it closes any previously opened TRNBUILD files.TRNBUILD Program Converting from TRNPTH to TRNBUILD 13 Converting from TRNPTH to TRNBUILD TRNBUILD is a more robust transit processor than the TRNPTH program. To initiate conversion in TRNPTH. opens another file. TRNBUILD offers no translation capability. By judiciously using TRNBUILD statements. you need not run a complete TRNPTH job. and sets up the process to convert any LINE statements that follow the TRNBUILD statement. The format of the TRNPTH TRNBUILD statement is: TRNBUILD filename When converting TRNPTH files to TRNBUILD. Use STOP=1 to complete the conversion. some TRNPTH data does not convert directly to TRNBUILD. but the LINE structures are somewhat different. TRNPTH writes equivalent PNR statements to the file. If a TRNBUILD file remains open after processing all input. use a TRNBUILD statement. Cube Voyager Reference Guide 953 . However. 13 TRNBUILD Program Converting from TRNPTH to TRNBUILD 954 Cube Voyager Reference Guide . Cube Voyager Reference Guide Cube Voyager Reference Guide 955 . Topics include: • • • • UB2TPP TPP2UB SYNCHIMP Saturn conversion 956 Cube Voyager Reference Guide .14 Utilities 14 Utilities This chapter describes utilities. 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 . 958 Cube Voyager Reference Guide . Matrix) by “reading” the file in. Optional.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.1*UBAUTOCOEF endrun PARAMETERS Sets general parameters. MATO VARO Keyword MATO VARO |KF| |KF| Description Specifies the filename of the converted TP+/Cube Voyager binary matrix file.34567 UBAUTOCOEF=8.var mw[1]=mi. The MATO file must be specified even if HEADERONLY=T. 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 VARO file contains the variable information from the user benefit file header.mat read file=ubout. A sample of the VARO file is listed below: UBTRNCOEF=2. for example: run pgm=matrix filei mati=t10_36.14 Utilities UB2TPP FILEO Outputs data files. Specifies the filename of the user benefit VARO file.1. MATO Keyword MATO |KF| Description Specifies the filename of the converted binary user benefit file. MATI VARI Keyword MATI VARI |KF| |KF| Description Specifies the filename of the binary TP+/Cube Voyager matrix file to be converted. Cube Voyager Reference Guide 959 .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. Set static parameters. Specifies an optional variable file that contains the variable information for the user benefit file header. Specify output binary user benefit file. Control statement FILEI FILEO PARAMETERS Description Specify input TP+/Cube Voyager input file and the user benefit variable file. FILEI Inputs data files. The following control statements are available in the Cube Voyager TPP2UB utility program. FILEO Outputs data files. 14 Utilities TPP2UB PARAMETERS Set general parameters. The program must have values for all PARAMETERS. 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 . They may be coded directly with the PARAMETERS statement. Set static parameters. The following control statements are available in the Cube Voyager SYNCHMP utility program. Specifies the filename of the input SYNCHRO LAYOUT file. Control statement FILEI FILEO PARAMETERS Description Specify input SYNCHRO files. FILEI Inputs data files. Cube Voyager Reference Guide 961 .Utilities SYNCHIMP 14 SYNCHIMP Use the SYNCHMP utility program to convert SYNCHRO data to Cube Voyager intersection data format. LAYOUTI LANESI PHASINGI TIMINGI VOLUMEI FILEI keywords Keyword LANESI LAYOUTI |KF| |KF| Description Specifies the filename of the input SYNCHRO LANES file. Specify output Cube Voyager files. NOTE: Cube has a SYNCHRO data import wizard accessible from the Tools menu. PLANID VOLDATE VOLTIME 962 Cube Voyager Reference Guide .14 Utilities SYNCHIMP FILEI keywords (continued) Keyword PHASINGI TIMINGI VOLUMEI |KF| |KF| |KF| Description Specifies the filename of the input SYNCHRO PHASING file. NODEO LINKO JUNCDATAO Keyword JUNCDATAO LINKO NODEO |KF| |KF| |KF| Description Specifies the filename of the output intersection data file. The values of these parameters are stored in the associated SYNCHRO input CSV data files. PARAMETERS Sets general parameters. Specifies the filename of the input SYNCHRO TIMING file. Specifies the filename of the output node file. Specifies the filename of the input SYNCHRO VOLUME file. Specifies the filename of the output link file. FILEO Outputs data files. Cube Voyager Reference Guide 963 . Specifies the date value in the VOLUME file. Specifies the units of the LANES file.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. Valid values are meters or feet. Specifies the time value in the VOLUME file. The Cube installation program installs this program in the Cube directory (C:\Program Files\Citilabs\Cube\SaturnPath. The window contains two fields and several command buttons: • Input Saturn Path File — Enter the existing file containing the Saturn output. 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. 964 Cube Voyager Reference Guide . you will open the program window.exe in standard installations).14 Utilities Saturn conversion Saturn conversion The SaturnPath utility program converts output from the Saturn assignment program into a Cube Voyager path file. and number of nodes in path). with fields showing any parameter values that you did specify. 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 will prompt to overwrite the file. If the specified output file does not exist. too. class number. the program automatically starts converting the input file. 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. route number. the program will close automatically.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. the program automatically writes the output file. Show Saturn File Statistics — Click to show statistics about the Saturn file (number of paths. node number. flow. • • Close — Click to close the program window. If there are no errors during the conversion. otherwise. Cube Voyager Reference Guide 965 . Running from command line When called from a command line or batch file. If you do not specify all three parameters. the program window will open. minimum and maximum zone number. 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 node’s 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. Cube’s Application Manger flow chart view of your model provides a convenient tool for identifying the model steps in an application that can be distributed. Model step dependencies are easily visible from the data flows presented in the flow chart. An example is shown in the figure below. This is a fairly typical transit network development and skimming (level of service) process that might be present in many models. Transit network definitions and skim matrices are produced for two periods (peak and off peak travel) and for two separate modes of access (drive and walk only). Each of these steps is independent of each other. Assume that each of these steps run in approximately 9 to 11 minutes. This implies a 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 network’s throughput capacity so there may be little runtime benefit or take even longer when using DP on certain steps. Therefore, it is important to “tune” the DP setup to get the best performance. In general, DP works well for computation-intensive applications (for example, doing hundreds of matrix computations for each zone in a mode choice step) but will result in less time savings for disk intensive procedures (for example, combining 3 matrix files into one matrix file). Cube Cluster 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 user’s responsibility to check for sub-process completion before using output files generated by the sub-process. When a sub-process is done, it will create a file named {ProcessID}{Process#}.script.end. Use the 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 WAIT4FILES When a block of operations is distributed to another computer.15 Cube Cluster Control statements DISTRIBUTEMULTISTEP keywords Keyword PROCESSID |S| Description Prefix for the file names used to communicate with the sub-processes. a Pilot string variable can be used to set the ProcessID by putting it within @ characters (for example. The node switches its work directory to be the same as the main process before running the multistep (or intrastep) distributed process. then when a model run requests the node it will switch to the work directory for that particular model and run the steps. Defaults to null (working directory used). ProcessID=@MyID@). When it is done. it will go back and wait for further commands in the COMMPATH directory. It is the user’s responsibility to check for sub-process completion before using output files generated by the 988 Cube Voyager Reference Guide . Common path for checking for availability of processors. Single process number since the steps are distributed to one process only. ProcessNum=MyProcess). the node reverts to waiting for the communication file in the COMMPATH directory. a Pilot numeric variable can also be used to set the process number dynamically (for example. Nodes can be waiting in the COMMPATH directory. In addition to a single numeric constant. the main computer will continue running the script without waiting for the sub-process to finish. In addition to a string constant. The common path is only used for initial communication with the node. PROCESSNUM |I| COMMPATH |S| ENDDISTRIBUTEMULTISTEP Statement to end current MULTISTEP subprocess. This will work regardless of the location of the script file and the work directory of the main process. After completing the steps. the whole run will stop if a sub-process returns with a code 2 (fatal) or higher. it will create a {ProcessID}{Process#}. FILES CHECKRETURNCODE UPDATEVARS PRINTFILES DELDISTRIBFILES WAIT4FILES keywords Keyword CHECKRETURNCODE |?| Description Specifies if the return codes from the subprocesses should be checked. meaning to remove all temporary files.end file. The default is true. When true.end file to be created. Controls the disposition of the MDP temporary communication files. Use the Wait4Files command in the Pilot program to wait for the . When a sub-process is done.script.Cube Cluster Control statements 15 sub-process. DELDISTRIBFILES |?| Cube Voyager Reference Guide 989 . variable vname1. MERGESAVE means to merge the files but not delete them. Files=@MyFile@). For example.15 Cube Cluster Control statements WAIT4FILES keywords (continued) Keyword FILES |S| Description Specifies a list of all the files to wait for.Matrix. Highway Invoke intrastep distributed processing. PRINTFILES |S| UPDATEVARS |S| DISTRIBUTEINTRASTEP Programs: Matrix. PROCESSID PROCESSLIST MINGROUPSIZE SAVEPRN 990 Cube Voyager Reference Guide .” or “SAVE. 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.xname. Controls the disposition of the print files from the sub-processes.” “DELETE. for UpdateVars=vname.” MERGE means the print files will be merged back into the main print file then deleted. Currently only available in Matrix and Highway. Any variables with the first part of the name matching an UpdateVars name will be merged back.” “MERGESAVE. It can be “MERGE. will all be merged back to the main process.xnamevar etc. DELETE means no merge but delete them and SAVE means no merge but save them.Matrix. The default is SAVE.vnameabc. Specifies a list of global variables computed in Pilot and logged from individual programs that should be merged back from the subprocess run. If there are more sub-processes than there are zone groups of this size. MINGROUPSIZE |I| PROCESSID PROCESSLIST |S| |I| SAVEPRN |?| Cube Voyager Reference Guide 991 .10-20. For example. It is a list of numbers and put in as individual numbers or ranges (for example. Each sub-process must be assigned a unique process number. then some sub-processes will not be used. if there are 100 zones and MinGroupSize is 20 and ProcessList=1-10. List of sub-processes to use for DP.25).5. ProcessList=1. only 4 sub-processes will be used to process 20 zones each and the main process will process 20 zones itself.Cube Cluster Control statements 15 COMMPATH DISTRIBUTEINTRASTEP keywords Keyword COMMPATH |S| Description Common path for checking for availability of processors. Switch to control if the sub-process print files should be saved or not. Defaults to null (working directory used). The ProcessID is the prefix for the file names used to communicate with the sub-processes. Minimum distributed zone group size. 992 Cube Voyager Reference Guide . You can access this utility from Cube Base. to start multiple processing nodes on the local machine.15 Cube Cluster Utilities Utilities This section describes: • • Cluster executable Utility functions Cluster executable Use the cluster. choose Cluster Node Management to open the Cluster Node Management dialog box. found in the Cube program folder.exe utility program. From the Tools menu. 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. 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.bat batch file or from a Cube Voyager * command call.exe program in the Cube Voyager program directory and setting the script and working directory. Cube Voyager Reference Guide 993 . which are open and running on remote processing nodes. Typically. A Cube Cluster processing node corresponds to a single. 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).exe or the Cluster. you must physically go to each machine and run either the Voyager. or by running the Cluster. Alternatively. you can use the COMMPATH keyword to send information to active instances of Cube Voyager.exe program as described in “Cluster executable” on page 992. You can start an instance of Cube Voyager manually by running the Voyager. Therefore. and click List Nodes to return the status of any processing node (remote or local). Click Close Nodes to close any processing node (remote or local). You must start remote nodes directly on the remote machines. you can run the program from either a .Cube Cluster Utilities 15 In Time to Wait for Response. You cannot start instances of Cube Voyager on remote nodes over a network.exe program on that machine. You can also run this program from a Windows command line. properly configured instance of Cube Voyager running and waiting. enter the number of seconds Cube Cluster should wait for a response from a node before determining that the node is unavailable. 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. This can be use instead of the Wait4Files command if you only want to check if a node is done but don’t want to wait for it to get done. For example.. The second argument is a string with the list of process numbers to check.. NumReadyNodes('TestDist'.15-20') or NumReadyNodes(MyProcess. 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.'1-5. If none of the files exist. Citilabs recommends starting an instance of Cube Voyager on each remote processor that you will use. FirstReadyNode('TestDist'. and leaving them run. then the return value will be zero. you can use this value as the COMMPATH keyword value.15-20') • • 994 Cube Voyager Reference Guide . The node will switch its work directory to be the same as the main process before running the multistep distributed process. The second argument is a string with the list of process numbers to check. For example. After completing the steps.'ProcessList') — This function will check for availability of a list of Cube Cluster nodes.15 Cube Cluster Utilities You use COMMPATH only for initial communication with the node.10. The return value is the number of ready nodes.'ProcessList') — This function will check for availability of a list of Cube Cluster nodes and return the process number of the first available node.') — This function will check for the existence of one or more files. setting the work directory to a common path like z:\wait. The return value is the number of files that exist. NumReadyNodes('ProcessID'. Then. the result will be 6. the node reverts to waiting for the communication file in the COMMPATH directory.'1-5.10. they are put into one string and separated by '|'. The function takes one string argument (constant or variable) and if there are more than one file to check.MyProcessList) FirstReadyNode('ProcessID'. 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. 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.’1-10’) > NumReadyNodes(‘DP2’. the script wants to select the one with the most available nodes: IF (NumReadyNodes(‘DP1’. ProcessList=@MyProcessList@ Cube Voyager Reference Guide 995 .’11-20’)) MyProcessID=’DP1’ MyProcessList=’1-10’ ELSE MyProcessID=’DP2’ MyProcessList=’11-20’ ENDIF RUN PGM=Matrix DistributeIntraStep ProcessID=@MyProcessID@. 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. Topics include: • • • • Using Cube Avenue Control statements Theory Examples 998 Cube Voyager Reference Guide . an optional extension to Cube Voyager. Older traffic models tend to fall into two categories: • • Operational traffic models Planning models Operational traffic models. Cube Avenue shares the same PHASE structure but has additional commands and keywords to implement dynamic traffic assignment.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. For example. However. Cube Voyager Reference Guide 999 . However. random day-to-day variations differ from the way travellers learn by experimenting with different routes on different days.” Sufficient runs can provide measures of trip time reliability. which implements static traffic assignment. these models can show how signal offsets and synchronization can create a “green wave. Of course. are useful for modeling network component interactions as queues and delays vary during the model period. Microsimulation models also model day-to-day variation by using different random number “seeds. convergent trend into travel patterns.” or how long queues can disrupt traffic flows through upstream junctions (“blocking back”). Derived from the Cube Voyager Highway program. these models are not useful for forecasting routing (if they do so at all). introducing a systematic. most analysts only complete enough runs to obtain a representative sample and extract averages. such as Cube Dynasim (microsimulation) and SYNCHRO (signal optimization). Cube Avenue simulates the movement of vehicles through the network. Hybrid models. such as trips to work. But packets consume computer memory and processor cycles. to evaluate the costs generated by a set of routing decisions. like Cube Avenue. you will need to clean up the network and/or matrix before continuing. frequent trips. Bucket rounding the matrix before assigning it is probably the easiest way of cleaning a non-sparse demand matrix but. If there are any nodes or links where demand exceeds supply by a factor of two or more. Therefore a matrix with many small cells can cause lots of time and RAM to be wasted. If the matrix is large. Typical actions include checking that the matrix is for the right period and checking that the capacity coded in the network is correct. These models are sometimes described as macrosimulation models. • • 1000 Cube Voyager Reference Guide . Avoid small matrix cells. on the other hand. Every non-zero cell must generate packets. However. 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. The target packet size should be at least as big as the expected number of iterations. if you have enough local knowledge of the study area. finding “Wardrop User Equilibrium” solutions to the travel assignment problem. These models iterate on capacity restraints. a bigger value may be appropriate. Cube Avenue uses a path builder in a capacity-restraint loop to model drivers finding routes and modifying those routes based on experience.16 Cube Avenue Using Cube Avenue Planning models. Cube Avenue tries to find a middle ground between these two extremes. do capture how drivers’ experiences over long periods of time allow them to pick optimal travel strategies for regular. you may be able to clean the matrix better by hand. are known as mesosimulation models. for example.SPDCLASS. to model tidal flow lanes. you can vary the values of the C variable by time segment. is only available in this phase. With this command. DYNAMIC. Variables and input fields applicable to this phase include: • • • • • DISTANCE LINKCLASS LI. LI. 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. This functionality may be used. At present.LANES SPEED Cube Voyager Reference Guide 1001 . too.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. only C my be varied in this way. LINKREAD phase This phase behaves similarly in a Cube Avenue assignment to the corresponding phase in a Cube Voyager Highway assignment.CAPCLASS LI. future releases will allow you to vary STORAGE. The command. 16 Cube Avenue Using Cube Avenue • • • • C T0 T1 STORAGE DISTANCE If the user does not set this variable in script.SPDCLASS. free-flow time must be provided independently of speed for zero distance links. it will be initialized from LI. it defaults to zero. and the values in them are positive. Zero distance links are sometimes described as “dummy links. Failing that. LI. LI. as it does in any other highway assignment. 1002 Cube Voyager Reference Guide . In Cube Avenue. if that variable exists and has a non-negative value. Distance is usually measured in miles or in kilometers. and appropriate speed or capacity tables are defined in the network.Lanes. it defaults to one. in conjunction with Li. or in the script.” As in any network. they will be used. to look up base speed and capacity values. LinkClass functions as the index for functions TC and COST.LINKCLASS will be used if the variable exists and has a positive value. If the script does not set the variable. LI. Failing that. a link distance of zero may also cause STORAGE to default to zero (with disastrous consequences for the modeling).CAPCLASS If these field(s) exist.DISTANCE. LINKCLASS In Cube Avenue. and output speeds are not meaningful for them. Cube Avenue Using Cube Avenue 16 LI. if PARAMETERS CAPFAC has been coded.Lanes. which measures how many vehicles can occupy the link simultaneously. Note that this measures how quickly the link can discharge or accept vehicles. such as “NumberOfLanes.Lanes does. Finally. Speed is in distance units per hour. Note that. may be used as an index into speed or capacity tables. In Cube Avenue. Thus the defaulting behavior of SPEED is only significant if it is used to calculate a default for T0.Speed does not exist. a value of one will be used. This capacity differs from STORAGE.Lanes will be taken from the input network.” will not be recognized as the number of lanes.LANES may also take part in the default STORAGE calculations. or if they result in a negative value. Scripts can use the DYNAMIC command to specify that the value of C varies by time segment.Capacity is used as the default. but Li. Cube Voyager Reference Guide 1003 . If all defaults fail. the value in Li. that factor will be applied.Capacity does not exist but Li. the independent variable is TIME. C This is the flow capacity of the link.Lanes does. a value of zero will be applied (with disastrous consequences for Cube Avenue modeling). If the script does not explicitly set this variable. a speed table lookup will be attempted. LI. Speed will be initialized to zero. If there is no such field or if the value in the field is non-positive. in vehicles per model period. Li. a capacity table lookup will be attempted. If Li. SPEED If the user does not set this variable in script. If none of these values exists. then defaulting will be from Li.Speed if that exists. SPEED is a dependent variable. Note that the field name required in the input network is “LANES” and that fields with similar names. As in any highway assignment. If Li. during the modeling.LANES The variable Li. Time and Li. so long as vehicles leave the link as fast as new vehicles arrive. If a positive value still cannot be found.16 Cube Avenue Using Cube Avenue Essentially. If it still cannot find a value it will try to use 60*Speed/Distance. Thus every link has two capacities: the standard capacity. If the user script does not supply a positive value for STORAGE. Li. restrains flow while STORAGE restrains occupancy. the program will look in turn for Li. If all else fails. the program will try to extract a value from LI. C. Thus. 1004 Cube Voyager Reference Guide . If the user does not set a value in script.T0. a default of zero will be applied. TC.LANES*DISTANCE*vpd. It is used during application of the function. the number of vehicles on the link does not change. in minutes. However.STORAGE. It defaults to T0 unless the user explicitly sets the value in script. impassable). LI. Both queuing and moving vehicles on the link will use up storage. before any calculated times are available from an ADJUST phase. in that order. a zerocapacity link can delay packets forever. will be tried. T0 This is the free-flow time for the link. It is very common to accept this value. T1 This is the link time to be used on the first iteration of assignment. this value is the maximum frequency with which a vehicle can be discharged from or admitted to a link. STORAGE This is the number of vehicles that can fill the link. and hence. although there may be some merit to using observed times where these are available. the storage does not directly limit the flow on the link. where vpd denotes the value of PARAMETERS VEHPERDIST. If all else fails a value of zero will be applied (with the disastrous consequence that the link will always be full. Note that in Cube Avenue it is applied to every time segment.Time1. a PATHLOAD statement) evaluates an expression (usually involving matrices) to determine the number of trips. Thus for COMBINE=AVE.Cube Avenue Using Cube Avenue 16 Note that a link that has any spare storage will admit packets. if a packet arrives at a link with some storage available. ILOOP phase This phase is concerned with the creation of packets and the determination of routes. Note that on the second and subsequent iterations. but the packet’s volume exceeds the available storage. in which time segment) the packet arrives there. This script should contain one or more DYNAMICLOAD statements. builds paths according to some attribute minimization criterion. The user script associated with this phase is executed for each time segment. A dynamic load evaluates an expression (usually involving matrices) to determine the number of trips. (The link then becomes full. the network’s volume fields may only be updated later after calculating. they just have their volumes modified according to the factors generated by the COMBINE methodology in force. but it defers updating the volume fields until the adjust phase. for each point on the route. and it remains full until it has discharged sufficient vehicles to reduce the occupancy back below 100%. packets generated during earlier iterations are not discarded. The trips are placed into packets. it will still be admitted to the link. In particular. and then it loads the trips into the network’s volume fields. builds paths according to some attribute minimization criterion. However.) Thus the maximum number of vehicles that can be observed on a link may exceed that link’s storage slightly. and a route. when (that is. where each packet contains a start time. 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 . a volume in one or more volume fields. and within each time segment for every origin. A conventional load (that is. there is a queue of blocked packets waiting to get on each downstream link. or a packet becomes unblocked on a link. The event queue is sorted on the time at which the events are scheduled to occur. ADJUST phase This phase is executed when the movement of packets through the network is simulated. a packet arrives on a new link. or if the end of the model period has been reached. All the packets from all the iterations so far will be simulated during the current iteration’s ADJUST phase. it is verified whether link A will accept the packet (if not it joins link A’s queue) and an arrival event is scheduled for the next link on the path. 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. 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. As each event is processed more events are added to the queue.16 Cube Avenue Using Cube Avenue volume for old packets will be ({iteration number} – 1){previous volume}/{iteration number}. If not. During the simulation. The events from the event queue are processed in turn. when a packet is scheduled to arrive at a link A from link B. the script associated with the ADJUST phase is executed for the time segment that has just been completed. when T1 is used). Initially. 1006 Cube Voyager Reference Guide . In addition. At the end of the entire simulation. There are four kinds of event that can be stored in the event queue: a packet departs an origin. a “queue” of events is maintained. It is these aggregate values that are passed to the Converge phase. before the event processing is completed. Initially the event queue contains one event for each packet’s departure from that packet’s origin and all the link queues are empty. a check is made to see whether any packets can be released from link B’s queue. For example. some of the results are aggregated to obtain values relevant to the entire modeled period. a packet arrives at its destination. Cube Voyager Reference Guide 1007 .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. 1800 results in C taking the value 1800 during time segments 3 and 5. 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 . Keyword C |NV99| Description Defines link capacity by time segment. 1000. In Cube Avenue. Only use this command during the LINKREAD phase. For example: DYNAMIC C[3]=1800. 1000 during time segment 4 and its usual value during all other time segments.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. read from the input network variable li. DYNAMIC Changes the value of the capacity variable 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.CAPACITY or read from the internal speed/capacity table). Use the DYNAMIC statement to set segment-specific capacities. A link’s capacities by segment are initially set to the static capacities for all segments. link capacities are vectored by time segment. LANES2*3 where LANES1 and LANES2 contain the available lanes during the first two hours and the last hour. 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 . such as reversible lanes.CAP*li. or construction closures.Cube Avenue Control statements 16 This statement is useful for modeling time-dependent changes in link capacities. the closing of HOV facilities at specific times of day. For example. DYNAMICLOAD DYNAMICLOAD is the dynamic analog of the static PATHLOAD statement.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. respectively. 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. the opening of HOV facilities to general purpose uses at specific times of day.CAP*li. COST2. the path will be built to minimize the appropriate time varying function. and so forth. 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 . In the first two cases. list) NOACCESS=real This statement may only occur in PROCESS PHASE = ILOOP. expr. In the last case. If you enter a single value that contains one or more occurrences of __TS__. entering PATH=LW.Variables. For example. LW.” “COST. Several clauses of the DYNAMICLOAD statement require timesegmented lists as inputs (these lists contain one item per time segment).COST1. The DYNAMICLOAD PATH= clause may take. and so forth.16 Cube Avenue Control statements PENIFACTOR = value MW[n] = TRACE(real. Cube Avenue expands the value into a list by replacing the __TS__ with the integers representing the time segments. so only the differences are noted in this document. It may also contain one or more PATHLOAD statements. such as 1.” or a list of input link attributes (that is. Most of the clauses have the same syntax and meaning as the corresponding clauses of the PATHLOAD statement. LW.COST__TS__ is equivalent to entering PATH=LW. one per time segment). 2. 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. Variables or LW. A dynamic traffic assignment must include a “PARAMETERS MODELPERIOD= SEGMENTS=” clause and at least one DYNAMICLOAD statement. A static assignment script must contain one or more PATHLOAD statements but may not contain a “PARAMETERS MODELPERIOD= SEGMENTS=” clause nor a DYNAMICLOAD statement. “TIME. as its value. in which case simultaneous dynamic and static loadings will occur. LI. 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. Furthermore.COST3. When the ILOOP is executed for time segment n. expression. 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. the nth element of the list will be the one that is evaluated. 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. false. then the demand is 30 vph and 7½ vehicles will depart the origin during the time segment. 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. You can use the macro expansion of _TX to abbreviate the list of link variables. The DYNAMICLOAD PACKETSIZE = clause specifies the target number of vehicles per packet. If necessary. The DYNAMICLOAD DEMANDISHOURLY = clause is. Instead actual loading is deferred until the simulation runs in the PROCESS PHASE=ADJUST. The DYNAMICLOAD VOL[n] = clause is similar to the PATHLOAD VOL[n] = clause. penalty) Cube Voyager Reference Guide 1011 . The paths will be assigned routes based on their departure time and their expectations of travel time and disutility. However.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. If DEMANDISHOURLY. Otherwise thirty vehicles depart the origin during the time segment. no change to the volume field values occurs during PROCESS PHASE=ILOOP. suppose that there is a segment of 15 minutes. such as VOL[1]=MW[__TS__+3]. The value must take the form: TRACE(time. by default. giving a departure rate of 120 vph. At least one packet will be generated for any IJ pair that has a positive demand. The DYNAMICLOAD MW clause specifies skims. The entered value must be a list of expressions with one entry per time segment. You can use __TS__ to abbreviate the list. and the corresponding expression in a DYNAMICLOAD VOL[n] = clause evaluates to thirty. For example. 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 may be more than one. it will be evaluated as a dynamic expression that varies by time segment. If the expression contains the string __TS__. Negative values indicate that the start time is in the 'warm up' period. • 1012 Cube Voyager Reference Guide . specified in minutes since the beginning of the model period. A static assignment process is what users should be familiar with as the typical assignment process. It indicates that the skim should be for vehicles departing their origins at the specified start time. to skim the value of the DYNAMIC PATH clause. • • You can use the special expression. There must be at least one instance of PATHLOAD in phase ILOOP. There are two classes of assignment process now supported in Cube Voyager: Static and Dynamic. If using Cube Avenue to perform dynamic traffic assignment. expression is the expression evaluated and summed for each link on the route. Case 1: Static assignment • There are no instances of “PARAMETERS MODELPERIOD= SEGMENTS=” in the entire script [this setting is the key that switches modes].16 Cube Avenue Control statements where: • time is the start time. In Cube Voyager a static assignment process contains no dynamic elements. A few rules apply to these two cases when using Cube Avenue as described below. the assignment process will include dynamic elements but may also include static elements. penalty is an optional list of turn penalty sets to include in the skim. PATHCOST. There may not be any instances of DYNAMICLOAD. There may be instances of PATHLOAD in phase ILOOP. If there are any instances of PATHLOAD. During this execution of phase ILOOP. an additional execution of PHASE ILOOP occurs prior to any of the executions described above. Case 2: Dynamic assignment • • • • • • There is exactly one instance of “PARAMETERS MODELPERIOD= SEGMENTS =. There is a single “static” time segment and it runs same as the Highway program has always run. packets created.” There must be at least one instance DYNAMICLOAD in phase ILOOP. no DYNAMICLOAD statements are executed but PATHLOAD statements are. a single item from the list of matrix expressions in each DYNAMICLOAD statement is evaluated (and paths built. No PATHLOAD statements are executed during any of these executions of phase ILOOP. During each of these executions of ILOOP.Cube Avenue Control statements 16 • • • • There may not be any instance of PATHLOAD outside 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.). 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). etc. There may not be any instance of PATHLOAD outside phase ILOOP. • Cube Voyager Reference Guide 1013 . there may be more than one. No variables are vectorized by segment and all apply to the model period as a whole. There may not be any instances of DYNAMICLOAD outside of phase ILOOP. 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. a fatal error will be generated. If there are any PATHLOAD statements in phase ILOOP. Some users have keys implemented in their application scripts to turn on or off the 1014 Cube Voyager Reference Guide . 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. These aggregate results are used for the calculation of convergence statistics. aggregate values applying to the model period are calculated from the results individual time segments. If a DYNAMICLOAD PATHO=T control is found in the ILOOP PHASE. Note that none of the discussion above depends on the ordering of PATHLOAD and DYNAMICLOAD statements. FILEO Highway program output files are not supported under FILEO if running a dynamic assignment process under AVENUE. It is their presence or absence from the ILOOP PHASE of the script (as a whole) that is significant.16 Cube Avenue Control statements • Phase ADJUST is executed for each time segment. then these values (except for the volumes) will be carried forward to the “static” execution of phase ILOOP during the next iteration. NOTE: Writing a packet log requires computer resources: processor time. 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. PACKETLOG AFTERITER |I| Iteration number when Cube Avenue begins writing packet log. you can filter displayed packets with Cube graphics. for every iteration). with all the information in the file. The file is likely to be very large. By default. By reducing required resources. if you know that Cube Avenue will require at least m iterations. overwriting the same file and ensuring that a valid packet log exists upon completion of a successful Cube Avenue run. PACKETLOG ARRIVALTIME |RPV| List of time intervals. even leading failed runs to succeed. RAM. It lists every packet. you can set AFTERITER to m-1 to save some run time by not writing the file during the first few iterations. Cube Avenue writes the packet log for each simulation run (that is. Packet log only includes packets that arrive at their destinations during the listed time intervals. The difference between these two times is the time that the packet spent queueing. However. you can improve run times.Cube Avenue Control statements 16 generation of the PATHO file. Specify each interval as an ascending pair of real numbers—minutes since the start of the model period. Specified as FILEO PACKETLOG=filename. Cube Voyager Reference Guide 1015 . giving the associated volume and route. Additional options on the FILEO PACKETLOG statement can reduce the number of packets included in the packet log and thus reduce the required resources. FILEO keywords Keyword PACKETLOG Subkeyword |F| Description Produces the dynamic equivalent to the static path file. However. It also gives the times (in hours since the start of the model period) each packet arrives and departs from each node. and disk space. List of destination nodes. List of links. log includes packets from all origins. the packet log does not restrict packets based on links traveled. PACKETLOG DESTINATION |IV| PACKETLOG FORMAT |S| PACKETLOG MUSTMEETALL |?| • The default value is true. defined in previously executed ADDTOGROUP commands. the PACKETLOG is a text file. PACKETLOG SELECTGROUP |IV| PACKETLOG SELECTLINK |IPV| 1016 Cube Voyager Reference Guide . Along with SELECTLINK. Either BIN or TXT. log includes packets to all destinations. Specify each interval as an ascending pair of real numbers—minutes since the start of the model period. 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. List of link groups. Packet log only lists packets starting at the listed origins. which you can display in Cube graphics or postprocess with a user-defined program. Along with SELECTGROUP. such as a matrix record-processing script. Packet log only list packets ending at the listed destinations.16 Cube Avenue Control statements FILEO keywords (continued) Keyword PACKETLOG Subkeyword DEPARTTIME |RPV| Description List of time intervals. defines a set of links that packets must pass through for inclusion in the packet log. SELECTGROUP. but binary files are about 60% smaller. By default. based on value of MUSTMEETALL. and MUSTMEETALL) is listed. PACKETLOG ORIGIN |IV| List of origin nodes. False — Link set defines a special area: the packet log lists any packet that passes at least one link in the set. NOTE: If none of these keywords (SELECTLINK. Binary format is only suitable for display in Cube graphics. based on the value of MUSTMEETALL. Packet log only includes packets that depart their origins during the listed time intervals. defines a set of links that packets must pass through for inclusion in the packet log. By default. By default. TIMESt_1 stores the amount of time that the vehicles spent traversing the link segment (averaged over all such vehicles). TIME_1 is similar. 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. 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. VfSMP_1. 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. It does not take turn penalties or junction modelling into account. Cube Voyager Reference Guide 1017 . SPEEDSt_1 and SPEED_1 This field contains the ratio between distance and the time (as defined above).Cube Avenue Control statements 16 Output data Cube Avenue produces additional output data over that produced by the Highway program. 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. etc. the values in the volume fields should correspond to the appropriate matrix row totals. VSt_1 is the result of applying the V function to V1St_1. it will be “blocked. links and turns in the network are associated with capacities and capacity bottlenecks may delay packets to ensure that these capacities are not exceeded. At origin zone centroid connectors. but this is just a convention indicating that data has not been collected for these links. VITSt_1 The number of vehicles on each downstream link at the end of time segment. if the packet tries to move onto a full link. excluding any “warm up” segments). VSt_1 and VSMP_1 The volume of traffic entering the link.” and it will queue until space becomes available on the next link. V2St_1. Packets of vehicles can be made to queue by either of two mechanisms. QUEUEVSt_1 This measures the average number of vehicles queuing on the link during time segment t. during time segment. the field value will be zero. The value is found by summing across all packets of vehicles that are flowing or queuing on the link. At origin zone centroid connectors. First. t. is recorded in this field. but are not recorded as “blocked. in volume field f. If there is very low demand for travel on the link. VfSMP_1. a link that is full of traffic may block further vehicles from entering. the vehicles affected queue while waiting to proceed.” 1018 Cube Voyager Reference Guide . Second. At the other extreme. links other than origin zone centroid connectors). The values in the fields labelled with “MP” instead of a time segment number contain aggregate values for the “model period” (that is. t. Note there are two very different situations that can result in low volumes entering downstream links (that is. the flow will be low because the link is empty.16 Cube Avenue Control statements VfSt_1. The value will always be less than or equal to the queue variable. Since the default value of COMBINE is “EQU. COMBINE |KS| See “COMBINE” on page 222 for valid subkeywords and descriptions. This page only mentions those parameters that are new or different in Cube Avenue. “AVE” is a good choice of combine value. 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. Cube Voyager Reference Guide 1019 .” COMBINE must always be specified explicitly for AVENUE. Note that the primary difference between these two regimes is where the front of a queue occurs. PARAMETERS Set general parameters MODELPERIOD SEGMENTS VEHPERDIST COMBINE CAPLINKENTRY PKTPTHSIZ MAXPTHPERSEG All the parameters from Highway are also available in Cube Avenue. Values can only increase in subsequent time segments. When CAPLINKENTRY=N. the link capacity only limits how quickly they can leave the link. Combine type “EQU” is not valid for Avenue. If CAPLINKENTRY is off. For most uses of AVENUE. 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.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. 16 Cube Avenue Control statements PARAMETERS keywords (continued) Keyword PACKETS |KS| Description Only applicable for COMBINE=AVE. 1020 Cube Voyager Reference Guide . selects between packet splitting and packet allocation modes. 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. Defaults to PA. On subsequent iterations a new best path is calculated and the packet’s volume is split across all available paths. Using this method results in higher memory usage and simulation time due to the greater number of packets in subsequent iterations. PSPacket splitting mode. 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. This is the traditional MSA method where a best path is calculated for a packet. PAPacket allocation mode. In this mode a new best path is calculated for each iteration. When ITERLOADINC > 0. Only applicable for COMBINE=AVE where PACKETS=PA is selected.Cube Avenue Control statements 16 PARAMETERS keywords (continued) Keyword ITERLOADINC |KI| Description Defaults to zero. (number of time segments – 1) * ITERLOADINC + 1 iterations are performed to allow for every time segment to be loaded and simulated at least once. the simulation results for that time segment are saved. This specifies the number of iterations between the loading of packets for subsequent time segments. Cube Voyager Reference Guide 1021 . This reduces the total simulation time. This allows for a partial convergence of the network for each time segment before subsequent time segments are loaded. After MAXITERS iterations have been performed for each time segment. and the simulation result for saved time segments are restored in order to ensure every time segment is simulated only MAXITERS times. For subsequent iterations path builds are not performed. resulting in a total number of iterations equal to (number of time segments – 1) * ITERLOADINC + MAXITERS. MAXITERS specifies the maximum number of iterations for each time segment. At the very minimum. 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. instead of a total number of iterations. 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. MODELPERIOD |S| The value of MODELPERIOD is the length of the model period in minutes. Otherwise. The value of the subsidiary segments clause is a list of time segment durations. If the segments list is absent. Cube Avenue builds paths for each packet—each packet’s node list is based on accurately built paths. and origin. the packet's simulated departure remains unchanged. MAXPTHPERSEG must be equal to 1. or absence. PKTPTHSIZ |KI| 1022 Cube Voyager Reference Guide . If the number of distinct packet departure times is less than this value. also in minutes. Cube Avenue executes this many path builds. the ILOOP phase must contain a DYNAMICLOAD statement. It is the presence. To save memory. of a segments clause that determines whether Cube Voyager runs Highway or Avenue. Defaults to 5. in terms of departure time. iteration. packets can swap their route information between RAM and temporary disk files. but need not (and. If PACKETS=PA is specified. distributed evenly through the time segment. If the segments list is present. Each packet’s node list is based on the nearest path build. Windows imposes a 2 gigabyte limit on the total memory available to a program. the ILOOP phase must contain a PATHLOAD statement but must not contain a DYNAMICLOAD statement. The length of the list determines the number of time segments. Packets use computer RAM when simulated. usually. should not) contain a PATHLOAD statement.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. Though this value can affect the packet’s route. Maximum number of nodes that a packet keeps in RAM. and any other value will results in a fatal error being issued. Thus.81. storage must include the average gap between the vehicles (vehicles do not queue bumper to bumper). The default value of this parameter is 181. the parameter value does not matter.81 vehicles per kilometer gives a vehicle every 5. 181. (181. or in the input network. there will already be vehicles driving on roads in the network interior. when the “true” model period begins.) The HCM2000 recommends that the following values be used. See “PATHLOAD” on page 230 for a description of this command statement and its associated keywords and usage. If the distance unit is kilometers. the extra time forms a kind of “warmup” period before the “true” modeling begins.81 vehicles per kilometer is 295. The value is only used for the calculation of default storage. Cube Voyager Reference Guide 1023 .38 vehicles per mile. so if storage is supplied explicitly in script. then 181. This is the number of queuing vehicles that can sit in one lane of roadway one distance unit long.5 meters.81 vehicles per mile does not yield an appropriate vehicle length.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. 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. Remember that the implied vehicle spacing must be greater than the average length of a vehicle. If the sum of the segments is strictly greater than the model period. The capacity. During dynamic simulation. During this execution. which is available for packets. PATHLOAD statements are executed but DYNAMICLOAD statements are not executed. ESTMO (ALLJ) PATHO (ALLJ INCLUDECOST NAME PATHOGROUP (FULLPATH)) 1024 Cube Voyager Reference Guide . all variables take values associated with the model period. PATHLOAD keywords not supported if using static PATHLOAD statements in a dynamic assignment process with DYNAMICLOAD in effect. See “Combined use of DYNAMICLOAD and static PATHLOAD” on page 1012 if implementing both command statements in the same run.16 Cube Avenue Control statements If a PATHLOAD statement is present in a Cube Avenue run. is reduced by the static loading. the static loads (generated from PATHLOAD statements) are present (and constant) in every time segment. an extra initial execution of the ILOOP is performed for every iteration. but to vary between time slices. Each packet has a start time and a number of vehicles in each volume field. on the second and subsequent iterations. However. It also has a route for each iteration of assignment. The demand for travel is assumed to be approximately constant during each time slice. during which the network is filled with traffic. there will be different estimates of delay for vehicles arriving on a link (or at a stop=line) for each time segment. the segment-by-segment times are recalculated independently. once modeling begins. The route is calculated based on the current estimate of each time segment’s delays and on the estimated time of arrival of the packet at each point on its route. It is designed to enable the prediction of time-varying costs and flows given a timevarying demand for travel. it is divided into a number of packets of vehicles. Cube Voyager Reference Guide 1025 . When dynamic demand is required for some origin-destination pair for some time segment. So.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. 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). The time modeled is divided into two major periods: a warm-up period. Furthermore the time is also divided into smaller time-slices. over which network statistics are aggregated. and the model period. At any time. no flows are assigned to the network at this stage in the process.” Given a flow. it must compare the total volume of packets in transit on the destination link. each link capacity or turn capacity is represented as a “gate. The ADJUST phase runs the simulation. The packets in transit on a link are the packets traveling on the link and the packets queuing on the link. the packet that is trying to move is blocked and remains queued on its current link until space becomes available. Otherwise the packet will be delayed until the sum of the busy time with the time at which the gate was most recently occupied. As they leave flows behind them in the network’s volume fields. a gate will work out a busy time proportional to the flow and inversely proportional to the capacity. and any flows resulting from the movement of packets during previous iterations are removed from the volume fields. 1026 Cube Voyager Reference Guide . They must also take at least the turn time to traverse a turn. If the volume of packets in transit exceeds the storage of the destination link. the routes from previous iterations are not discarded. Packets emerge from their origin zones at their start times and start moving along their routes. if a packet wishes to move into a link. Unlike a static load.16 Cube Avenue Theory On the second and subsequent iterations. If a packet arrives at a gate and the gate was unoccupied for the corresponding busy time. Instead the packet volumes travel along each route in proportion to the lambda values for the appropriate iteration. Furthermore. During the ILOOP phase. the path-building algorithm is invoked to calculate routes. it can pass straight through (but the gates most recent occupied time becomes now). Each link has a storage capacity. Such packets are queued on the link preceding the gate. Packets must take at least the link time to traverse a link. The simulation is run in continuous time (not segment-by-segment). but they are not considered to be blocked. the segment in which the first link is left. When a packet moves from a link to another link. the packets are released onto the network and move along their predetermined paths. all the link volume fields. the volume fields for the second link. from previous iterations are retained. As the simulation progresses. Paths are calculated for each packet and the packets are written to (a temporary file on) disk. At the start of the simulation (that is. As they move from link to link the network volume fields are updated as follows: • • When a packet departs the origin. are updated. for all time segments. the packets are appended to the existing disk file. The packets are read from disk and the stored values of flow are multiplied by the appropriate factor.Cube Avenue Theory 16 Cube Avenue calculations This section describes Cube Avenue calculations: • • • Volumes Times Speeds Volumes During the ILOOP phase. and for the turn between the two links. When a packet arrives at a destination no volume fields are updated. On the second and subsequent iterations. Note that the volume fields are updated for a single time segment. the paths etc. the matrix cells in the demand trip matrix are calculated and split into packets. for the current iteration are cleared to zero. the ADJUST phase). • 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 . the volume for the origin zone centroid connector is updated. V20 are increased by the values stored in the packet. flow times for all time segments are initialized to the T1 values read from the input network (or set by code in phase LINKREAD). is used instead. these functions default to simple summation over all volumes. Prior to any calculations. The network time fields are calculated as the sum of the blocked and flow times. If the latter choice is made. Unmodeled turns are those where there is no modeling or where there is a fixed turn penalty. V2. The link time is the sum of the flow time and the block time. Any turns where these defaults do not yield a value are initialized to zero. Cube Avenue maintains two components of link time (called flow time and block time) and one component of turn time for each time segment. Block times are initialized to zero. the volumes will be written to the output network. Modeled turns are those with function turn penalties or with intersection models. V. the convergence tests decide whether Cube Avenue should continue or stop.16 Cube Avenue Theory • • • First the packet is examined to determine which of the twenty possible volume fields are present. There are two kinds of turns in Cube Avenue: unmodeled and modeled. the function. and from times in the turn penalty file. Times Logically. Unmodeled turns never change their time and they do not apply capacity “gates” to regulate the movement of packets from their preceding link. the function. is executed to update the total volume. At the end of the iteration. if the volumes are for a turn. In both cases the times are updated for each 1028 Cube Voyager Reference Guide . T. The values of V1. If the volumes are for a link. Note that in the absence of a userdefined function. Similarly turn times are initialized from the “EstimatedDelay” values stored in the intersection file. …. The turn times are updated by running the intersection model with the previously noted initial queues and the turning volumes obtained from the simulation. They are calculated immediately prior to network output as Speed = 60 Distance / Time. the blocked time for the segment becomes the average excess minutes per vehicle. Any user code for the ADJUST phase is executed. the queues for each modeled turn are noted. Speeds The link speeds are not used during the path building or simulation. The flow times are updated by running the appropriate TC functions for the segment volumes. The costs are taken by applying the cost function to these fields. Cube Voyager Reference Guide 1029 . The program tracks in which time segments these excess vehicle minutes occur.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. In the first time segment these are taken from the “InitialQueue” values stored in the intersection file. Sometimes the packets take longer than the sum (flow time + turn time) to do so. the link times are taken from the network time field. Before a segment begins. incurred during the segment. As the simulation progresses the packets move from link to link. Note that the speeds do not take turn times into account. all blocked times are zeroed. Prior to simulation. After a segment has been simulated. In subsequent time segments they are found by looking at the packets simulated to be waiting to make the relevant movement. During path building. The time fields in the network for the segment are now updated to be the sum of blocked and flow times. Note that this is a signed value. or during the static phase of a combined assignment. It takes the value zero during a static assignment. 1030 Cube Voyager Reference Guide . and the interpretation of some other script variables is modified. User script may not assign values to this variable. SegmentStart This is the time in minutes between the start of the modeled period and the start of the time segment currently being processed. etc. It takes the value zero during a static assignment. However there are some new script variables. that may be set during the LINKREAD phase. 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. This section describes only the new or changed variables: • • • • • Storage TimeSegment SegmentStart Period Time. User script may not assign values to this variable. as the dynamic time segments are being processed. 2. STORAGE. 3. It takes values 1. or during the static phase of a combined assignment. TimeSegment This is the time segment number.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. and Vol Storage There is a new script variable. Refer to the description in “LINKREAD phase” on page 1001. Cost. Time. they are not vectored. some care needs to be taken when calculations involve both “ordinary” link arrays and these time-segment vectors of link arrays.5 In a Cube Avenue dynamic assignment. User script may not assign values to this variable.5 ELSE LW. For example. more work variables must be used: IF (TIMESEGMENT=1) LW. a common way of handling costs for multi user class assignment is to calculate costs into a work variable: LW.TRUCK_COST2=DISTANCE+TIME LW.TRUCK_COST1=DISTANCE+TIME LW. (Although the values for each time segment in turn will be assigned to the link variables. It is the duration of the current time segment when time segments are being processed. with one dimension referring to the time segment and the other referring to the link number. and the costs associated with one time segment overwrite those associated with the previous one.CAR_COST1=DISTANCE/2+TIME*1.) To correctly calculate costs by user class.5 Cube Voyager Reference Guide 1031 .Cube Avenue Theory 16 Period This is the duration of the period currently being processed in minutes. the values referring to different time segments will be given different names (see “Output data” on page 1017). and Vol Internally. it will be in the context of the model period. In the output network. However. this will result in both link variables having the cost values applicable to the last time segment. When script is being executed. or of the current time segment as appropriate.CAR_COST2=DISTANCE/2+TIME*1. Cost.CAR_COST=DISTANCE/2+TIME*1. or during the static phase of a combined assignment.TRUCK_COST=DISTANCE+TIME LW. these link arrays become two-dimensional. It is the duration of the model period during a static assignment. TRUCK_COST__TS__ 1032 Cube Voyager Reference Guide . For example: DYNAMICLOAD PATH=LW.16 Cube Avenue Theory The new variables can be used in a DYNAMICLOAD statement. .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.MAT" ENDRUN Cube Voyager Reference Guide 1033 ..NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. with “RUN PGM=.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT..” Place all statements and keywords that control the run in a “RUN.. . statements using an editor. You can specify an output print file after a “PGM=AVENUE PRNFILE=” statement. Use Application Manager.. Do not change filenames or add or remove FILEI/FILEO . ENDRUN” block. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. SEGMENTS specifies a list of durations for each modeled time segment. seed random numbers ENDRUN • • 1034 Cube Voyager Reference Guide . The internal random number generator randomly draws a departure time for each packet departing in a given interval. MODELPERIOD specifies the duration of the modeled time period. In this example. Seeding the random number generator makes results repeatable between multiple runs of the same assignment. this example seeds the random number generator. COMBINE specifies the method of combining iterations together. In addition. the sum of the segments exceeds the model period. Cube Avenue treats the excess time as a “warm up” prior to the model period.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. .PRN“ FILEO NETO = "{SCENARIO_DIR}\OUTPUT. statements using an editor.30 min warm-up X=RANDSEED(165) .MAT" PARAMETERS MAXITERS=10. the method is AVE. Use Application Manager. COMBINE=AVE.16 Cube Avenue Examples Parameters This example adds some parameters to the Cube Avenue script: • • MAXITERS specifies the maximum number of iterations. successive averages. Do not change filenames or add or remove FILEI/FILEO . MODELPERIOD=90. in minutes.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. RUN PGM=AVENUE PRNFILE="{SCENARIO_DIR}\OUT.30. AVE is the recommended method for equilibrium dynamic assignment. . In this case.30.30. SEGMENTS=30. MAT" PARAMETERS MAXITERS=10.LNCAP*1. COMBINE=AVE. statements using an editor.MPH T0=60*DISTANCE/SPEED . Use Application Manager. LINKCLASS — Function index number for calculating congested time and cost. SPEED — Used with DISTANCE to calculate default T0 values. T0 — Free-flow link travel time. SEGMENTS=30. This example shows: • • • • • • DISTANCE — Used with other variables to calculate default T0 and STORAGE values. C — Flow rate capacity. .30 .Cube Avenue Examples 16 LINKREAD Just as in the Highway model.LANES*LI.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT.VEHPERLNMI IF (STORAGE=0) STORAGE=9999999 LINKCLASS = LI.time in minutes C=LI.FEET/5280 .FTYPE ENDPHASE ENDRUN Cube Voyager Reference Guide 1035 .scale to model period STORAGE = DISTANCE*LI.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. MODELPERIOD=90.LANES*LI.30.30 min warm-up PHASE=LINKREAD DISTANCE=LI. Cube Avenue reads the input network and uses either user expressions or default rules to initialize important link variables.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.30. You might need to convert from hourly capacities.5 . STORAGE — Number of vehicles that can physically fit on a link (should not be zero). RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. in vehicles per model period. Do not change filenames or add or remove FILEI/FILEO .converting to miles SPEED=LI. Accordingly DISTANCE and SPEED are not used ENDPHASE ENDRUN Centroids Centroid connectors connect zones to the network. For example.81. Do not change filenames or add or remove FILEI/FILEO . RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.30.30 min warm-up PHASE=LINKREAD . . Use Application Manager.) Citilabs recommends using different STORAGE values for arterials and freeways. MODELPERIOD=90. (The default value for VehPerDist is 181. Input network fields named STORAGE. CAPFAC=1. as well as input CAPACITY for C . freeway storage = 120 vehicles/ln-mi .Automatically use STORAGE from network.30. SEGMENTS=30.MAT" PARAMETERS MAXITERS=10. they do not represent physical road features. which was . infinite storage. the example uses the CAPFAC parameter to scale the value to the model period duration. 1036 Cube Voyager Reference Guide .PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. Because the network’s input capacity is specified in vehicles per hour. In Cube. in Cube Avenue. arterial storage = 220 vehicles/ln-mi . very large) capacity.30 .calculated in Cube editor window based on HCM: . you must define these links to have infinite (that is.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. if the input network has values for LANES and DISTANCE.16 Cube Avenue Examples Simplifying LINKREAD Not every link variable needs an explicit expression.Also use TIME from network for T0 . then Cube Avenue can compute STORAGE using the formula VehPerDist * LANES * DISTANCE. CAPACITY. and TIME override any default calculations for these variables. you can define a network variable named STORAGE. COMBINE=AVE.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. statements using an editor.5. and zero travel time. Therefore. Cube Voyager Reference Guide 1037 .calculated in Cube network editor based on HCM: .30 min warm-up PHASE=LINKREAD . RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.Cube Avenue Examples 16 Because links with zero capacity and storage can cause problems in dynamic assignment.30 . and builds dynamic (time-varying) paths. arterial storage = 220 vehicles/ln-mi . which is initially the free-flow link travel time. also.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. which was .NET" FILEI NETI = "{SCENARIO_DIR}\INPUT. CAPFAC=1.30. this is the same as TIME.Also use TIME from network for T0 as well .5. creates packets for assignment. By default. Do not change filenames or add or remove FILEI/FILEO . 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.Automatically use STORAGE from network. you must find such links and give them large capacity and storage values. statements using an editor. MODELPERIOD=90.MAT" PARAMETERS MAXITERS=10. . This example assigns all centroid connectors LINKCLASS=2 using the ZONES variable. Cube Avenue loops through all the input zones.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.30. freeway storage = 120 vehicles/ln-mi . COMBINE=AVE. Use Application Manager. The statement DYNAMICLOAD PATH=COST tells Cube Avenue to build dynamic paths using congested travel costs by time segment. SEGMENTS=30. VOL[1]=mi. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.30.1. statements using an editor.1. The statement PACKETSIZE=10 groups the input vehicle trips into packets with a target size of ten vehicles. Cube Avenue adjusts all links using the standard BPR formula: TC[1] = T0 *(1 + 0. Cube Avenue uses delay functions to calculate congested travel times by segment. Do not change filenames or add or remove FILEI/FILEO .30. The tables listed in VOL[1] specify the matrix to use for each time segment.1.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.1. including warm-up.15* (V/C) ^ 4) .1. SEGMENTS=30.16 Cube Avenue Examples The input matrix for this example contains three tables. statements using an editor. one for each half hour of the model period. Use Application Manager.mi. MODELPERIOD=90. CAPFAC=1.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT.3 ENDPHASE ENDRUN ADJUST When a script calls one or more DYNAMICLOAD statements.5.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. PACKETSIZE=10.NET" 1038 Cube Voyager Reference Guide .MAT" PARAMETERS MAXITERS=10.30 . .mi. By default.2.mi.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.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. COMBINE=AVE.1. After simulating packets and recording link volumes. Do not change filenames or add or remove FILEI/FILEO . RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT. Use Application Manager. Cube Avenue simulates the movement of packets through the network during the ADJUST phase. is inadequate for Cube Avenue.3 PHASE=ADJUST ENDPHASE ENDRUN Enhancing ADJUST The standard BPR formula. which does not degrade link performance significantly until volumes exceed capacity. PACKETSIZE=10.1. CAPFAC=1. where assignment volumes never exceed capacity. LINKCLASS=2 represents centroid connectors. MODELPERIOD=90.1.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.2.J represents a calibration parameter coded directly into the network. SEGMENTS=30. which should not degrade performance. COMBINE=AVE. LI.mi.1. This example implements a performance function from Chapter 30 of the Highway Capacity Manual 2000.Cube Avenue Examples 16 FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.30. The example introduces a custom COST function that incorporates vehicle operating costs and tolls into route-choice behavior. Use Application Manager.DO represents free-flow signal delay.1. In this example: • • • LI.mi.30. statements using an editor. .mi. The units of COST are monetary.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.MAT" PARAMETERS MAXITERS=10. based on facility type.30 .5.NET" Cube Voyager Reference Guide 1039 .PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.1.1. Do not change filenames or add or remove FILEI/FILEO . VOL[1]=mi. MAT" PARAMETERS MAXITERS=10. 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.30 . SEGMENTS=30. MODELPERIOD=90. specifying that links specify an area.mi. PACKETSIZE=10.J*V/C*DIST^2)/30^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.5. but not necessarily all of the links 1040 Cube Voyager Reference Guide .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.3 PHASE=ADJUST Function TC[1]=T0+LI.1.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.1.1. VOL[1]=mi.D0+(0.mi.30.1.mi.25*30)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI.1.1.30. hence output packets must pass through at least one of the specified links. COMBINE=AVE. CAPFAC=1.2.16 Cube Avenue Examples FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. PRN" FILEO NETO = "{SCENARIO_DIR}\OUTPUT. VOL[1]=mi. CAPFAC=1. DESTINATION=1-10. FORMAT=BIN PARAMETERS MAXITERS=10.LOG". PACKETSIZE=10.D0+(0.1. and builds time-varying paths for these flows.5. This computation-intensive process can result in slow run times. ORIGIN=1-10.3 PHASE=ADJUST Function TC[1]=T0+LI.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.1. SELECTLINK=(L=101-1903*).2.30.mi.J*V/C*DIST^2)/30^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI. COMBINE=AVE.25*30)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI. DEPARTTIME=1800-3600. AFTERITER=9. ARRIVALTIME=1800-3600.mi.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. MUSTMEETALL=F. SELECTGROUP=3.TOLL Function COST[2]=TIME ENDPHASE ENDRUN Tuning parameters Cube Avenue generates packet flows that depart intermittently throughout the model period. Cube Voyager Reference Guide 1041 .1.mi. SEGMENTS=30.1.30.1.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. MODELPERIOD=90.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.30 .TOLL>0) AddToGroup=3 PHASE=ILOOP DYNAMICLOAD PATH=COST.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.1. VOL[1]=mi.LOG".TOLL>0) AddToGroup=3 PHASE=ILOOP DYNAMICLOAD PATH=COST.TOLL Function COST[2]=TIME ENDPHASE ENDRUN Reducing segment and volume lists When using many time segments.30.mi. FORMAT=BIN PARAMETERS MAXITERS=10. PACKETSIZE=10. MODELPERIOD=90.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT. ARRIVALTIME=1800-3600. COMBINE=AVE.5.J*V/C*DIST^2)/30^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.3 PHASE=ADJUST Function TC[1]=T0+LI.1. SELECTGROUP=3. MUSTMEETALL=F. AFTERITER=9.30.mi. SEGMENTS=30. DESTINATION=1-10. CAPFAC=1. ORIGIN=1-10. This example has a segment duration of 30 minutes. segment and volume lists can become long and unwieldy.1.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.mi.30.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. SELECTLINK=(L=101-1903*).1. 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.1. This reduces the number of built paths and improves computation time. 1042 Cube Voyager Reference Guide . RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.25*30)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT. DEPARTTIME=1800-3600.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.D0+(0. but can introduce model granularity.2.1.1. A MaxPthPerSeg value of 10 forces packets within threeminute intervals to use the same path. AFTERITER=9. DESTINATION=1-10. ORIGIN=1-10.1.1.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.D0+(0. FORMAT=BIN PARAMETERS MAXITERS=10. when the “_TS_” notation is used within MW brackets for VOL.1 MW[2]=mi. DEPARTTIME=1800-3600. RUN PGM=AVENUE PRNFILE=“{SCENARIO_DIR}\OUT.1. SEGMENTS=4*30.2.TOLL>0) AddToGroup=3 PHASE=ILOOP MW[1]=mi. MODELPERIOD=90.25*15)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI. VOL[1]=MW[__TS__] PHASE=ADJUST Function TC[1]=T0+LI. ARRIVALTIME=1800-3600. 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.J*V/C*DIST^2)/15^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.MW[3]=mi.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET. MUSTMEETALL=F.PRN” FILEO NETO = "{SCENARIO_DIR}\OUTPUT.5. If the time segments are of equal duration.MW[4]=mi. Cube Avenue substitutes the expression with an MW vector that contains the number of time segments (replacing “_TS_” with the time segment’s index). PACKETSIZE=10.TOLL Function COST[2]=TIME Cube Voyager Reference Guide 1043 .Cube Avenue Examples 16 The SEGMENTS parameter supports the repetition (*) operator.LOG".1. SELECTGROUP=3.1.3 DYNAMICLOAD PATH=COST. SELECTLINK=(L=101-1903*). COMBINE=AVE. 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. CAPFAC=1. 16 Cube Avenue Examples ENDPHASE ENDRUN 1044 Cube Voyager Reference Guide . Cube Voyager Reference Guide Cube Voyager Reference Guide 1045 . Highway 213 GOTO keyword. Public Transport 740 @.. Matrix variable 457 _COMPARE. Distribution 578 SETPA keyword. Highway variable 140 _ZONES. 85 * command 88 ** command 88 :label GOTO keyword.@ 24.. Generation 594 ACCESS LINE NODES subkeyword. Network variable 345 A A COMP keyword.. Fratar 130 A2P BALANCE keyword.% 24. Pilot 96 GOTO 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. eliminating 814 report 775 1046 Cube Voyager Reference Guide . Public Transport 749 LINE NODES subkeyword. Generation 589 Highway array 141 Network variable 345 REPORT keyword. TRNBUILD 919 access legs generating 869 multiple.Index Symbols Index Symbols %.. 85 _BSEARCH. Network variable 345 _SKIPTOI. Generation 594 SETPA keyword. Generation 588 AAD convergence testing calculation 172 Highway variable 142 PARAMETERS keyword. Index A restricting to modes 670 ACCESS_C LINE NODES subkeyword. Fratar 130 algorithm all-or-nothing path building 763 Cube Avenue 1025 public transport transfers 763 ALIGN PLOTTER FOOTER subkeyword. TRNBUILD 917 all-way-stop-controlled intersections 313 ALPHA FACTORS keyword. Pilot 105 AONMAXFERS FACTORS keyword. TRNBUILD 919 ACCESSLEGS REREPORT keyword. common description 282 JUNCTION keyword. Public Transport 664 ADJUSTWAIT CROWDMODEL keyword. Public Transport 732 ACCESSMODES SELECT keyword. general 67 APPLY CROWDMODEL keyword. signals 293 ADDTOGROUP SETGROUP keyword. Highway 260 ADJUSTLINK CROWDMODEL keyword. cost-based model 462 CHOICE keyword. common description 280 JUNCTION keyword. empirical roundabout 316 JUNCTION keyword. general 76 arrays Cube Voyager Reference Guide 1047 . Public Transport 667 ALTERNATIVES CHOICE keyword. Highway 253 ADJUST phase Cube Avenue 1006 Highway program 164 stack for. Public Transport 664 AFTERITER FILEO PACKETLOG subkeyword. 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. overview 276 APPROACH1 JUNCTION keyword. overview 276 JUNCTION keyword. Highway 239 ALLSTOPS LINE keyword. Network 381 ALL REPORT keyword. Matrix 525 FILEO PRINTO subkeyword. Public Transport 667 AONMETHOD PARAMETERS keyword. Public Transport 749 LINE NODES subkeyword. Network 390 ALLJ PATHLOAD ESTMO subkeyword. Highway 232 PATHLOAD PATHO subkeyword. Cube Avenue 1015 afterpgm NEWPAGE keyword. utility-based model 472 ALTNAME PARAMETERS keyword. TRNBUILD 939 ACCUMULATE FILEO STOP2STOPO subkeyword. Public Transport 775 ACCESSLINK GENERATE keyword. Highway 205 FILEO PRINTO keyword. Network 368 PRINT FILE subkeyword. Pilot 100 aftersys NEWPAGE keyword. Distribution 577 ACTION NT keyword. Pilot 100 AGF SETPA keyword. Network 380 PLOTTER HEADER subkeyword. Public Transport 725 ACOMP REPORT keyword. Public Transport 664 APPROACH JUNCTION keyword. TPP2UB 960 ANSWER PROMPT keyword. Public Transport 760 ACTUALGREEN JUNCTION keyword. Public Transport 746 LINE keyword. Highway 206 FILEO PRINTO subkeyword. overview 276 APPROACHWIDTH JUNCTION keyword. Fratar 128 REPORT keywords. cost-based model 469 XCHOICE keyword. Public Transport 763 APPEND FILEO NETO keyword. utility-based model 465 XCHOICE keyword. numeric items 70 print format code. Matrix 457 Highway 141 initializing. Network 363 BESTJRNY skim function. utility-based model 472 BASEGDBNETWORK FILEO LINEO subkeyword. number of 592 production and attraction. Pilot 100 BEG FILEI LINKI VAR subkeyword. Matrix 508 MERGE keyword. cost-based model 469 BASEDATA FILEI TURNPENI subkeyword. Matrix 508 MERGE keyword. utility-based model 465 BASEUTILSMW XCHOICE keyword. Cube Avenue 1031 Matrix. Network 391 specifying with keywords 28 string valued 508 user. Highway 198 FILEI ZDATI subkeyword. general 73 BASECOSTS CHOICE keyword. Public Transport 709 FILEO NTLEGO subkeyword. reporting in Matrix 551 ARRAYSUM COMP function. Public Transport 705 BASEDEMAND CHOICE keyword. referencing 570 route-enumeration components 674 setting to same value. Cube Avenue 1015 ASSIGN TRIPS MATRIX subkeyword. Public Transport 717 BASEMW FREQUENCY keyword. geometric signals 296 JUNCTION keyword. utility-based model 473 beforepgm NEWPAGE keyword. Matrix 491 finding keys in. DBI 491 Matrix.Index B creating and populating 511 Cube Cluster and 983 field names in. example 64 production and attraction 120 production and attraction. overview 276 AVEX0 FILEI ZDATI subkeyword. cost-based model 469 XCHOICE keyword. Highway 254 sorting. Network 372 B B Highway array 141 Network variable 345 print format code. Network 372 AVERAGELANEWIDTH JUNCTION keyword. declaring in Network 348 user-defined. generating 585 production and attraction. Matrix 481 Matrix built-in function 410 ARRIVALTIME FILEO PACKETLOG subkeyword. Pilot 100 beforesys NEWPAGE keyword. Highway 252 sorting 76 sorting. Network 379 BASE1 PRINTROW keyword. utility-based model 465 BASEDEMANDMW XCHOICE keyword. string items 72 BALANCE Generation control statement 588 Highway variable 142 BALANCE variable functions for 174 setting. Matrix 491 AUTOCOEF PARAMETERS keyword. convergence script 172 variables for 173 BANDWIDTH PLOTTER keyword. Pilot 112 AUTOARRAY FILEI DBI subkeyword. sorting in Matrix 553 zonal data. RECI 504 populating with LOOKUP. denoting 767 link. reporting in Highway 252 link work. cost-based model 462 BASECOSTSMW XCHOICE keyword. Highway 198 FILEI ZDATI subkeyword. TPP2UB 960 AVE FILEI ZDATI subkeyword. cost-based model 462 CHOICE keyword. TRNBUILD 946 ATTACHMENTS SENDMAIL keyword. summary 625 BESTPATHONLY 1048 Cube Voyager Reference Guide . Matrix 532 BASEUTILS CHOICE keyword. declaring in Highway 180 user. Public Transport 622 skim function. Highway 156 internal. Public Transport 669 skim function. Network 351 Highway function 142 Network function 346 CAPACITYINTERCEPT JUNCTION keyword. empirical roundabout 318 JUNCTION keyword. Public Transport 668 BIN FILEO TURNVOLO file format 208 boarding penalty example 882 mode specific 669 perceived. overview 277 CAPACITYSLOPE JUNCTION keyword. signals 291 CANSHARERIGHT JUNCTION keyword. Public Transport 623 skim function. default wait curve 784 first. outside LINKREAD phase 221 setting. empirical roundabout 317 JUNCTION keyword. TRNBUILD 905 BOARDS TRIPS MATRIX ASSIGN subkeyword. including in 713 number. Network 392 CAPACITYFOR COMP function. example in Cube Avenue 1035 value computed. saturation-flow priority junctions 336 JUNCTION keyword. signals 292 CAPACITY REPORT keyword. Public Transport 621 skim function. TRNBUILD 946 bottleneck modeling as generalized cost 799 modeling with crowding 861 queuing location. including in 709 link output. 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. saturation-flow priority junction 337 JUNCTION keyword. Highway LINKREAD phase 158 variable. wait curve used 782 transit leg definition 809 wait time at 799 boardings example 882 line output. Network 390 REPORT keyword. overview 277 CAPFAC applying in Cube Avenue 1003 PARAMETERS keyword. TRNBUILD 935 SPDCAP keyword. Highway 221 scaling input capacity with. Public Transport 711 C C DYNAMIC keyword. summary 625 BRDPEN FACTORS keyword. geometric signals 297 JUNCTION keyword. skim function 621 reducing during transfers 800 boarding point first. example value 147 print format code. TRNBUILD 928 BUSBLOCKAGE JUNCTION keyword. Highway 254 SPDCAP keyword. skim function 623 passenger loading report. overview 276 JUNCTION keyword. numeric items 70 print format code. Cube Avenue 1008 Highway variable 140 Highway 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 BYCLASS FILEO LINKO subkeyword. overview 276 JUNCTION keyword. including in 773 BOARDPEN FACTOR keyword. Highway 250 REPORT keyword.Index C FACTORS keyword. Cube Avenue 1019 trips affected. string items 72 set value. Cube Avenue 1036 Cube Voyager Reference Guide 1049 . skim function 624 BRDINGS skim function. Public Transport 830 transfer points. Public Transport 830 CHOICECUT FACTORS keyword. general 47 CROSSTAB keyword. Cube Cluster 991 DISTRIBUTEMULTISTEP keyword. Pilot 112 CENTRALBUSINESSDISTRICT JUNCTION keyword. Cube Avenue 1019 CC SENDMAIL keyword. Public Transport 623 skim function. Public Transport 836 transit choices. geometric signals 298 JUNCTION keyword. TRNBUILD 942 CLEARERROR Pilot control statement 89 CLEARFILEO DOWNLOAD keyword. differences with 475 choice modeling absolute logit model 422 alternative alighting. Generation 590 FILEO RECO subkeyword. Cube Cluster 989 CHOICE Matrix control statement 461 Matrix control statement. geometric signals 297 CONFVAR 1050 Cube Voyager Reference Guide . Matrix 508 MERGE keyword.Index C CAPLINKENTRY PARAMETERS keyword. TRNBUILD 923 PNR keyword. Network 361 FILEO MATO keyword. Network 372 CODE CLEARERROR keyword. Public Transport 763 CHECKRETURNCODE WAIT4FILES keyword. overview 277 CENTRALRESERVATIONWIDTH JUNCTION keyword. Cube Cluster 988 COMP control statement. Highway 222 TRNBUILD control statement 903 command prompt. Highway 203 PARAMETERS keyword. general 66 REPORT MARGINREC subkeyword. Cube Avenue 1019 PARAMETERS keyword. replacing 420 XCHOICE. starting Cube Voyager from 17 comments 25 COMMPATH DISTRIBUTEINTRASTEP keyword. TRNBUILD 918 LINK keyword. Network 355 COLOR LINE keyword. Public Transport 833 walk choice. Matrix 525 PRINT keyword. Public Transport 669 CIRCULAR LINE 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. summary 625 composite cost skim function 623 confidence levels matrix estimation 863 output links 722 CONFLICTINGBIKE JUNCTION keyword. geometric priority junctions 331 JUNCTION 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. Public Transport 746 CLEAR LINE GLOBAL subkeyword. TRNBUILD 917 COMBINE FILEI LINKI subkeyword. overview 277 CFORM FILEO PAO subkeyword. TRNBUILD 932 SUPPORT keyword. Highway 199 FILEI ZDATI subkeyword.exe 992 CmpNumRetNum 35 CNT FILEI ZDATI subkeyword. Pilot 94 Cluster. Matrix 549 CHANGEATLASTSTOP PARAMETERS keyword. 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 645 MATI phase. Public Transport 646 Distribution program 573 fields 27 Generation program 587 Highway program 179 Highway program. Public Transport 648 MATO phase. writing 575 phase supporting. Highway 171 phases and. Public Transport 733 Highway array 141 NT keyword. Highway 205 COSTS CHOICE keyword. restricting modes 670 egress. adjusting for 130 COPY Pilot control statement 92 COS 38 COST FUNCTION keyword. Public Transport 650 stacks. Public Transport 651 Matrix program. Highway 202 CRITICALGAP JUNCTION keyword. Highway program 168 stack for. empirical roundabout 320 CROSSTAB Cube Voyager Reference Guide 1051 . Highway 225 PATHLOAD keyword. Highway LINKREAD phase 159 COSTDEC FILEO PATHO keyword. cost-based model 470 COUNTVAR FILEO ESTMICPO subkeyword. overview 277 JUNCTION keyword. empirical roundabout 319 JUNCTION keyword. geometric priority junctions 332 CROSSINGLENGTH GEOMETRIC priority junctions 332 JUNCTION keyword. Public Transport 644 null blocks 25 overview 45 Public Transport program 653 SELECTIJ phase. Highway 212 GENERATE keyword. Public Transport 722 connectors access. geometric priority junctions 332 CROSSING2EXIT JUNCTION keyword. Highway program 260 convergence crowding model. types 138 keywords 28 LINKREAD phase. general 48 CONSOLIDATE PARAMETERS keyword. summary 974 DATAPREP phase. types 411 Network program 347 NODEREAD phase. Highway 202 FILEO SCREENLINEO subkeyword. Fratar 130 control blocks 26 control fields 27 control statements comments 25 control blocks 26 Cube Cluster. two-way stop 307 CROSSING2ENTRY JUNCTION keyword. iteration control 123 intersection modeling and 274 multiple purposes and 568 output matrices and 127 output matrices. gap-acceptance roundabout 327 JUNCTION keyword. Highway program 259 subkeywords 29 tokens 24 CONVERGE phase Cube Avenue 1007 Highway program 171 not specifying. Public Transport 760 value set. Public Transport 862 Cube Avenue 1028 default testing. 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. restricting modes 670 CONSOLE control statement.Index C FILEO ESTMICPO subkeyword. cost-based model 462 COSTSMW XCHOICE keyword. list of 451 Matrix program. empirical roundabout 320 JUNCTION keyword. Highway 137 target totals. Highway 168 Distribution model 566 Fratar distribution 119 Fratar distribution. Public Transport 781 CSV PATHLOAD TRACE subkeyword. 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. producing for 202 MATO file. 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. string items 72 DATAPREP Public Transport phase 646 DBF FILEO PAO subkeyword. Highway 243 PRINT keyword. updating 861 link-travel-time adjustment 857 outputs. Public Transport 620 skim function. Public Transport 618 skim function. producing for 708 Public Transport screenline file. summary 625 CWDWAITA skim function. signals 292 D D print format code. Pilot 108 Cube Analyst intercept file. Public Transport 783 CWDCOSTP skim function. summary 625 CYCLETIME JUNCTION keyword. Public Transport 746 VEHICLETYPE keyword.Index D Network control statement 354 crowd modeling boarding probability. overview 277 JUNCTION keyword. general 66 CTLFILE RUN keyword. numeric items 70 print format code. Public Transport 747 VEHICLETYPE keyword. updating 861 control statement defining 664 in-vehicle-time effects 800 link travel times. skim function 618 seat occupancy value 748 theory 857 CROWDMODEL Public Transport control statement 664 CRUSHCAP LINE keyword. writing to with Matrix RECO 526 Generation program output 590 1052 Cube Voyager Reference Guide . summary 625 CWDWAITP skim function. producing for 722 screenline data file. skim function 618 perceived wait time. 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. producing for 522 Public Transport demand matrices 863 Public Transport intercept file. Generation 590 FILEO TURNVOLO file format 208 DBF files dumping link and node records to 401 fields. Public Transport 618 skim function. setting 711 process. Public Transport 663 WAITCRVDEF keyword. Public Transport 781 crowding actual wait time. cost-based model 470 XCHOICE keyword. utility-based model 473 DETAILS FILEI LINKI subkeyword. Public Transport 722 DELACCESSMODE FACTORS keyword. Public Transport 749 LINE NODES subkeyword. Matrix 521 FILEO TURNVOLO keyword. Cube Avenue 1016 design concepts 3 DESTINATION FILEO PACKETLOG subkeyword. Matrix 504 FILEO LINKO subkeyword. cost-based model 470 DEADLINKS REPORT keyword.Index D linking to LOOKUPI file 56 matrix data input files. Network 361 Cube Voyager Reference Guide 1053 . utility-based (XCHOICE) 473 combined with mode-choice 445 demand. Highway 199 FILEI ZDATI subkeyword. Matrix 498 Matrix program input. cost-based model 469 specifying name. Public Transport 772 REPORT LINEVOLS subkeyword. Matrix 508 DEFAULTCONF FILEO ESTMICPO subkeyword. cost-based (CHOICE) 463 assigning zones. Cube Avenue 1016 destination zones. Public Transport 670 DEMAND CHOICE keyword. Public Transport 717 FILEO SUBAREAMATO keyword. utility-based model 465 XCHOICE keyword. Highway 204 FILEO MATO subkeyword. utility-based model 472 DEMANDMW XCHOICE keyword. Public Transport 724 turning volume file. utility-based 473 specifying name. cost-based model 470 XCHOICE keyword. Matrix 519 FILEO MATO subkeyword. Matrix 554 DBI FILEI keyword. Public Transport 715 FILEO NETO keyword 205 FILEO NETO subkeyword. Matrix 535 destination-choice model assigning zones. Public Transport 670 DELETE Network control statement 358 DELETESTR 38 DELIMITER FILEI DBI subkeyword. specifying 475 description 443 example code 559 using gravity model 565 DESTSPLIT CHOICE keyword. Network 365 FILEO MATO subkeyword. DBI 490 Matrix program input. estimating 863 pure mode-choice model. Matrix 551 DEFAULT FILEI ZDATI subkeyword. Matrix 494 FILEI RECI subkeyword. Matrix 490 files. cost-based model 470 XCHOICE keyword. Highway 206 FILEO TURNVOLO keyword. Network 390 DEC FILEO MATO keyword. RECI 503 stop-to-stop analysis. Public Transport 750 DELAYEQUATION JUNCTION keyword. Highway 207 DELMODE FACTORS keyword. Public Transport 670 DELAY LINE NODES subkeyword. cost-based model 463 CHOICE keyword. geometric signals 298 DELDISTRIBFILES WAIT4FILES keyword. utility-based model 465 XCHOICE keyword. cost-based (XCHOICE) 470 assigning zones. Highway 208 writing to. cost-based model 462 DCOSTSMW XCHOICE keyword. Highway 207 PATHLOAD PATH subkeyword. processing 510 functions to read records 510 DCOSTS CHOICE keyword. utility-based model 473 demand matrices Public Transport. Highway 252 REPORT ZDAT subkeyword. Highway 239 REPORT LINES subkeyword. utility-based (CHOICE) 465 assigning zones. Highway 203 DEFCONF FILEO SCREENLINEO subkeyword. utility-based model 473 DEPARTTIME FILEO PACKETLOG subkeyword. Cube Cluster 989 DELEGRESSMODE FACTORS keyword. TRNBUILD 919 DELAY_C LINE NODES subkeyword 919 LINE NODES subkeyword. cost-based model 463 CHOICE keyword. cost-based 470 pure mode-choice. Public Transport 773 REPORT ZDAT keyword. Network 390 DUPSTR character function 38 DUTILS CHOICE keyword. 581 examples 580 friction factors 571 introduction 563 overview 563 DLL CALL keyword. 580. Cube Avenue 1002 setting. Public Transport 750 DWELL_C LINE NODES subkeyword. Matrix 458 DOWNLOAD Pilot control statement 93 DRAWA PLOT keyword. ADJUST phase 1038 using in ILOOP 1037 using with PATHLOAD 1012 using work variables in 1032 E E print format code. Public Transport 760 skim function. example in Cube Avenue 1035 value computed. Public Transport 775 ELSE control statement. utility-based model 466 DUTILSMW XCHOICE keyword. Network 379 DIRECTION GENERATE keyword. TRNBUILD 923 NT keyword. Network 378 DUPLICATES REPORT keyword. Public Transport 733 ZONEACCESS GENERATE subkeyword. TRNBUILD 942 value. specifiying with 507 empirical roundabout difference with gap-acceptance roundabout 288 1054 Cube Voyager Reference Guide . Network 378 DRAWLINK PLOT keyword. Public Transport 750 DYNAMIC Cube Avenue control statement 1008 DYNAMICLOAD Cube Avenue control statement 1009 example. TRACEI 791 generating 869 report 775 EGRESSLEGS REREPORT keyword. example 529 ZDATI. Public Transport 623 skim function. 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. writing with 525 retrieving matrix data. Public Transport 733 DIST Highway array 141 LINK keyword. general 52 Highway control statement 214 Network control statement 369 Pilot control statement 97 ELSEIF control statement. example 528 writing with FILEO RECO. TRNBUILD 949 DIRECTLINK GENERATE keyword. TRNBUILD 950 DISTANCE Highway variable 140 script variable. writing with 518 output matrix names 524 RECO. utility-based model 473 DWELL LINE NODES subkeyword. general 52 Highway control statement 214 Network control statement 369 Pilot control statement 97 EMME/2 data bank file MATI. numeric items 70 egress legs definition 809 eliminating in multirouting models 815 example report. summary 625 SUPPLINK keyword. TRNBUILD 940 SUPPORT keyword. Highway LINKREAD phase 159 ZONEACCESS LINK subkeyword. example 516 retrieving zonal vector matrix. specifying as input with 498 MATO.Index E DEVICE PLOTTER keyword. example 517 scalar and vector matrix names 527 specifying matrix written 524 variable names written 526 writing with FILEO MATO. common description 282 ENDCOPY Pilot control statement 92 ENDDISTRIBUTEMULTISTEP Cube Cluster control statement 988 ENDIF control statement. overview 277 ENTRYGATE FILEI TOLLMATI subkeyword. Public Transport 624 skim function. TRNBUILD 893 listing in run print file. input file 702 destination zones printed. empirical roundabout 322 JUNCTION keyword. Highway 202 impact on Cube Avenue 1014 impact on Cube Cluster 982 ESTMICPO FILEO keyword. 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. Matrix 505 maximum in data records. Highway 195 ENTRYRADIUS JUNCTION keyword. Generation 593 PROCESS keyword. output file 720 quality issues 871 report 788 EXCESSDEMAND skim function. input file 701 origin zones reported. overview 277 enumerated routes destination zones 719 destination zones reported. empirical roundabout 320 JUNCTION keyword. overview 277 ESTMDATO FILEO keyword. output file 720 origin zones printed. empirical roundabout 323 JUNCTION keyword. maximum number 695 fatal. input file 701 destination zones reported. Highway 249 ENDPROCESS Generation control statement 592 Highway control statement 248 Network control statement 388 ENDRUN Pilot control statement 107 ENTRYANGLE JUNCTION keyword. input file 702 origin zones printed. common description 283 JUNCTION keyword. output file 721 origin zones reported. output file 720 report 787 user-class specific 770 using FACTORS statements for 611 EQUATION 167 EQUITURNCOSTFAC PARAMETERS keyword. Highway 202 impact on Cube Avenue 1014 impact on Cube Cluster 982 ESTMO impact on Cube Avenue 1024 PATHLOAD keyword. Matrix 505 responding to 100 transit line 766 ESTIMATEDDELAY JUNCTION keyword. summary 625 EXCESSPROP skim function. overview 277 ENTRYWIDTH JUNCTION keyword. Highway 226 errors clearing 89 factor file. Public Transport 624 Cube Voyager Reference Guide 1055 . output file 721 destination zones reported.Index E example 325 keywords 316 model overview 315 ENABLE JUNCTION keyword. Network 375 maximum in RECI records. Highway 232 setting to true 209 evaluated routes destination zones printed. output file 720 file containing 719 maximum transfers in 675 origin zones 719 origin zones reported. priority junction 337 JUNCTION keyword. Public Transport 764 EXTRACTCOST GENERATE keyword. names of 695 maximum errors 695 validating fare data in 695 FACTORI FILEI keyword. utility-based model 465 COMP MW subkeyword. Public Transport 671 F FACTOR TRNBUILD control statement 905 factor file input. Highway 196 EXITLANES JUNCTION keyword. geometric signals 298 EXITONLY JUNCTION keyword. Public Transport 733 EXCLUDERECI FILEO RECO subkeyword. overview 40 variables in 43 EXTENDREPORT PARAMETERS keyword. overview 33 selection. Highway 183 COMP MW subkeyword. 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. TRNBUILD 910 PARAMETERS keyword. Public Transport 670 EXTRAXFERS2 FACTORS keyword. Matrix program 480 computing values with FUNCTION 211 LOOKUP statement 55 numeric.Index F skim function. Public Transport 658 FILEI LINKI subkeyword. common description 283 JUNCTION keyword. Highway 232 EXCLUDELINK GENERATE keyword. defining 689 report 792 fare model assigning 671 1056 Cube Voyager Reference Guide . Public Transport 734 EXTRAXFERS1 FACTORS keyword. Public Transport 695 FACTORS network development processing 609 Public Transport control statement 666 route enumeration. Matrix 525 EXCLUSIVELANES JUNCTION keyword. overview 277 JUNCTION keyword. overview 277 EXITS TRIPS MATRIX ASSIGN subkeyword. Matrix 478 COMP MW subkeyword. Public Transport 764 TRNBUILD control statement 907 fare matrices input file containing 696 name. Highway 205 FILEO NETO subkeyword. Network 367 JLOOP keyword. summary 625 EXCLUDE CHOICE DESTSPLIT subkeyword. Fratar 130 XCHOICE DESTSPLIT subkeyword. Network 361 FILEO LINKO subkeyword. Highway 232 EXCLUDEJ PATHLOAD keyword. Public Transport 763 EXTENDRUNTIMES PARAMETERS keyword. cost-based model 463 CHOICE DESTSPLIT subkeyword. cost-based model 470 XCHOICE DESTSPLIT subkeyword. utility-based model 473 EXCLUDEGROUP PATHLOAD keyword. Distribution 578 SETPA keyword. controlling with 611 FAIL LOOKUP keyword. Network 365 FILEO NETO keyword. TRNBUILD 946 EXP 35 EXPDIST numeric function 35 EXPINV numeric function 36 exponential distribution function 35 expressions COMP statements 47 COMP. general 56 FARE FARELINKS keyword. Highway 216 SETPA keyword. Public Transport 696 FILEI keyword. Public Transport 690 FAREZONES FARESYSTEM keyword. Pilot 93 LOOKUP keyword. TRNBUILD 911 FAREMATRIX FARESYSTEM keyword. network 380 PRINT keyword. summary 625 fares boarding and transfer costs 850 determining trip cost from 850 examples 855 generalized cost component 798 input file. Distribution 574 FIELDS FILEI DBI subkeyword. Public Transport 689 FAREMSG PARAMETERS keyword. specifying for 747 matrix reports 792 methods for defining structure 848 modeling in Public Transport 845–857 models for. Public Transport 765 FAREP skim function. general 49 Cube Avenue control statement 1014 Distribution control statement 517 DOWNLOAD keyword.Index F defining 687 input file for. overview 801 multiple systems in network 850 overview 845 route evaluation. matrices 696 input file. Public Transport 696 FARELINKS TRNBUILD control statement 909 FAREMATI FILEI keyword. Network 390 SYNCHIMP control statement 962 TPP2UB control statement 959 TRNBUILD control statement 912 Cube Voyager Reference Guide 1057 . Public Transport 621 skim function. including cost in 764 skim functions for 621 system describing 687–694 validating in factor file 695 zones for 852 FARESYSTEM FACTORS keyword. Matrix 522 FILEO RECO subkeyword. Public Transport 747 Public Transport control statement 687 FARETABLE FARESYSTEM keyword. Pilot 94 example. Highway 251 FILEI control statement. summary 625 FAREFROMFS FARESYSTEM keyword. general 75 RENUMBER keyword. 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. Public Transport 689 FAREI FILEI keyword. missing data 765 line. Public Transport 621 skim function. general 56 PLOTTER keyword. specifying 696 purpose 801 FAREA skim function. Matrix 549 REPORT VDTSPD keyword. Matrix 505 FILEO MATO subkeyword. general 66 READ keyword. 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. control statements 696 input file. Matrix 495 FILEI MATI subkeyword. Network 390 SYNCHIMP control statement 961 TPP2UB control statement 959 TRNBUILD control statement 910 UB2TPP control statement 957 FILEO control statement. Network 388 Public Transport control statement 694 REPORT keyword. Matrix 526 FILE COPY keyword. Matrix 545 REPORT MARGINREC subkeyword. Matrix 500 FILEI RECI subkeyword. Public Transport 671 LINE keyword. Public Transport 692 FFACTORS GRAVITY keyword. gap-acceptance roundabout 327 JUNCTION keyword. Public Transport 711 FMVOLT NT keyword. Public Transport 716 FILEO NETO subkeyword. Matrix 546 WAIT4FILES keyword. Matrix 549 FORMAT character function 38 FILEO LINEVOLO subkeyword. Network 366 FILEO LINKVOLO subkeyword. overview 277 JUNCTION keyword. TRNBUILD 913 FILEO LINKO subkeyword. Network 373 FirstReadyNode function 994 FIRSTZONE Cube Cluster impact 984 Matrix built-in variable 409 FIXED FILEO SUPPORTO subkeyword. Network 380 FORM CROSSTAB COMP subkeyword. Public Transport 750 NT keyword. Matrix 527 PRINT keyword. Public Transport 761 FOLLOWUPTIME JUNCTION keyword. Public Transport 750 FMVOL LINE NODES subkeyword. 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. overview 277 JUNCTION keyword. two-way stop 307 FONT PLOTTER FOOTER subkeyword. Network 382 PLOTTER POSTLINKVAR subkeyword. two-way stop 308 FRACTIONS PARAMETERS COMBINE keyword. Public Transport 760 FMVOLS FILEO LINKO subkeyword. Highway 204 FILEO MATO subkeyword. Cube Avenue 1016 FILEO SUBAREAMATO keyword. Public Transport 747 FMOFF LINE NODES subkeyword. Network 381 PLOTTER LEGEND subkeyword.Index F UB2TPP control statement 958 FILES keyword RENUMBER keyword. general 73 REPORT MARGINREC subkeyword. Public Transport 672 FREQPERIOD PARAMETERS keyword. overview 277 FLARESTORAGE JUNCTION keyword. TRNBUILD 915 FILEO MATO 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. empirical roundabout 324 JUNCTION keyword. Public Transport 750 FMON LINE NODES subkeyword. Highway 199 FILEI ZDATI subkeyword. Network 355 CROSSTAB VAR subkeyword. Network 384 PLOTTER POSTNODEVAR subkeyword. Network 379 FILLMW Distribution control statement 531 Fratar control statement 531 Highway control statement 211 Matrix control statement 531 FIRST FILEI ZDATI subkeyword. general 67 PRINTROW keyword. Matrix 508 MERGE keyword. Highway 208 FOURLANEMAJOR JUNCTION keyword. geometric priority junctions 332 JUNCTION keyword. TRNBUILD 916 FLARELENGTH JUNCTION keyword. TRNBUILD 928 1058 Cube Voyager Reference Guide . Matrix 522 FILEO MATO subkeyword. overview 277 JUNCTION keyword. Network 385 FOOTER PLOTTER keyword. Network 367 FILEO PACKETLOG subkeyword. two-way stop 307 FMCAPACITY LINE keyword. two-way stop 308 FREQBYMODE FACTORS keyword. Network 365 FILEO PAO subkeyword. Network 356 FILEO LINKO subkeyword. Generation 591 FILEO RECO subkeyword. Network 380 PLOTTER HEADER subkeyword. Highway 206 FILEO TURNVOLO keyword. specifying 666 route evaluation. Public Transport 683 FACTORS XFERPEN subkeyword. including in 764 in-vehicle time component 799 logit choice models 423 route enumeration and evaluation. Public Transport 734 FULL REPORT LINKVOL subkeyword. Highway 239 FUNCTION Highway control statement 211 functions built-in. Public Transport 682 FACTORS XFERFACTOR subkeyword. TRNBUILD 917 friction factors curves in gravity model 564 distribution process. Pilot 112 FROMNODE GENERATE keyword. general 35 trig. Public Transport 684 SENDMAIL keyword. general 37 utility. all programs 35 character. using for 826 theory. general 38 COMP expression 481 convergence. Highway program 143 Cube Avenue 1030 Highway program 141 lookup 40 matrix 185–188 Matrix program. use in 571 example. typical process 62 expression. TRNBUILD 936 FULLPATH PATHLOAD PATHO subkeyword. 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. 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. route enumeration 801 converting from monetary fares 682 fare component 801 fares. Highway 226 using in BALANCE variable 173 gap-acceptance roundabout difference with empirical roundabout 288 example 328. specifying 574 FROM FACTORS XFERCONST subkeyword. built-in 410 numeric. TRNBUILD 917 Matrix control statement 532 FREQUENCYR LINE keyword. 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 G FREQUENCY Distribution control statement 532 Fratar control statement 532 impact on Cube Cluster 983 LINE keyword. singly constrained 558 implementation guidelines 564 GROUPEDMODES FILEO STOP2STOPO subkeyword. overview 277 JUNCTION keyword. specifying 747 route enumeration. general 50 LINE keyword. TRNBUILD 932 SUPPORT keyword. default 784 wait curve. Network 381 HEADERONLY PARAMETERS keyword. Public Transport 725 GROUPS FILEO STOP2STOPO subkeyword. 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. two-way stop 309 GRAVITY Distribution control statement 573 gravity model alternative to complete formulation 565 control statement for 573 description 563 example 580. Public Transport 726 H HDWAYPERIOD PARAMETERS keyword. TRNBUILD 918 LINK keyword. Public Transport 747 HEADWAY_R LINE keyword. TRNBUILD 923 PNR keyword. specifying in 783 HEADWAY. two user class 885 keywords to avoid excessive legs 872 network development 609 nontransit network. use for 802 selecting 765 wait curve. UB2TPP 958 headway computing wait time from 799 line in reverse direction. Public Transport 765 HEADER PLOTTER keyword. overview 257 SETUP phase 155 1060 Cube Voyager Reference Guide . 581 example. geometric signals 299 JUNCTION keyword.Index H DATAPREP phase 646 example preparing public transport network 876 example. 533 Pilot control statement 96 Public Transport control statement 739 GRADE JUNCTION keyword. specifying 748 line. 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. invoking 990 examples 261–269 functions 141 ILOOP phase 160 intersection modeling 272 introduction 135 linking to Public Transport program 865 LINKREAD phase 156 logic. priority junction 330 geometric priority junctions example 335 keywords 331 GEOMETRYSOURCE Network variable 345 GLOBAL control statement. getting started 146 control statement overview 138 control statements 179 CONVERGE phase 171 convergence functions 143 convergence variables 142 Cube Cluster. LINE keyword. TRNBUILD 942 GOTO Distribution control statement 533 Fratar control statement 533 Generation control statement 533 Highway control statement 213 Matrix control statement 533. rules for 784 wait curve. select link 162 zonal loop. assigning trips to 150 HWYTIME PHASE1 keyword. overview 864 specifying 48 INPUT phase Network program 394 variable associations 396 inputs loading process. overview 277 INLIST function example 414 numeric function 36 INPUT REPORT keyword. Public Transport 627 network development. Public Transport 610 route enumeration. general control statement 50 IDP commands that disable 982 description 976 using when summarizing zonal values 984 IF COMBINE keyword.Index I variables 140 zonal loop. Public Transport 613 Cube Voyager Reference Guide 1061 . Network 390 input files See also FILEI phase-based processing. Highway 232 INCLUDELINK GENERATE keyword. TRNBUILD 915 ID. selected zone loading 163 zonal loop. TRNBUILD 913 FILEO LINKVOLO subkeyword. skim function 619 INITIALQUEUE JUNCTION keyword. Matrix 479 COMP MW subkeyword. Public Transport 659 FILEO LINKO subkeyword. utility-based model 465 COMP MW subkeyword. Network 366 FILEO NETO keyword. Highway 250 SELECT keyword. Highway 205 FILEO NETO subkeyword. common description 284 JUNCTION keyword. Network 367 JLOOP keyword. Highway 209 INCLUDECOST PATHLOAD PATHO subkeyword. Public Transport 734 incremental logit model 430 initial wait time actual. skim function 618 perceived. cost-based model 470 XCHOICE DESTSPLIT subkeyword. Highway 183 COMP MW subkeyword. 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. Public Transport 612 route evaluation. Highway 239 INCLUDEJ PATHLOAD keyword. TRNBUILD 931 I I FILEI ROUTEI subkeyword. subarea trip extraction 163 HOV facilities. Highway 215 SETPA keyword. Distribution 578 XCHOICE DESTSPLIT subkeyword. TRNBUILD 939 IBOARDFARE FARESYSTEM 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. Public Transport 700 FILEO ROUTEO subkeyword. Highway 260 INCLUDE CHOICE DESTSPLIT subkeyword. TRNBUILD 939 ILOOP phase computing volumes. Public Transport 719 Highway variable 140 Matrix built-in variable 409 REPORT VDTSPD keyword. cost-based model 463 CHOICE DESTSPLIT subkeyword. Network 393 Public Transport program. Public Transport 692 ID FILEO LINEVOLO subkeyword. Fratar 130 SETPA keywords. utility-based model 473 INCLUDE0 FILEO TURNVOLO keyword. summary 625 IWAITCURVE FACTORS keyword.Index J select-link process. Distribution 576 maximum. 171 writing output matrices. Public Transport 691 LOOKUP keyword. all-way 313 two-way stop-controlled 305 two-way yield-controlled 329 INTRA Matrix keyword 412 intrastep distributed processing. empirical roundabout 325 JUNCTION keyword. Public Transport 619 skim function. Public Transport 673 IWAITFAC FACTOR 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. summary 625 J J FILEI ROUTEI subkeyword. Public Transport 628 skimming. Distribution 566 Cube Avenue parameters 1034 highway assignment. Distribution 575 writing packet log. Public Transport 708 INTERCEPTO FILEO keyword. specifying 194 purpose 273 results file. maximum 226 maximum. Public Transit 708 INTERPOLATE FARESYSTEM FARETABLE subkeyword. Highway 143 convergence variables 142 convergence. Public Transport 719 1062 Cube Voyager Reference Guide . common 280 priority junctions 329 roundabouts 314 signal controlled 290 stop. Public Transport 618 skim function. Fratar 127 number. Cube Avenue 1025 processing. Highway 206 IWAITA skim function. 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. Cube Avenue 1015 writing path output file 206 ITERS FILEO PATHO keyword. TRNBUILD 905 IWAITMIN FACTOR keyword. Fratar distribution 123 reported. Public Transport 701 FILEO ROUTEO subkeyword. requirement for 863 output file name. specifying 203 intersections control statements 276 keywords. TRNBUILD 905 IWAITMAX FACTOR keyword. general 56 intersection modeling control statements 276 description 274 introduction 273 invoking at nodes 193 keywords 280 limitations 274 nodes invoked at. TRNBUILD 905 IWAITP skim function. Distribution 577 testing for convergence 169. Distribution 577 iterations ADJUST phase 165 assignment and capacity restraint 147 combining MATO matrices from 226 CONVERGE phase 171–178 converge phase functions. Public Transport 664 REPORT keyword. crowd-modeling runs 664 processing. Public Transport 615 INSCRIBEDDIAMETER JUNCTION keyword. Highway 202 output file name. TRNBUILD 923 SPDCAP keyword. signals 293 LANES LINK keyword. numeric items 71 print format code. Matrix 495 JOINTOFIELDS FILEI DBI subkeyword. 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. Highway variable 140 LASTZONE Cube Cluster impact 984 Matrix built-in variable 409 LAYOUTI FILEI keyword. SYNCHIMP utility 961 LEFTDRIVE FILEO NETO subkeyword. Matrix 537 JLOOP keyword. Public Transit 674 LANEADJUST JUNCTION keyword. Public Transport 742 Matrix built-in variable 409 PRINTROW keyword. Public Transport 775 TRNBUILD control statement 917 Line combining 893 LINEI Cube Voyager Reference Guide 1063 . Network 382 Public Transport control statement 745 REREPORT keyword. string items 72 LAMBDA. Network 368 PARAMETERS keyword. Highway 215 JLOOP keyword. SYNCHIMP utility 961 LAST FILEI ZDATI subkeyword. Network 392 LANESI FILEI keyword. Highway variable 140 LAMBDAA FACTORS keyword. Network 373 LASTITERATION. Highway 225 LAMBDAW FACTORS keyword. specifying 203 JUNCTIONI FILEI keyword. specifying 194 output. Public Transport 673 LAMBDASEARCH PARAMETERS COMBINE keyword. Matrix 508 MERGE keyword. SYNCHIMP utility 962 JUNCTION junction file control statement 276 junction file control statements 276 input. Cube Avenue 1003 LI. Public Transport 760 LEGEND PLOTTER keyword.LANES input field. Highway 250 SELECT keyword.name Highway array 141 LI. Network 363 Level-of-Service extraction 893 LI. Cube Avenue 1002 LI. Cube Avenue 1002 LINE PLOTTER LEGEND subkeyword.Index K Highway variable 140 JLOOP keyword. TRNBUILD 910 print format code. Highway 254 SPDCAP 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. Highway 199 FILEI ZDATI subkeyword. Matrix 496 JUNCDATAO FILEO keyword.SPDCLASS input field.CAPCLASS input field. Network 381 LEN FILEI LINKI VAR subkeyword. Network 375 LEFTSTR 39 LEG NT keyword. overview 277 JUNCTION keyword. general 74 REPORT VDTSPD keyword. Highway 194 JUNCTIONO FILEO keyword. Distribution 574 L L FARELINKS keyword. setting 253 listing in print file. selecting 630 drawing. Highway 260 links arrays supporting 141 centroid connectors 1036 computing walk and transit times 878 confidence level value 722 Cube Avenue packets. Public Transport 756 merging records from multiple files. Public Transport 710 FILEO keyword. TRNBUILD 914 LINKOFFSET PLOTTER keyword. TRNBUILD 936 LINESTRING REPORT keyword. Highway variable 140 LINKNUM. TRNBUILD 950 LINKCLASS Highway variable 140 setting. example in Cube Avenue 1035 value computed. Highway 233 LINKIDLASTUSE PATHLOAD LINKIDARRAY subkeyword. Network 365 FILEO keyword. identifying 628 travel time computation. base 767 travel demand on. loading 230 restricted use by mode 723 speed on. maximum 733 one-way. Public Transport 755 variables supporting 140 walk 798 1064 Cube Voyager Reference Guide . TRNBUILD 931 LINKI FILEI keyword. TRNBUILD 935 report produced. non-input network 755 transit line time. Highway function 142 LINKO FILEO keyword. SYNCHIMP utility 962 FILEO keyword. example 401 loops for processing. Public Transport 711 REPORT keyword. See transit lines LINESORT REPORT LINEVOL 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. eliminating 371 group codes for.Index L FILEI keyword. Public Transport 776 LINEO FILEO keyword. example 401 nontransit leg. example 401 duplicate. characteristics of 379 dumping to DBF files. Highway 233 LINKIDMW PATHLOAD LINKIDARRAY subkeyword. TRNBUILD 913 LINEVOLS REPORT keyword. example 793 REREPORT keyword. Network 377 drawn. Public Transport 708 LINES FILEO LINKO subkeyword. Cube Avenue 1002 LINKDUMP PHASE1 keyword. Public Transport 773 LINEZONLEG1 REREPORT keyword. Network 382 LINKPOST PLOT keyword. Highway 233 LINKIDCNTMW PATHLOAD LINKIDARRAY subkeyword. nontransit legs 735 output file. Highway 233 LINKIDARRAY PATHLOAD keyword. TRNBUILD 935 LINEVOL REPORT keyword. specifying in Public Transport 710 path. specifying 1016 demand using. Network 378 LINKREAD phase Cube Avenue 1001 Highway program 156 Public Transport program 645 stack for. Public Transport 777 LINK TRNBUILD control statement 922 ZONEACCESS keyword. TRNBUILD 935 LINEVOLO FILEO keyword. Public Transport 697 LINELINELEG REREPORT keyword. Public Transport 772 REPORT keyword. Highway LINKREAD phase 158 variable. Public Transport 776 LINEZONLEG2 REREPORT keyword. Public Transport 776 lines. Network 360 LINKID#MW PATHLOAD LINKIDARRAY subkeyword. Public Transport 781 WAITCRVDEF keyword. Public Transport 663 LOOKUP control statement. Network 375 LISTERRS FILEI RECI subkeyword. Highway 218 input zones. Public Transport 692 LINE keyword. TRNBUILD 936 LINKVOLO FILEO keyword. general 55 LOOKUP NAME subkeyword. Highway 197 FILEI TURNPENI subkeyword. Highway 194 FILEI keyword. practical considerations 450 mode and destination choice 445 scale parameters 450 lognormal distribution function 36 inverse function 36. Public Transport 759 OPERATOR keyword. 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. standard 53 impact on Cube Cluster 983 numeric function. Public Transport 734 LOOKUP keyword. Matrix 497 FILEI keyword. TRNBUILD 928 LISTLINK SUPPORT keyword. Public Transport 757 general. TRNBUILD 942 LN 36 LOADDISTFAC LINE keyword. details about 738 GENERATE keyword. Public Transport 748 VEHICLETYPE keyword. Public Transport 697 FILEI SYSTEMI subkeyword. Public Transport 695 FILEI FAREI subkeyword. 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. Public Transport 696 FILEI LINEI subkeyword. general 57 LOOKUPI FILEI keyword. general 56 PRINT keyword. Public Transport 762 VEHICLETYPE keyword. Public Transport 842 trip matrix into public transport network 883 LOG control statement. Network 364 FILEI keyword. Public Transport 703 FILEI TURNPENI subkeyword. Public Transport 705 FILEO PAO subkeyword. Public Transport 782 LONGNAMECROSDCRVDEF keyword. Public Transport 781 loading analyses mode transfers 639 operator transfers 639 overview 638 stop-to-stop movements 639 loading process overview. Generation 591 FILEO STOP2STOPO subkeyword. general 68 REPORT MARGINREC subkeyword. Pilot 95 LOOKUP keyword. Cube Avenue 1037 jumping to end 354 link records. including in 711 summing output by user class 711 LINKVOL REPORT keyword. Network 352 FILEI FACTORI subkeyword. Matrix 550 ZONEACCESS GENERATE subkeyword 949 LIST_ERRS PARAMETERS keyword.Index L links file defining output 710 lines data. Public Transport 626 theory. Highway 217 Cube Voyager Reference Guide 1065 . Public Transport 726 GENERATE keyword. Public Transport 748 MODE keyword. TRNBUILD 914 LIST COMPARE keyword. Matrix 505 LISTINPUT PARAMETERS keyword. 36 LOGNORMDIST numeric function 36 LOGNORMINV numeric function 36 LONGNAME FARESYSTEM keyword. Matrix 538 general variable. Distribution 574 LOTMODE PNR keyword. UB2TPP 958 Public Transport phase 651 MATOADJUST PARAMETERS keyword. TRNBUILD 911 FILEI keyword. built-in 409 MATSTAT REPORT keyword. Matrix 482 Highway function 142 Matrix built-in function 410 matrix function. Highway 185–188 intrazonal cells. Matrix 550 MATVAL COMP function. Public Transport 674 MAXCOST GENERATE keyword. Network 375 MAXCOMPD FACTORS keyword. overview 278 MAPSCALE PARAMETERS keyword. invoking 990 examples 555 functions. UB2TPP 957 Public Transport phase 647 MATO FILEO keyword. Public Transport 698 FILEI keyword. Highway 184 MATRIX TRIPS keyword. Public Transport 741 matrix columns. Matrix 549 MARGINS impact on Cube Cluster 983 PLOTTER keyword. Highway 186 LOWEST COMP function.name. Highway 194 FILEI keyword. Highway 215 terminating. Distribution 575 PARAMETERS keyword. Highway 186 LTRIM. Matrix 481 Highway function 142 Highway variable 140 Matrix built-in variable 409 matrix function. Highway 226 MATOEVERY PARAMETERS keyword. Network 382 MAPWINDOW PLOTTER keyword.Index M link records. Matrix 540 MAX FILEI ZDATI subkeyword. Fratar 127 MATRICES TRNBUILD control statement 924 matrices applying part to logit model 449 functions. Highway 199 FILEI ZDATI subkeyword. TRNBUILD 945 Matrix program control statements. list of 451 control statements. COMP statement 481 introduction 407 variables. Public Transport 714 FILEO keyword. Public Transport 735 1066 Cube Voyager Reference Guide . Highway array 141 M MAJORROADWIDTH JUNCTION keyword. Public Transport 665 using to control run order 81 LOS GRAVITY keyword. Matrix 508 MERGE keyword. Distribution 574 LOSRANGE GRAVITY keyword. TPP2UB 959 FILEI keyword. Network 383 REPORT keyword. Highway 203 FILEO keyword. character function 39 LW. matrix 482 Matrix built-in function 410 MATVALCACHE PARAMETERS keyword. Matrix 550 MATI FILEI keyword. built-in 410 functions. Network 373 numeric function 36 MAX_IP_ERRS PARAMETERS keyword. Public Transport 756 matrices. Matrix 518 FILEO keyword. Network 383 MARGINREC impact on Cube Cluster 983 REPORT keyword. TPP2UB 959 FILEO keyword. TRNBUILD 915 FILEO keyword. Matrix 535 matrix column cells. Matrix 498 FILEI keyword. geometric priority junctions 333 JUNCTION keyword. working with 412 value limitations 521 variables. Public Transport 765 PLOTTER keyword. TRNBUILD 932 LOWCNT COMP function. types 411 Cube Cluster. Index M MAXDIFF COMBINE keyword. TRNBUILD 949 MAXMSG PATHLOAD SUBAREAMAT subkeyword. Highway 226 PARAMETERS keyword. Highway 226 MAXLINKDELAY FILEI TURNPENI subkeyword. TRNBUILD 950 MAXSTRING PARAMETERS keyword. Network 390 MESSAGE CONSOLE subkeyword 48 SENDMAIL keyword. Network 373 numeric function 36 MINCOST GENERATE keyword. Highway 242 MAXMW PARAMETERS keyword. TRNBUILD 947 ZONEACESS GENERATE subkeyword. Matrix 540 PARAMETERS keyword. common description 284 Cube Voyager Reference Guide 1067 . TRNBUILD 927 MAXPERLINE PRINTROW keyword. Highway 226 PARAMETERS keyword. Fratar 128 MAXRECS FILEI DBI subkeyword. TRNBUILD 904 MAXDIST SEGLIMITS keyword. Matrix 506 MAXSTOPS ZONEACESS GENERATE subkeyword. Public Transport 675 MAXFIELDS FILEO MATO subkeyword. TRNBUILD 928 MAXSCAN FILEI RECI subkeyword. TRNBUILD 938 XFERGEN keyword. Matrix 540 PARAMETERS keyword. Distribution 576 PARAMETERS keyword. TRNBUILD 938 MAXTIMEDIFF MULTIACCESS keyword. Public Transport 769 zone pairs without valid routes 766 MEUSESNT FILEO SCREENLINEO subkeyword. Pilot 112 message 770 765 messages displaying 48 excessive travel time 763 zonal timing. Public Transport 765 MIN FILEI LINKI VAR subkeyword. Public Transport 723 PARAMETERS keyword. Highway 229 zonal timing. Public Transport 706 MAXLINKS ZONEACESS GENERATE subkeyword. Public Transport 695 FILEI LINEI subkeyword. Matrix 523 MAXITERS convergence testing calculation 172 PARAMETERS keyword. TRNBUILD 931 MAXNTLEGS GENERATE keyword. TRNBUILD 906 MDP 978 MERGE Network control statement 371 REPORT keyword. general 74 MAXPTHPERSEG PARAMETERS keyword. TRNBUILD 928 MAXPCTDIFF MULTIACCESS keyword. Public Transport 735 MINGROUPSIZE DISTRIBUTEINTRASTEP keyword. Matrix 496 FILEI RECI subkeyword. Matrix 541 zonal timing. Public Transport 697 FILEI RECI subkeyword. Pilot 104 MAXTIME PNR keyword. TRNBUILD 927 MAXWAITTIME FACTOR keyword. Matrix 505 MAXRMSE PARAMETERS keyword. Fratar 127 PARAMETERS keyword. Network 363 FILEI ZDATI subkeyword. TRNBUILD 949 MAXERRS FILEI FACTORI subkeyword. Matrix 508 MERGE keyword. Matrix 505 MAXFERS FACTORS keyword. Cube Cluster 991 minimum system requirements 7 MINIMUMCAPACITY JUNCTION keyword. Fratar 128 MAXRUNTIME PARAMETERS keyword. TRNBUILD 932 SEGLIMITS keyword. Distribution 576 PARAMETERS keyword. Highway 199 FILEI ZDATI subkeyword. Cube Avenue 1022 MAXPURPS PARAMETERS keyword. Public Transport 735 MAXPATHTIME PARAMETERS keyword. Public Transport 765 MAXNODE PHASE1 keyword. Cube Cluster 987 multistep distributed processing. Public Transport 676 1068 Cube Voyager Reference Guide . Matrix 452 ABORT keyword. Public Transport 748 LINE keyword. TRNBUILD 918 NT keyword. theory 825 evaluating routes with 827 specifying 676 MUSTUSEMODE FACTORS keyword. Public Transport 664 Cube Avenue 1022 duration. prohibiting 670 fare model 672 intercept data and 765 limiting selected routes to 807 link use restricted 723 logit choice model 422 must-use. Matrix 546 MO FILEO MATO keyword. TRNBUILD 908 model period crowd model. TRNBUILD 950 mode-and-destination-choice model 445 MODEFAC FACTOR keyword. Highway 197 FILEI TURNPENI subkeyword. TRNBUILD 937 SEGLIMITS keyword. Public Transport 715 MODE FACTORS FARESYSTEM subkeyword. TRNBUILD 936 REPORT NODEVOL subkeyword. overview 278 MSG ABORT keyword. TRNBUILD 942 modes access connectors. Cube Avenue 1016 must-use mode enumerating routes with. TRNBUILD 950 ZONEACESS GENERATE subkeyword. Public Transport 672 LINE keyword. TRNBUILD 936 REPORT LINKVOL subkeyword. TRNBUILD 916 LINK keyword. Public Transport 761 PNR keyword. TRNBUILD 910 FILEO NETO subkeyword. Public Transport 676 MUSTMEETALL FILEO PACKETLOG subkeyword. TRNBUILD 923 REPORT LINEVOL subkeyword. selecting 633 egress connectors. See MDP MUMEXTRACOST FACTORS keyword. TRNBUILD 938 SUPPORT keyword. Cube Avenue 1022 PARAMETERS keyword. theory on 821 generation process 686 maximum transfers permitted 667 MINUTP 953 MISSINGLINK FILEI TURNPENI subkeyword. 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. Highway 204 FILEO MATO subkeyword. report 795 turn-penalty free 706 MODES subkeyword FILEO STOP2STOPO. Public Transport 727 MOVEMENT JUNCTION keyword. Matrix 546 MISSINGZO RENUMBER keyword. Public Transport 654 MULTIACCESS TRNBUILD control statement 927 MULTISTEP DISTRIBUTE keyword. overview 278 minimum-cost routes finding. Public Transport 706 MISSINGZI RENUMBER keyword. TRNBUILD 905 MODEFARE FARE keyword. enumerating routes with 825 required in transit route 676 required. TRNBUILD 933 Public Transport control statement 758 SUPPLINK keyword. TRNBUILD 947 ZONEACCESS LINK subkeyword. Network 348 ABORT keyword. TRNBUILD 915 FILEO SUPPORTO subkeyword. common description 285 JUNCTION keyword.Index M JUNCTION keyword. TRNBUILD 940 XFERGEN keyword. Public Transport 803 MODELPERIOD PARAMETERS keyword. junction file 194 Highway program 227 modeling approaches. Matrix 524 FILEO MATO subkeyword. Highway 227 MODES FARELINKS keyword. extra cost allowed 676 stop-to-stop movement data collected 727 transfer penalty 800 transfers between. Highway 180 ABORT keyword. Generation 591 FILEO TURNVOLO keyword. Highway 256 NAME CROWDCRVDEF keyword. Matrix 478 COMP keyword. Highway 209 naming conventions string variables. general 57 MATRICES keyword. Highway 234 PRINTROW keyword. TRNBUILD 918 LOOKUP keyword. Highway 196 NETITOLLROAD FILEI TOLLMATI subkeyword. input file 699 Cube Voyager Reference Guide 1069 . introduction 135 Highway.Index N MW COMP keyword. Highway 182 COMP keyword. Public Transport 781 WAITCRVDEF keyword. Highway 206 LINE keyword. Public Transport 762 PATHLOAD PATHO subkeyword. Highway 204 FILEO MATO subkeyword. 925 MODE keyword. Highway 194 Network variable 345 REREPORT keyword. Public Transport 716 FILEO keyword. Public Transport 718 NETI FILEI keyword. Public Transport 692 FILEI DBI subkeyword. Public Transport 782 NAMES FILEO PAO subkeyword. Public Transport 876 development process overview. Matrix 527 FILEO SUBAREAMATO keyword. Fratar 131 N N FILEI JUNCTIONI subkeyword. Public Transport 777 substituting for NODES. 398 public transport. Public Transport 759 OPERATOR keyword. general 57 NET FILEO LINEO subkeyword. Matrix 497 FILEI RECI subkeyword. Network 366 FILEO keyword. TRNBUILD 940 TURNS keyword. Public Transport 746 LINE keyword. Highway 202 FILEO MATO keyword. Highway 196 NETO 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. Highway 196 NETIEXIT FILEI TOLLMATI subkeyword. Matrix 524 FILEO MATO subkeyword. TRNBUILD 919 SUPPLINK keyword. Public Transport 699 FILEI keyword. Public Transport 658 FILLMW keyword. Network 351 variables. generating nontransit legs 730 public transport. Public Transport 715 FILEO RECO subkeyword. Matrix 531 function description 34 Highway array 141 Matrices keyword. input file 194 highway. general 43 NEAREST LOOKUP keyword. Highway 240 VEHICLETYPE keyword. processing 343 highway. general 74 SETPA keyword. Highway 194 FILEI keyword. Highway 199 FILEO ESTMDATO keyword. Public Transport 663 FARESYSTEM keyword. revising speed and capacity 254 input data files 359 output file 365 plotting 398. output file name 205 highway. Public Transport 709 FILEO NTLEGO subkeyword. Matrix 506 FILEI ZDATI subkeyword. developing 646 public transport. Highway 205 FILEO keyword. Public Transport 609 highest node number 376 highway. TRNBUILD 911 NETIENTRY FILEI TOLLMATI subkeyword. TRNBUILD 926 Matrix built-in variable 409 PATHLOAD keyword. including in 777 stop. Distribution 588 NNTIME LINE NODES subkeyword. Highway 236 NODE JUNCTION keyword. transfer points 685 wait-time weighting factor for 682 NODES. Public Transport 866 times. preparing 603 simplification of. SYNCHIMP utility 962 FILEO keyword. intermediate 761 nontransit legs. TRNBUILD 940 SUPPORT keyword. Network 368 FILEO keyword. selecting 632 turning volumes accumulated 256 wait curve associated 673 wait curve associated. Cube Avenue 1016 destination. Cube Avenue 1022 nontransit leg. TRNBUILD 919 LINK keyword. Network 377 fare zones 852 highest number in network 376 intersection modeling invoked at 194 maximum in RAM. avoiding 872 generating 730 generating. nontransit legs 734 output. TRNBUILD 923 SUPPLINK keyword. Public Transport 808 speeds. Network 376 NODEVOL REPORT keyword. output file 716 public transport. including in Public Transport 718 Public Transport report. TRNBUILD 948 NODEI FILEI keyword. 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 . TRNBUILD 915 NODEPOST PLOT keyword. Network 364 NODEMERGE phase description 394 variable referencing 396 NODEO FILEO keyword. number in 376 NEWPAGE Pilot control statement 100 NHB BALANCE keyword. Network 378 NODEREAD Public Transport phase 644 NODES FACTOR MAXWAITTIME subkeyword. Cube Avenue 1016 origin.Index N Public Transport. starting 993 destination. Public Transport 866 zones. transit line flag 746 stop-to-stop movements collected for 727 transit line 749–753 travel demand on. identifying 628 travel demand on. common description 286 JUNCTION keyword. Public Transport 673 FACTORS WAITFACTOR subkeyword. Public Transport 749 PARAMETERS keyword. portion allocated to 673 approaches at 280 Cube Cluster processing. TRNBUILD 943 nodes alighting. Public Transport 751 NOACCESS PATHLOAD MW subkeyword. FACTORS IWAITCURVE subkeyword. including in report 774 stop. nontransit legs 737 drawing. Public Transport 685 FILEO STOP2STOPO subkeyword. TRNBUILD 906 LINE keyword. overview 278 PNR keyword. TRNBUILD 936 nontransit legs direction 733 excessive. TRNBUILD 933 XY keyword. Public Transport 682 FACTORS XWAITCURVE subkeyword. Public Transport 727 Highway variable 140 LINE keyword. start and finish 760 origin. TRNBUILD 920 LINK keywords. Public Transport 711 NTLEGI FILEI keyword. Public Transport 735 LINE keyword. Cube Avenue 1016 output files See also FILEO naming 49 Pilot program 81 Cube Voyager Reference Guide 1071 . Public Transport 752 ONELINKREC FILEO LINKO subkeyword. Public Transport 663 FARESYSTEM keyword. cost-based model 463 CHOICE keyword. numeric function 37 NORMINV. TRNBUILD 950 ONLINE CONSOLE subkeyword 48 PARAMETERS keyword. selecting 633 fare model 672 transit line 753 ORIGIN FILEO PACKETLOG subkeyword. working matrix 73 size limits 521 NUMLINKS. TRNBUILD 923 NT keyword. TRNBUILD 910 FILEO SUPPORTO subkeyword. Public Transport 766 NOTMODES FILEI TURNPENI subkeyword. Highway variable 140 NumReadyNodes function 994 NUMRECS SORT keyword. cost-based model 463 OCOMPUTIL CHOICE keyword. numeric function 37 NOROUTEERRS PARAMETERS keyword. Public Transport 713 ONRUNERRORGOTO Pilot control statement 100 OPERATOR FACTORS FARESYSTEM subkeyword. Public Transport 692 MODE keyword. Public Transport 700 NTLEGMODE GENERATE keyword. TRNBUILD 946 OMITFARES FILEI FACTORI subkeyword. all-way stop 313 JUNCTION keyword. Public Transport 717 NTLEGS FILEO LINKO subkeyword. Public Transport 759 OPERATOR keyword. general 76 O OCOMPCOST CHOICE keyword. Public Transport 753 Public Transport control statement 762 operators defining 762 demand using. TRNBUILD 929 ONOFFS FILEO LINKO subkeyword. Public Transport 712 ONEWAY FARELINKS keyword.Index O inverse function 37 NORMDIST. Public Transport 752 OLINKS TRIPS MATRIX ASSIGN subkeyword. TRNBUILD 905 NT Public Transport control statement 759 NTBYLINK FILEO LINKO subkeyword. Public Transit 672 LINE keyword. utility-based model 466 ODEMAND CHOICE keyword. Public Transport 782 NUMBEROFLANES JUNCTION keyword. TRNBUILD 943 ZONEACCESS LINK subkeyword. utility-based model 466 ODEMANDMW XCHOICE keyword. TRNBUILD 916 GENERATE keyword. Public Transport 762 VEHICLETYPE keyword. Public Transport 761 PNR keyword. Public Transport 695 ON LINE NODES subkeyword. Public Transport 781 WAITCRVDEF keyword. cost-based model 470 XCHOICE keyword. utility-based model 473 OFF LINE NODES subkeyword. TRNBUILD 933 SUPPLINK keyword. Public Transport 712 null blocks 25 NUMBER CROWDCRVDEF keyword. Public Transport 706 NOX FACTOR keyword. overview 278 numbers print format 67 print format. TRNBUILD 940 SUPPORT keyword. Public Transport 753 LINE keyword. Public Transport 735 NTLEGO FILEO keyword. Public Transport 766 NOROUTEMSGS PARAMETERS keyword. general 50 PAO FILEO keyword. Cube Cluster 988 outputs loading process. Generation 594 SETPA keyword. Highway 239 PATHOGROUP PATHLOAD PATHO subkeyword. general 50 PAGEWIDTH GLOBAL keyword. generating report of 772 statistics.Index P Public Transport program 864 waiting for subprocess. Fratar 131 P2A BALANCE keyword. Pilot 108 SYNCHIMP control statement 962 TPP2UB control statement 960 TRNBUILD control statement 928 UB2TPP control statement 958 PARKINGMANEUVERS JUNCTION keyword. Highway 205 impact on Cube Avenue 1024 impact on Cube Cluster 983 PATHLOAD keyword. Public Transport 627 network development. skimming 841 utility. Matrix 501 FILEO MATO subkeyword. Highway 240 PATHSTYLE PARAMETERS keyword. Matrix 525 PC REPORT keyword. Generation 588 PACKETLOG FILEO 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 . Public Transport 610 route enumeration. example report 793 hours. example report 793 distance. Pilot 112 PATH FILET keyword. Matrix 530 PATHLOAD keyword. geometric signals 299 JUNCTION keyword. Generation 594 PCOMP REPORT keyword. Public Transport 615 P P COMP keyword. Fratar 128 PDIFF convergence testing calculation 172 Highway variable 142 PARAMETERS keyword. Public Transport 613 skimming. Distribution 579 SETPA keyword. Public Transport 612 route evaluation. Highway 211 FILET 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. Cube Avenue 1015 PAGEHEIGHT GLOBAL keyword. overview 278 passenger loadings analyses 638 assigning 626 example report 884 report example 794 passengers assigning to trips 626 denied boarding 799 distance. TRNBUILD 929 PATHTRACE Highway function 142 PATTERN FILEI MATI subkeyword. specifying for nontransit legs 761 PASSWORD SENDMAIL keyword. Generation 589 REPORT keyword. improving with new service 828 volume. generating report 772 flow-metered volume 760 hours. 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. geometric signals 300 JUNCTION keyword. Public Transport 637 PERIOD CROWDMODEL keyword. Fratar 131 PGM RUN keyword. Highway 240 REPORT 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 . two-way stop 309 PEDESTRIANPHASE JUNCTION keyword. Highway 241 PERCENT select-link expression keyword. Generation 593 PROCESS keyword. Highway 227 PEDESTRIANFLOW JUNCTION keyword. perceived. skim function 621 transfer. skim function 621 PENI PATHLOAD keywords. actual. Network program 394 NODEREAD. Highway 194 PGF SETPA keyword. signals 294 PHASINGI FILEI keyword. geometric signals 299 JUNCTION keyword. 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. Network program 395 PHASES. Pilot 109 PHASE JUNCTION keyword. Network program 395 Network program 393 NODEMERGE. Network program 394 LINKMERGE. Network 388 PHASE1 TRNBUILD control statement 930 phases defining in scripts 248 INPUT. Highway 250 PENIFACTOR PATHLOAD keyword. SYNCHIMP utility 962 PILOT example. Public Transport 664 FILEI JUNCTIONI subkeyword. skim function 621 boarding. Highway 249 PROCESS keyword. Cube Avenue 1022 PLANID PARAMETERS keyword. two-way stop 309 penalty boarding. Public Transport 644 Public Transport program 641 SUMMARY. overview 278 JUNCTION keyword. signals 293 PROCESS keyword. SYNCHIMP 963 PLATESIZE PLOTTER keyword. perceived. Public Transport 669 transfer.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. JUNCTION keyword. overview 278 JUNCTION keyword. geometric signals 299 PEDESTRIANSPEED JUNCTION keyword. Index P inverse function 37 POISSONDIST numeric function 37 POISSONINV numeric function 37 PORT SENDMAIL keyword. example 335 geometric. 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 69 PRINTROW control statement. example 876 loading trip matrix. Cube Cluster 991 PROCESSNUM DISTRIBUTEMULTISTEP keyword. 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. example 338 saturation-flow. general 67 PRINT PRINTO subkeyword. TPP2UB 960 1074 Cube Voyager Reference Guide . Network 385 POSTLINKVAR PLOTTER keyword. general 66 Distribution control statement 542 FILEO PAO subkeyword. Cube Cluster 991 DISTRIBUTEMULTISTEP keyword. Distribution 574 PARAMETERS keyword. Highway variable 140 PROMPT Pilot control statement 105 public transport network developing. Pilot 112 POST PLOTTER POSTLINKVAR subkeyword. Matrix 525 FILEO keyword. Public Transport 718 PRINT keyword. keywords 331 keywords 330 overview 329 saturation-flow. general 55 PRINT control statement. Highway 206 FILEO keyword. overview 605 routes. Network 368 FILEO keyword. finding 603 skimming 604 system data input file 703 terminology 605 PURPOSE GRAVITY keyword. Cube Cluster 988 program features 5 PROJECTLINK. Pilot 95 FILEO keyword. Cube Cluster 988 PROCESSLIST DISTRIBUTEINTRASTEP keyword. 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. general 69 Public Transport control statement 771 REPORT MARGINREC subkeyword. Network 385 POW 37 PREFIX LOG keyword. Matrix 550 PRINTFILES WAIT4FILES keyword. Public Transport 637 PROCESS Generation control statement 592 Highway control statement 248 Network control statement 388 PROCESSID DISTRIBUTEINTRASTEP keyword. Cube Cluster 990 printing defining character formats 71 defining numeric formats 70 example listing links in 401 PRINTO FILEO keyword. Pilot 109 PROBABILITY select-link expression keyword. Network 384 POSTNODEVAR PLOTTER keyword. details 786 reports. keywords 336 PRNFILE RUN keyword. Network 361 RENUMBER Fratar control statement 543. Highway 251 READ control statement. Pilot 109 REDIRECTOUT RUN keyword. common description 286 JUNCTION keyword. Network 356 FREQUENCY keyword.RECNO Matrix built-in variable 409 RECO FILEO keyword.RECERR Matrix built-in variable 409 RECI.NUMRECORDS Matrix built-in variable 409 RECI. general 75 READNTLEGI GENERATE keyword. Matrix 533 Cube Voyager Reference Guide 1075 . Pilot 105 R R LOOKUP keyword. overview 278 RANDSEED 37 RANGE CROSSTAB COL subkeyword. Network 376 REPLACESTR 39 REPLACESTRIC 39 REPORT Distribution control statement 576 FILEO RECO subkeyword. Matrix 503 impact on Cube Cluster 983 RECI processing Matrix program 417 RECI. Public Transport 677 REDIRECTIN RUN keyword. Highway 227 REMOVEFROMGROUP SETGROUP keyword.Index Q Q QUESTION PROMPT keyword. Network 352 MERGE keyword. numeric items 71 print format code. Matrix 525 WRITE keyword. Highway 253 RENAME FILEI LINKI subkeyword. Public Transport 676 RECI FILEI keyword. Network 372 RECOSTMAX FACTORS keyword. Matrix 554 RECO processing Matrix program 417 RECORD COMPARE keyword. Public Transport 736 REBESTPATHCOST FACTORS keyword. Pilot 109 RELATIVEGAP 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.NUMFIELD Matrix built-in variable 409 RECI. Network 355 CROSSTAB ROW subkeyword. general 58 print format code. string items 72 RAAD convergence testing calculation 172 Highway variable 142 PARAMETERS keyword. Matrix 533 REPORT VDTSPD keyword. Matrix 527 Fratar control statement 128 FREQUENCY keyword. 543 impact on Cube Cluster 983 REPL_DUP 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 . 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. Public Transport 720 REPORTO FILEO keyword. Public Transport 701 FILEO ROUTEO subkeyword. example 789 REPORTJ FILEI ROUTEI 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. Network 362 REVERSESTR 39 REWAITMAX FACTORS keyword. Public Transport 701 FILEO ROUTEO subkeyword. general 67 PRINT PRINTO subkeyword. Public Transport 718 reports enumerated routes 787 evaluated routes 788 fare matrices 792 public transport network 774 Public Transport. Public Transport 678 REWAITMIN FACTORS keyword. Public Transport 720 produced report. general 57 RESUME CLEARERROR keyword 89 REV FILEI LINKI subkeyword. Public Transport 678 REWIND PRINT FILE subkeyword.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. Highway 187 ROWCNT COMP function. Highway 188 ROWMPY COMP function. keywords 316 example. Highway 187 ROWFAC COMP function. Network 355 ROWADD COMP function. empirical 325 example. Matrix 484 Highway function 141 Matrix built-in function 410 matrix function. Highway 188 ROWREAD COMP function. Highway 188 RT LINE NODES subkeyword. Matrix 485 ROWSUM COMP function. Highway 187 ROWMAX COMP function. TRNBUILD 937 Cube Voyager Reference Guide 1077 . Public Transport 754 relation to RT. 483 Highway function 141 Matrix built-in function 410 matrix function. not using 670 must-use mode. 483 Highway function 141 Matrix built-in function 410 matrix function. Public Transport 611 required transit modes 676 theory 820 transit connectors. Matrix 485 Highway function 141 Matrix built-in function 410 matrix function. Matrix 484 Highway function 141 Matrix built-in function 410 matrix function.Index R function for BALANCE 177 Highway function 145 ROUND. Matrix 483 Highway function 141 Matrix built-in function 410 matrix function. Highway 188 ROWMIN COMP function. Matrix 483 Highway function 142 Matrix built-in function 410 matrix function. Matrix 484 Highway function 141 Matrix built-in function 410 matrix function. theory 825 overview 603 process overview. TRNBUILD 920 RUNTIMEADJ REPORT keyword. finding 821 modes. Highway 187 ROWAVE COMP function. theory 824 maximum transfers in route 670 minimum-cost routes. Highway 187 ROWDIV COMP function. Public Transport 700 ROUTEO FILEO subkeyword. Matrix 483 Highway function 141 Matrix built-in function 410 matrix function. including in cost 764 initial wait time 673 overview 603 process overview. Public Transport 679 RUNTIME LINE keyword. Public Transport 719 ROW CROSSTAB keyword. Public Transport 752 LINE NODES subkeyword. Matrix 483. Matrix 483 Highway function 141 Matrix built-in function 410 matrix function. numeric function 37 roundabouts empirical. gap-acceptance 328 keywords. TRNBUILD 920 RUN Pilot control statement 107 RUNFACTOR FACTORS keyword. Highway 187 ROWFIX COMP function. gap-acceptance 327 overview 314 route enumeration components generated 674 determining routes. finding 822 route evaluation fares. TRNBUILD 921 LINE NODES subkeyword. Public Transport 612 required transit modes 676 theory 826 route file format 768 ROUTEI FILEI keyword. Matrix 483. Public Transport 702 FILEO ROUTEO subkeyword. Matrix 509 PNR keyword. Public Transport 679 SET Distribution control statement 552 FILEI JUNCTIONI subkeyword. converting output to Cube Voyager format 964 SAVEPRN DISTRIBUTEINTRASTEP keyword. Highway 203 screenline file creating 863 SCREENLINEI FILEI keyword. 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. Network 362 FILEI ZDATI subkeyword. TRNBUILD 934 TRNBUILD control statement 938 select link process. Highway 200 FILEI ZDATI subkeyword. Public Transport 720 SELECTGROUP FILEO PACKETLOG subkeyword. Public Transport program 628 SELECTBYMAT FILEI ROUTEI 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 702 SCREENLINEO FILEO keyword. Highway 236 SELECTIJ Public Transport phase 649 SELECTLINK FILEO PACKETLOG subkeyword. numeric items 71 SAME FARESYSTEM STRUCTURE subkeyword. 338 Saturn. Public Transport 707 SETUP phase Cube Avenue 1001 Highway program 155 SETUPPER LOOKUP keyword. Cube Cluster 991 scientific format 70 SCREENLINE FILEO ESTMICPO subkeyword. Public Transport 693 SATFLOWPERLANE JUNCTION keyword. signals 294 saturation flow 302. Highway 238 SENDMAIL Pilot control statement 111 SEQSIZE PARAMETERS keyword. Cube Avenue 1016 PATHLOAD MW subkeyword. general 58 signals fixed-time. Public Transport 722 SCREENVAR FILEO SCREENLINEO subkeyword. overview 278 JUNCTION keyword. saturation-flow priority junctions 338 JUNCTION keyword. Public Transport 754 VEHICLETYPE keyword. Cube Avenue 1016 PATHLOAD MW subkeyword. Cube Avenue 1023 SELECT FILEI LINKI subkeyword. example 302 1078 Cube Voyager Reference Guide . Public Transport 723 SEATCAP LINE keyword. Public Transport 781 SEGLIMITS TRNBUILD control statement 937 SEGMENTS PARAMETERS keyword.Index S S S print format code. TRNBUILD 929 service-frequency mode example 836 SERVICEMODEL FACTORS keyword. two-way stop 309 SIZE LOOKUP keyword. Pilot 112 SORT control statement. example in Cube Avenue 1035 SPDCAP keyword. Public Transport 761 REPORT keyword. cost-based model 471 XCHOICE keyword. TRNBUILD 939 SLACK GENERATE keyword. Public Transport 773 SPDCAP Highway control statement 254 Network control statement 392 SPDCODE LINK keyword. cost-based model 464 CHOICE keyword. cost-based model 471 SPREAD definition 681 Cube Voyager Reference Guide 1079 . Network 392 SUPPLINK keyword. Highway LINKREAD phase 158 variable. Public Transport 697 PARAMETERS keyword. cost-based model 470 XCHOICE SPLIT subkeyword. utility-based model 474 SPLITCOMP XCHOICE SPLIT subkeyword. Public Transport 752 LINE NODES subkeyword. 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. geometric 296 overview 290 saturation flow. TRNBUILD 924 SPEED Highway variable 140 LINE NODES 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. utility-based model 467 XCHOICE keyword. Network 390 REPORT keyword.Index S geometric. Network 351 Highway function 142 Network function 346 SPLIT CHOICE keyword. general 76 Cube Cluster impact 983 Distribution control statement 553 FILEI DBI subkeyword. Public Transport 773 REPORT LINEVOLS subkeyword. Highway 254 SPDCAP keyword. generic 291 keywords. cost-based model 471 SPLITINTO CHOICE DESTSPLIT subkeyword. Cube Avenue 1003 SPEEDFOR COMP function. TRNBUILD 940 SUPPORT keyword. TRNBUILD 943 value computed. Public Transport 714 REPORT LINES subkeyword. Highway 250 REPORT keyword. cost-based model 463 CHOICE SPLIT subkeyword. overview 278 JUNCTION keyword. Matrix 497 FILEI RECI subkeyword. Public Transport 614 quick reference 625 theory 839 SKIP0 FILEO LINKO subkeyword. Public Transport 736 SMTPSERVER SENDMAIL keyword. priority junctions 330 JUNCTION keyword. signals 295 JUNCTION keyword. cost-based model 464 XCHOICE DESTSPLIT subkeyword. TRNBUILD 937 setting. TRNBUILD 920 LINK keyword. Public Transport 773 SKIPBADLINES FILEI LINEI subkeyword. example 300 keywords. example 302 SIN 38 SINGLELANE JUNCTION keyword. Public Transport 766 SKIPMODES SELECT keyword. TRNBUILD 924 NT keyword. TRNBUILD 915 SYMBOL PLOTTER LEGEND subkeyword. See two-way stops. Network 362 STOP2STOPO FILEO keyword. example in Cube Avenue 1035 variable. Pilot 113 subkeywords 29 SUBSTR 39 SUM FILEI ZDATI subkeyword. Highway 256 T0 Highway variable 140 setting. Public Transport 774 REPORT LINKVOL subkeyword. Highway 241 SUBAREAMATO FILEO keyword. Public Transport 727 STOPNODES REREPORT keyword. Highway 200 FILEI ZDATI subkeyword. string items 72 TURNS keyword. Highway LINKREAD phase 159 variable. Cube Avenue 1004 STORAGESPACE JUNCTION keyword. overview 278 JUNCTION keyword. TRNBUILD 936 STORAGE script variable. example in Cube Avenue 1035 value computed. Public Transport 703 T T print format code. Highway 206 impact on Cube Avenue 1014 impact on Cube Cluster 982 SUBAREANETI FILEI keyword. Public Transport 681 SQRT 37 STACK REPORT keyword. cost-based model 464 CHOICE keyword. Network 373 SUMMARY phase Network program 395 variable referencing 396 SUPPLINK TRNBUILD control statement 940 SUPPORT TRNBUILD control statement 941 SUPPORTO FILEO keyword. Pilot 107 standing 748 START FILEI LINKI subkeyword. Public Transport 680 SPREADFACT FACTORS keyword. Public Transport 693 STRUPPER 39 SUBAREAMAT PATHLOAD 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 724 STOPGROUP FILEO STOP2STOPO subkeyword. Matrix 509 MERGE keyword.Index T SPREADCONST FACTORS keyword. TRNBUILD 915 REPORT LINEVOL subkeyword. Highway 195 SUBJECT SENDMAIL keyword. Network 362 starting Cube Voyager 12 STARTMW CHOICE keyword. Public Transport 680 SPREADFUNC FACTORS keyword. Network 382 SYNCHIMP 961 SYNCHIMP utility 961 SYSTEMI FILEI keyword. Cube Avenue 1030 setting. TRNBUILD 936 REPORT LINEVOLS subkeyword. utility-based model 468 XCHOICE keyword. Highway LINKREAD phase 159 variable. Public Transport 777 stops. Cube Avenue 1004 T1 Highway variable 140 value set. cost-based model 472 XCHOICE keyword. Cube Avenue 1004 TAN 38 TAPER 1080 Cube Voyager Reference Guide . numeric items 71 print format code. utility-based model 475 statement tokens 24 STOP FILEI LINKI subkeyword. all-way stops STOPSONLY FILEO NETO subkeyword. Highway 196 PATHLOAD keyword. TRNBUILD 921 TIMEP skim function. example 790 TRACEJ FILEI ROUTEI subkeyword. report 796 maximum in route 670 method 763 penalty between modes 684 penalty weighting factor 683 penalty. TRNBUILD 941 value set.Index T PLOTTER BANDWIDTH subkeyword 379 TC FUNCTION keyword. summary 626 TIMINGI FILEI keyword. Public Transport 619 skim function. Generation 594 REPORT keyword. skim function 618 banning between modes 684 between modes. Highway 242 TOLLROUND FILEI TOLLMATI subkeyword. Highway 212 TCCOEFF PARAMETERS keyword. Highway 197 TONODE GENERATE keyword. Public Transport 702 FILEO ROUTEO subkeyword. Network 352 FREQUENCY keyword. skim function 621 actual wait time. Public Transport 752 LINE NODES subkeyword. Public Transport 683 FACTORS XFERPEN subkeyword. Public Transport 721 TRAM PARAMETERS keyword. Public Transport 753 LINE NODES subkeyword. skim function 619 report by line 776 transit lines attribute report 776 Cube Voyager Reference Guide 1081 . Highway 229 terminology. TRNBUILD 920 LINK keyword. Pilot 113 TOD PARAMETERS keyword. Public Transport 702 FILEO ROUTEO subkeyword. general 74 TO FACTORS XFERCONST subkeyword. Highway 228 TCEXP PARAMETERS keyword. TRNBUILD 920 theory Cube Avenue 1025 Network program 393 THISPROCESS Cube Cluster impact 984 Matrix built-in variable 410 THRUNODE PATHLOAD keyword. general 58 TOLLFACTOR FILEI TOLLMATI subkeyword. Public Transport program 605 TF LINE NODES subkeyword. summary 626 TIMEFAC LINE keyword. Matrix 541 transfers actual penalty. Public Transport 737 TPP2UB 959 TPP2UB utility 959 TRACE PATHLOAD keyword. Highway 243 REPORT keyword. TRNBUILD 924 PNR keyword. Highway 195 path-based toll function 151 PATHLOAD keyword. Matrix 533 PRINTROW keyword. skim function 621 perceived wait time. Highway 242 TOLLMATI FILEI keyword. TPP2UB 960 TOLERANCE LOOKUP keyword. SYNCHIMP utility 962 TITLE COMPARE keyword. Pilot 107 SELECT keyword. Public Transport 620 skim function. Public Transport 754 LINE keyword. report 795 between operators. Highway 242 TIME Highway array 141 LINE NODES subkeyword. Highway 250 REPORT keyword. Highway LINKREAD phase 159 TIMEA skim function. constant to add 682 perceived penalty. Public Transport 684 SENDMAIL keyword. TRNBUILD 939 TRACEI FILEI ROUTEI subkeyword. TRNBUILD 934 SUPPLINK keyword. Highway 197 TOLLS FILEI TOLLMATI subkeyword. Public Transport 682 FACTORS XFERFACTOR subkeyword. Public Transport 721 report produced. Matrix 551 REPORT keyword. generating 772 travel demand on. including data in 711 loadings. report 794 passenger boardings. Highway 197 FILEI keyword. selecting 631 errors in data. number computed 768 unsuccessful proportion. perceived. computation of 755 travel time. Public Transport 779 TRNLEGS4 REREPORT keyword. report 763 transit line. Public Transport 716 JUNCTION keyword. Public Transport 778 TRNLEGS2 REREPORT keyword. generating report 773 report summarizing 793 reports. Highway 229 TURNPENI FILEI keyword. name of 704 turn times converting to costs 229 TURNCHANNELIZED JUNCTION keyword. Highway 229 TURNGAPWT PARAMETERS keyword. TPP2UB 960 TRNLEGS1 REREPORT keyword. skim function 624 unsuccessful. overview 278 JUNCTION keyword. extending control value 764 travel time. common description 287 JUNCTION keyword. 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. extending control values 764 TRIM 39 Trip Matrix processing 893 trip purposes 568 trip time best. overview 278 select-link expression keyword. geometric signals 300 UNITFARE 1082 Cube Voyager Reference Guide . Public Transport 768 TRIPSXY FILEI LINKI subkeyword. Highway 207 TURNS Highway control statement 255 TURNVOLO FILEO keyword. Public Transport 767 travel time actual. skim function 624 TRIPSIJ PARAMETERS keyword. Public Transport 704 TURNPENO FILEO keyword. Public Transport 778 TRNLEGS3 REREPORT keyword. skim function 620 transit line 767 transit line. ignoring 766 excessive travel time. skim function 622 TRIPS TRNBUILD control statement 945 trips. Public Transport 636 U UB2TPP utility 957 UNCONNECTED REPORT keyword. including in 775 summary report. message 763 links file. Network 390 UNITEXTENSION JUNCTION keyword. link 767 transit network maximum node number. 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. skim function 619 crowded link. Network 363 TYPE FILEO MATO subkeyword. skim function 620 perceived.Index U demand using. Public Transport 779 TRNPTH 953 turn penalty files input. TRNBUILD 931 transposed matrix 410 TRANTIME PARAMETERS keyword. exceeding control value. identifying 628 travel time. two-way stop 311 TURNCOSTFAC PARAMETERS keyword. Public Transport 652 matrix 184 Matrix program. geometric priority junctions 334 JUNCTION keyword. Highway 250 VEHICLETYPE LINE keyword. Pilot 94 user class example 884 list of 768 overview 769 passenger loading report by 774 trips loaded 768 user stacks. Matrix 479 COMP keyword. Network 366 VARI FILEI keyword. Cube Avenue 1023 VISIBILITY JUNCTION keyword. Public Transport 768 REPORT LINEVOLS subkeyword. Public Transport 753 Cube Voyager Reference Guide 1083 . Highway program 259 USERCLASS REREPORT keyword. Public Transport 709 FILEO NTLEGO subkeyword. Network 363 FILEO ESTMICPO subkeyword. UB2TPP 958 VARS FILEO TURNVOLO keyword. Highway 203 LOG keyword. Public Transport 774 USERNAME SENDMAIL keyword. built-in 409 naming convention 43 Network program. overview 278 VOL FILEO LINEO subkeyword. Public Transport 768 VAL 39 SET keyword. utility-based model 475 V V FUNCTION keyword. summary 626 value of choice skim function 624 VALUEMW FREQUENCY keyword. Network 356 FILEI LINKI subkeyword. Pilot 95 FILEI keyword. Public Transport 659 CROSSTAB keyword. TPP2UB 959 variables COMP expression. SYNCHIMP 963 UPDATEVARS WAIT4FILES keyword. Cube Cluster 990 URL DOWNLOAD keyword. Highway 252 SET keyword. Public Transport 646 MATI phase. Pilot 107 SET keyword. Public Transport 650 VARO FILEO keyword. Matrix 533 VALUEOFTIME FACTORS keyword. Public Transport 754 Public Transport control statement 780 VEHPERDIST PARAMETERS keyword. Public Transport 779 USERCLASSES PARAMETERS keyword. Matrix 453 ARRAY keyword. referencing in 395 NODEREAD phase. Highway 181 ARRAY keyword. Pilot 113 USERUNTIME PARAMETERS keyword. Highway 209 REPORT keyword. Highway variable 140 V4ROUTEFORMAT PARAMETERS keyword. Highway 213 V.Index V FARESYSTEM keyword. general 55 VARFORM FILEO LINKO subkeyword. Network 349 COMP keyword. Network program 397 SELECTIJ phase. Public Transport 649 MATO phase. Public Transport 718 Highway array 141 LINE NODES subkeyword. Public Transport 647 Highway 140 LINKREAD phase. TRNBUILD 929 UTILITIES CHOICE keyword. Matrix 480 convergence. Matrix 552 VDTSPD impact on Cube Cluster 983 REPORT keyword. Highway program 142 DATAPREP phase. Public Transport 624 skim function. Public Transport 682 VAR ARRAY keyword. Public Transport 645 output. Matrix 552 ValOfChoice skim function. Public Transport 694 UNITS junction file control statement 278 PARAMETERS keyword. Highway 184 COMP keyword. Highway 252 SET keyword. utility-based model 468 UTILITIESMW XCHOICE keyword. Public Transport 761 PATHLOAD keyword. Public Transport 618 skim function. Highway 225 WIDTH JUNCTION keyword. skim function 618 initial. Public Transport 683 XFERGEN TRNBUILD control statement 947 XFERLEGS REREPORT keyword. theory 798 WALKSPEED PARAMETERS keyword. Public Transport 718 NT keyword. Public Transport 737 XFERPEN FACTORS keyword. TRNBUILD 946 W WAIT PROMPT keyword. geometric priority junctions 335 JUNCTION keyword. Public Transport 621 skim function. TRNBUILD 948 XCHOICE CHOICE. skim function 619 wait curve 783 WAIT4FILES Cube Cluster control statement 988 WAITCRVDEF Public Transport control statement 782 WAITFACTOR FACTORS keyword. Highway 252 VOLDATE PARAMETERS keyword. skim function 619 theory 799 transfer. Public Transport 682 walk choice portion of trips allocated to 674 walk time. Public Transport 765 WORKRAM PHASE1 keyword. Public Transport 714 VOLT NT keyword. Pilot 106 wait curves defining 782 description 783 wait time converting to perceived 905 crowding. 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. Public Transport 780 XFERMETHOD GENERATE keyword. Public Transport 761 VOLTIME PARAMETERS keyword. actual. skim function 618 transfer. PARAMETERS COMBINE keyword. Public Transport 684 XFERPENA skim function. perceived. Highway 244 REPORT VDTSPD keyword. TRNBUILD 905 XPENFAC FACTOR keyword. Public Transport 761 XPEN FACTOR keyword. actual. summary 626 XN FILEO NTLEGO subkeyword. SYNCHIMP 963 VOLUMEI FILEI keyword. TRNBUILD 908 XFERCONST FACTORS keyword. Public Transport 621 skim function. SYNCHIMP 963 VOLFIELDS FILEO LINKO subkeyword. TRNBUILD 906 XWAITA skim function. perceived. Matrix 540 maximum index. skim function 618 crowding. Public Transport 682 XFERFACTOR FACTORS keyword. actual. summary 626 1084 Cube Voyager Reference Guide .Index W NT keyword. SYNCHIMP utility 962 VOLUMES TRIPS MATRIX ASSIGN subkeyword. overview 278 Windows starting Cube Voyager from 13 work matrices maximum index. skim function 618 initial. TRNBUILD 930 WEIGHTS. Highway 226 maximum index. differences with 475 Matrix control statement 468 XFARE FARE keyword. perceived. summary 626 XFERPENP skim function. TRNBUILD 921 Y Y Network variable 345 XY NODE subkeyword. Public Transport 769 PARAMETERS keyword. keywords 336 Z Z FILEI ZDATI subkeyword. Network 376 PNR keyword. TRNBUILD 948 XYALL SUPPLINK keyword. Matrix 527 Matrix built-in variable 410 ZDAT Report keyword. Distribution 576 PARAMETERS keyword. keywords 331 keywords 330 overview 329 saturation flow. summary 626 XY TRNBUILD control statement 948 XY keyword. TRNBUILD 944 XYFAC SUPPLINK keyword. example 335 geometric. Matrix 541 PARAMETERS keyword. Public Transport 619 skim function. TRNBUILD 930 XYSPD LINE NODES subkeyword. TRNBUILD 941 SUPPORT keyword. TRNBUILD 906 XWAITP skim function. TRNBUILD 930 ZONEO RENUMBER keyword. Matrix 551 ZDATI FILEI keyword. TRNBUILD 944 XYFACTOR PARAMETERS keyword. Highway 198 FILEI keyword. Public Transport 755 LINE keyword. TRNBUILD 948 yield-controlled intersections geometric. Highway 200 FILEI ZDATI subkeyword. Public Transport 753 LINE NODES subkeyword. TRNBUILD 906 XWAITMAX FACTOR keyword. TRNBUILD 934 RENUMBER keyword. Matrix 506 zonal timing messages Highway 229 Matrix 541 Public Transport 769 zone lacking valid routes 766 lists. TRNBUILD 906 XWAITMIN FACTOR keyword. Matrix 546 Cube Voyager Reference Guide 1085 . TRNBUILD 920 XYSPEED LINE keyword. TRNBUILD 941 SUPPORT keyword. Fratar 128 PARAMETERS keyword. Matrix 546 ZONES Highway variable 140 Matrix built-in variable 410 PARAMETERS keyword. Matrix 541 PARAMETERS keyword.Index Y XWAITCURVE FACTORS keyword. Matrix 510 FILEO RECO subkeyword. Highway 229 PARAMETERS keyword. Highway 252 REPORT keyword. Highway 230 PARAMETERS keyword. working with 413 substituting 415 ZONEACCESS TRNBUILD control statement 949 ZONEMSG PARAMETERS keyword. Public Transport 685 XWAITFAC FACTOR keyword. Index Z 1086 Cube Voyager Reference Guide .