RG CubeVoyager

Cube Voyager Reference Guide Cube Voyager Reference Guide
Citilabs
Cube Voyager
Reference Guide
Version 5.0
Copyright 20072008 Citilabs, Inc. All rights reserved. Citilabs is a registered trademark of Citilabs, Inc. All other brand names and product names used in this book are trademarks, registered trademarks, or trade names of their respective holders. The information contained in this document is the exclusive property of Citilabs. This work is protected under United States copyright law and the copyright laws of the given countries of origin and applicable international laws, treaties, and/or conventions. No part of this work may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying or recording, or by any information storage or retrieval system, except as expressly permitted in writing by Citilabs. Citilabs has carefully reviewed the accuracy of this document, but shall not be held responsible for any omissions or errors that may appear. Information in this document is subject to change without notice
Document Revision 50-006-1 December 12, 2008
Cube Voyager Reference Guide
Contents
About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Design concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Program features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Minimum system requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 2
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Starting Cube Voyager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Starting Cube Voyager from Cube Base . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Starting Cube Voyager from Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Starting Cube Voyager from the command prompt. . . . . . . . . . . . . . . . 14
Chapter 3
General Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Introduction to Cube Voyager control statements . . . . . . . . . . . . . . . . . . . . . 20 Control statement syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Statement tokens (%...%) and (@...@) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Null blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Control blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Control fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 Subkeywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Keyword values and documentation descriptions . . . . . . . . . . . . . . . . . 28 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Variable naming convention (general syntax) . . . . . . . . . . . . . . . . . . . . . 39
Cube Voyager Reference Guide iii
Contents
Standard control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Control statement introduction (general syntax) . . . . . . . . . . . . . . . . . . 41 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 CONSOLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 GLOBAL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 LOG. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 LOOKUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 READ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Chapter 4
Pilot Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Using Pilot program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Statement tokens (%...% and @...@) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 *command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 CLEARERROR. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 COPY ... ENDCOPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 DOWNLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 NEWPAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 ONRUNERRORGOTO. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 PROMPT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102 RUN ... ENDRUN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
iv Cube Voyager Reference Guide
Contents
SENDMAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Pilot example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Pilot example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110 Pilot example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Chapter 5
Fratar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Using Fratar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 Specifying target values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115 Controlling target totals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 Convergence Iteration control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 Multiple purposes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 SETPA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Chapter 6
Highway Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Using the Highway program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Highway introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Highway program control statement overview . . . . . . . . . . . . . . . . . . . 133 Functions and built-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Getting started with assignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 Path-based tolls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 SETUP and LINKREAD phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 ILOOP phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 ADJUST phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 CONVERGE phase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196 FILET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 FILLMW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Cube Voyager Reference Guide v
Contents
FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 LINKLOOP ... ENDLINKLOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215 PATHLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 SETGROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 SPDCAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245 TURNS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 Process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248 User stacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Highway example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Highway example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Highway example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253 Highway example 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 Highway example 5 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255 Highway example 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 Highway example 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 Highway example 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Chapter 7
Intersection Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Introduction to intersection modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 Why use intersection modeling? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 How the intersection models work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Limitations of intersection modeling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Cube Voyager intersection modelling and other programs. . . . . . . . 263 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 JUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 UNITS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
vi Cube Voyager Reference Guide
Contents
Common keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 APPROACH. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 APPROACH1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 ENABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 ESTIMATEDDELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 EXITONLY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 INITIALQUEUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 MINIMUMCAPACITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 MOVEMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 NODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 RANDOMNESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275 TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 Signal-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Overview of signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 Generic keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 Geometric keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Geometric signals example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 Saturation flow signals example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 Two-way stop-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301 All-way-stop-controlled intersections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302 Roundabouts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Overview of roundabouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 Empirical roundabouts: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305 Empirical roundabouts: Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 Gap acceptance roundabouts: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . 316 Gap-acceptance roundabouts: Example. . . . . . . . . . . . . . . . . . . . . . . . . . 317 Priority junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Overview of priority junctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318 Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 Geometric priority junctions: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 320 Geometric priority junctions: Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 324 Saturation-flow priority junctions: Keywords . . . . . . . . . . . . . . . . . . . . . 325 Saturation-flow priority junctions: Example . . . . . . . . . . . . . . . . . . . . . . 327
Chapter 8
Network Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Introduction to the Network program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 Built-in variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 Built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Cube Voyager Reference Guide vii
Contents
Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 COMPARE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 CROSSTAB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 MERGE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 PLOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 PLOTTER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 SPDCAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Phase descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 Variable referencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 Output variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383 Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Listing links to the print file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Merging link records from multiple ASCII files . . . . . . . . . . . . . . . . . . . . 387 Dumping link and node records to DBF files excluding select fields . 387 Building network from inline data records. . . . . . . . . . . . . . . . . . . . . . . . 388 Simple link plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 Complex plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
viii Cube Voyager Reference Guide
Contents
Chapter 9
Matrix Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Using the Matrix program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Introduction to the Matrix program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Control statement types in Matrix program . . . . . . . . . . . . . . . . . . . . . . 396 Working with intrazonal cells of a matrix . . . . . . . . . . . . . . . . . . . . . . . . . 397 Working with lists of zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Working with RECI/RECO processing in v4.0 and beyond. . . . . . . . . . 402 Working with logit choice models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 ARRAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 BSEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 CALL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 CHOICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 XCHOICE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 FILET. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 FILLMW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 FREQUENCY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 IF ... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 514 LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 RENUMBER. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527 SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 SORT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532 WRITE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Cube Voyager Reference Guide ix
Contents
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Example 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Example 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534 Example 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 Example 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Example 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Example 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539
Chapter 10
Distribution Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541

Introduction to the Distribution program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 Convergence: Iteration control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 Multiple purposes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 Referencing productions and attractions . . . . . . . . . . . . . . . . . . . . . . . . . 549 Travel function values: Friction factors . . . . . . . . . . . . . . . . . . . . . . . . . . . 550 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 GRAVITY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 SETPA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Distribution example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Distribution example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559 Distribution example 3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Chapter 11
Generation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563

Introduction to Generation program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566 BALANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 PROCESS ... ENDPROCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 Generation example 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574 Generation example 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
x Cube Voyager Reference Guide
Contents
Chapter 12
Public Transport Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Summary of facts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580 Preparing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584 Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 Network development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588 Route enumeration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 Route evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591 Skimming (level of service) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593 Loading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 Select link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 Loading analyses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 Crowd modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 NODEREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624 DATAPREP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 MATI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626 SELECTIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628 SKIMIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629 MATO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 630 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632 ABORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 COMP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636 CONTINUE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 CROWDCRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641 CROWDMODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643 EXIT. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 FACTORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 FARESYSTEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684 GENERATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 GOTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 IF... ELSEIF ... ELSE ... ENDIF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 JLOOP ... ENDJLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720 LINKLOOP ... ENDLINKLOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
Cube Voyager Reference Guide xi
Contents
LOOP ... ENDLOOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731 MODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 NT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 734 OPERATOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 737 PRINT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 PRINTROW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 REPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 746 REREPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749 VEHICLETYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 755 WAITCRVDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760 Enumerated routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 761 Evaluated routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762 Fare matrices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766 Transit line summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767 Transit line loadings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 768 Transfers between modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 769 Transfers between operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 770 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 Generalized cost . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 Modeling approach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777 Network simplification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782 Route-enumeration process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793 Route-evaluation process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799 SFM and SFCM examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 809 Skimming process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 812 Loading process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815 Fares. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 818 Crowding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 830 Using the Public Transport program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836 Estimating demand matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 836 Defining input and output files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837 Linking Highway and Public Transport models . . . . . . . . . . . . . . . . . . . 838 Coding network times/speeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839 Generating nontransit access and egress legs . . . . . . . . . . . . . . . . . . . . 842 Considering nontransit-only routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845
xii Cube Voyager Reference Guide
Contents
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849 Public transport network development . . . . . . . . . . . . . . . . . . . . . . . . . . 849 Public transport skimming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854 Public transport loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856 Public transport user classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857
Chapter 13
Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861
UB2TPP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 862 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 863 TPP2UB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865 SYNCHIMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 FILEI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 866 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867 Saturn conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869 Running from program window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869 Running from command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 870
Chapter 14
Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871

Using Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872 Cube Cluster introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 872 Cube Cluster control statement summary . . . . . . . . . . . . . . . . . . . . . . . . 877 Working with Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 877 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 DISTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 DISTRIBUTEMULTISTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890 ENDDISTRIBUTEMULTISTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 WAIT4FILES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 891 DISTRIBUTEINTRASTEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 893 Utilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895 Cluster executable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895 Utility functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 897
Cube Voyager Reference Guide xiii
Contents
Chapter 15
Cube Avenue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899

Using Cube Avenue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 Cube Avenue introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 900 Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 902 Control statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 DYNAMIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 909 DYNAMICLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 910 FILEO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915 PARAMETERS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 920 PATHLOAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 Theory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 Cube Avenue algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 924 Cube Avenue calculations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 926 Functions and built-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932 Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 932 Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933 LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 934 Simplifying LINKREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935 Centroids . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 935 ILOOP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 936 ADJUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 937 Enhancing ADJUST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 938 Packet logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 939 Tuning parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 940 Reducing segment and volume lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 945
xiv Cube Voyager Reference Guide
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 Chapter 9, Matrix Program Chapter 10, Distribution Program Chapter 11, Generation Program Chapter 12, Public Transport Program Chapter 13, Utilities Chapter 14, Cube Cluster Chapter 15, Cube Avenue
Cube Voyager Reference Guide xv
About This Document
xvi Cube Voyager Reference Guide
Introduction
This chapter introduces you to Cube Voyager. Topics include: Design concepts Program features Minimum system requirements
Cube Voyager Reference Guide 1
Introduction Design concepts
Design concepts
Cube Voyager is designed to be an integrated modeling system for transportation planning applications. At the heart of the Cube Voyager system is a flexible control language referred to as a scripting language. This provides a flexible environment and grants control over all aspects of the modeling process. The Cube Voyager system has four main assignment programs: Network, Matrix, Highway, and Public Transport. In addition, the system offers supplementary programs for common transportation planning tasks, such as the Generate program for trip generation and the Distribution program for trip distribution. These supplementary programs provide an easy-to-use interface to the basic four programs. Users may implement any model formulation desired in the scripting language. Cube Voyager has no hard coded mechanisms; users are free to change and modify runs as they progress. Cube Voyager is an excellent choice for model applications which require congestion feedback mechanisms. Typically, transportation planning software is run as a series of independent programs, any one of which could require a relatively large amount of input control data, and consume a considerably large amount of computer resources. Some programs could execute for hours, and operate most efficiently with large amounts of RAM. A user may want to use Scenario Manager in Cube to run many scenarios which could require running a large number of programs in successive order. Cube Voyager is a library of programs that employ a language that allows the user to write the script to provide instructions for performing all types of typical planning operations. The script is stored in a file and then read when the system is executed. The individual programs are activated according to the instructions in the script. Each program is designed to perform certain operations, but only as specified by the user. A typical application could involve
2 Cube Voyager Reference Guide
Introduction Design concepts
a very complicated set of instructions, or can be as simple as computing and/or printing a number from a file. It is the users responsibility to design the process that is to be run. The binary files generated by Cube Voyager are designed to reduce disk storage requirements and reduce the amount of time spent on input/output. They have a proprietary format that can not be used by other software, but they can be translated to other formats by the user.
Introduction Program features
Program features
Advanced features of the Cube Voyager software include: Integration with ESRIs ArcEngine allows reading and writing of supported file structures directly to and from a personal geodatabase Full multirouting transit system Intersection and link constrained traffic assignments Flexible scripting language for model run specifications True 32-bit system designed for operating systems such as Windows 95/98/NT/2000/XP All calculations are performed in 64-bit floating-point arithmetic Seamless file format compatibility with existing transportation planning packages such as TRANPLAN, MINUTP, TRIPS, TP+ and others. Database connectivity allowing data to be stored and edited in standard dBASE format Network calculator which can manipulate up to 10 network files concurrently Large problem sizes process efficiently (maximum zones=32,000, maximum nodes=999,999, maximum links=999,999) Flexible matrix calculator with no practical limit on the number of matrices (999 internal working matrices and up to 255 matrices on input and output files). Advanced plotting capabilities to create high quality plots for on-line printing or as plot file images that can be plotted at a later time All data is stored as floating point values (a proprietary data compression scheme is employed to save disk space)
Introduction Program features
Capability to link with user-generated native code
Introduction Minimum system requirements
Minimum system requirements

Cube Voyager requires a Windows 95/98/NT/2000/XP environment in which to function. The system utilizes RAM as needed; most applications will not require any special RAM considerations. The exact amount of RAM required can not be determined until an application actually runs and the combination of user options is diagnosed. It is fairly safe to state that if a computer can run Windows, it has enough RAM to run Cube Voyager. About 75 MB of disk space is required to install Cube Base and Cube Voyager. Additional disk space is required for the various files. A typical application will require zonal data files, networks, and matrices. Zonal data files are not very large, and network sizes will depend upon the number of alternatives and variables that the user wishes to employ. The largest networks will be only a few MB. The largest storage requirements will be associated with matrices. A matrix will contain zones zones cells of information. Each cell value can be from 0 to 9 bytes in size, but Cube Voyager uses a proprietary data compression technique that helps to reduce the sizes. The user can control the matrix sizing. Cube Voyager is designed to run in a multitasking environment. In such an environment, there is a possibility that several simultaneous applications could try to access the same data files simultaneously. This could possibly cause problems if one application is trying to update a file while other applications are accessing it.
Getting Started
This chapter describes how to get started using Cube Voyager. Topics include: Installation Starting Cube Voyager
Getting Started Installation
Installation
To install Cube Voyager, follow the steps outlined below: Install the Citilabs license CD first Once the license files are installed, Cube Voyager should automatically be selected during the installation of Cube
Getting Started Starting Cube Voyager
Starting Cube Voyager

This section describes various ways to start Cube Voyager: Starting Cube Voyager from Cube Base Starting Cube Voyager from Windows Starting Cube Voyager from the command prompt
Starting Cube Voyager from Cube Base

Cube Voyager should be started from Cube. After creating a new Cube Voyager application or opening an existing one, go to the Program menu, point to Passenger Forecasting, then VOYAGER to access Cube Voyager programs from the menus. See Chapter 14, Application Manager, in the Cube Base Reference Guide for general information on setting up an application in Application Manager. See Running application in Application Manager on page 631 of the Cube Base Reference Guide and Running a Cube Voyager, TP+, or TRIPS program on page 631 of the Cube Base Reference Guide for specific information on running a Cube Voyager application or program from Cube. When running a Cube Voyager application or program in Cube from Application Manager, Application Manager builds a task run file and a full Cube Voyager script file of the entire job and sends the task run file to a program called Task Monitor. See Chapter 16, Task Monitor, in the Cube Base Reference Guide for a detailed description of this program. Task Monitor sends the Cube Voyager
script file of the run to the Cube Voyager program to run and monitors and display status information about the run as shown in the figure below.
Starting Cube Voyager from Windows

If Cube Voyager has been properly installed, Cube Voyager can be started from: Start Menu, Run, then type or browse for VOYAGER.EXE (the default directory is C:\Program Files\Citilabs\CubeVoyager), then click enter The Cube Voyager run monitor window will open and prompt the user for the following data: The name of the script file that is to be run
The working directory where the basic application data is stored A system prefix (max of 4 characters) The desired height and width of a printed page A Run ID (character string) that will be printed at the top of every printed page
Users can use either the Browse or the Favorite button to locate a job script file. Both buttons invoke an Open File dialog box. The only difference is that the Browse button points to the current directory, while the Favorite button points to the Windows Favorite directory. Users can add frequently run job script files to the Favorite directory (using Windows Explorer) to quickly locate them later in a Cube Voyager window, with the Favorite button. The Edit Input File button can be used to open the current job script file in Cube for editing or running directly from Cube. See Starting a model run on page 554 of the Cube Base Reference Guide.
11
The Work Directory is defaulted to the directory where the job script file resides when a new job script file is selected. When this data is completed and the Start button is pressed, Cube Voyager begins execution and the Start and the Cancel buttons become the Pause and the Abort buttons, respectively. The Pause button can be used to pause the execution, while the Abort button allows for pre-mature termination of the execution. During execution, periodic messages will be written to the window. The window can be minimized or left open as Cube Voyager is executing. When the application is finished, the View Print File button can be pushed to view the resulting run print file. The Notify When Done check box can be used to bring the Cube Voyager window back on top when its done, if it has been minimized during execution. The default behavior is to have the Cube Voyager window maintain its current status, minimized or maximized, after the execution is completed.
The Send Email When Done check box can be used to send an email to report on the run status at the end of a run. When selected the following dialog box appears which allows the user to provide the same information documented in the Cube Voyager SENDMAIL statement under the Pilot program.
The Wait Start button can be used to place this instance of Cube Voyager in wait mode for use as a processing node for Cube Cluster. See Chapter 14, Cube Cluster, for a detailed description of this process.
13
The About Voyager button can be used to get License and maintenance information and the version and date of all Cube Voyager programs as well as some standard machine information as shown on the About Voyager dialog below.
Starting Cube Voyager from the command prompt

You can run Cube Voyager completely from a command prompt (if this capability is available). The path to VOYAGER.EXE should be added to the PATH system variable, so that, it can be run from any working directories. The following statement will initiate a Cube Voyager run from a command line with the appropriate parameters and options:
Voyager.exe scriptfile [-Ppppp] [-PH:pageheight] [-PW:pagewidth] [-Sworkdir] [-Irunid] [/Start] [/StartTime:hhmm] [/EmailOn] [/NotifyOn] [/ViewPrint] [/Hide] [/High] [/Wait] [/WinLeft:xx] [/WinTop:xx] [/WinWidth:xx] [/WinHeight:xx]
Command line parameters:
scriptfile is the name of the file that contains the Cube Voyager
script control statements. The name may have a complete path in the typical operating system format. This file may be in a different subdirectory than the -Spath argument. In some operating environments (such as Windows), it may be necessary to provide a fully qualified file name (path\filename).
pppp is a prefix (or project) that is pertinent to this application. Some files will always contain these characters (maximum 4 characters) as part of their name. Most individual programs will allow the prefix to be substituted directly for the ? character in their file names. The characters must be those that are acceptable as part of filenames to the operating system, and are not a Cube Voyager operator ('",+-*/&|). The program will generate a print file and a var file with this prefix as its first characters. If the prefix is not designated, the program will assign one based upon the following criteria:
If there is a pppp.PRJ file in the working subdirectory: the prefix will be set to the last prefix in the file. If there is no pppp.PRJ, it will generate a file by that name. Warning: Be sure that any pppp.PRJ file that Cube Voyager reads is a valid Cube Voyager PRJ file. The program automatically associates a unique sequence number with the prefix. The pageht, pagewdth, and runid parameters can be reset dynamically by Cube Voyager control statements within individual Cube Voyager programs. When set within the individual programs, their effect may be valid for only that program.
pageht is the height (number of print lines) for a printed page
of output. This will default to 58, if the program can not find a height from the Cube Voyager PRJ file. The maximum value is 32767.
pagewdth is the maximum length a printed line can have. It
may not be less than 72, nor greater than 255. If it is not specified, and a width can not be found from the Cube Voyager
15
PRJ file, it will default to 132. Note that pagewdth will not cause longer length lines to be truncated or folded; they will be written with the appropriate length. The primary use of pagewdth is to assist in formatting messages and reports.
workdir is the subdirectory that the application is to be run
from. Normally, the user will log onto the desired subdirectory, and workdir will not need to be specified. But, in some operating environments, it may not be possible to log on to a subdirectory before starting the program. (Windows may cause some problems in this area.) When the program starts, it checks if workdir is specified, and if so, changes to that subdirectory before it processes the other arguments (excluding filename).
runid can be used to specify a starting ID for the application. If
ID is not specified, it will try to obtain a starting ID from the Cube Voyager PRJ file with matching prefix. Command line options: /Startfor example to auto start the run, also auto terminate when done unless /ViewPrint is on /StartTime:hhmm to auto start the run at certain time /EmailOn to set Email check box on /NotifyOn to set notify on check box /ViewPrint to automatically bring up print file /Hide to hide the run dialog box completely when starting if auto start on /High to set the high priority check box /Wait to auto start in Wait Start mode as a cluster node /WinLeft:xx to set the window location and width/height or to restore screen size and position when restart from Wait Start mode /WinTop:xx /WinWidth:xx
/WinHeight:xx
As the Cube Voyager job is executing, periodic messages will be written to the Cube Voyager run dialog if /Hide is not on. Pressing Ctrl-Break can be normally used to prematurely terminate the run if the run dialog has been hidden. Otherwise, the Abort button on the Cube Voyager run dialog can be used. When the Cube Voyager job is completed, control will return to the windows command line interpreter.
17
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
19
General Syntax Introduction to Cube Voyager control statements
Introduction to Cube Voyager control statements

Cube Voyager operates by reading control statements from a script (job) file. All control statements have the same general format. Each statement begins with a control word to tell the program what type of statement it is. Following the control word and one, or more, spaces, are keywords and their values. A keyword is always followed by an equals (=) sign, and then the value(s) to be associated with the keyword. There may be as many keywords as are applicable to the control type. A statement can be continued onto the next line by breaking it after a valid operator for the statement. If the last character on the statement (prior to any comments) is a valid operator for the statement, the statement MUST continue onto the next line. Valid continuation characters are: comma and mathematical and logical operators: ( , + - / * ^ & | = ); the character must be one that is in proper context for the statement.
Example
COMP a = b + c = ; invalid: = is not in proper context COMP a = b + c + ; valid: + is logical at this point d + e / f ; continuation of previous line ZDATI=myfile, z=2-4, emp=21-30 pop=40- ; valid: - is logical here 48, ; valid: , is logical here sfdus = 51-55 & ; invalid: & doesnt fit here mfdus= 61-65
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.
21
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
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
23
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.
If the dash touches the second field, and there is another dash between the first field and the dash, it is a range with the second field being negative.
Examples of numbers specified as single or range values
Expression 1-5, 1- 5, 1 5 1 5 1 5, 1,5, 1 , 5 1,-5 1 , -5 135 -1-5 -1--5 -8--5 -8 - -5 Meaning three ways of specifying range: 1 through 5. value 1, and value -5. three ways of specifying: value 1 and value 5. error! value 1 and value -5 value 1 and range: 3 through 5. range: 1 through +5 range: -1 through -5; descending, and could be an error. range: -8 through -5, but doesnt look nice. range: -8 through -5, but less confusing.
It should be noted that this syntax is somewhat different for numeric expression fields as noted below; ranges are invalid in such expressions. Select expressions do allow ranges for single variables, strings, and results of numeric expressions, so it is suggested that parenthesis be used to remove any ambiguities in expressions. This is described in more detail in IF ... ELSEIF ... ELSE ... ENDIF on page 48.
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
25
square brackets []. When a keyword is subscripted, there may be no special characters prior to the right bracket (]); the subscript must fill the space between the []. Most keywords that are subscripted are specific to the program, and the subscript must be an integer constant. Some programs allow certain vectored keywords to have a variable as the subscript; this is usually only when the keyword is on a COMP (or similar type of statement). Some keywords allow double subscripts to indicate a matrix of rows and columns. In such cases, there are two sets of brackets [row][column]. For example: capacity stratified by lanes (row) and spdclass (column). The row index sets the row where the data is to load and the column index sets where in the row the data loading is to begin. If there is no column designation, it is assumed to be one. One is the minimum value for rows and columns. If there is more input data than is allowed in a row, the data spills into the next row (beginning at that rows column 1), but it will not fill beyond the end of the array. In certain cases, three-dimensional arrays are allowed, but they are rare, and will be more fully defined in the specific program documentation.
Examples
LINKI= LIINKI[3]= NOX[2][7]= NOX[3]= ; single value format VAL=10,20,30,35,40,50 ; VAL[1]=10, VAL[2]=20, , VAL[6]=50 VAL[55]=770, VAL[83]=1200,1250 ; VAL[83]=1200, VAL[84]=1250 VAL(2) ; invalid, the subscript must be [2]
Subkeywords
Some keywords (internal level 2) may have further descriptive keywords (level 3) associated with them, and each of those sub keywords may possibly have another sub keyword (level 4) associated with them. Level 4 is the maximum. A level 2 keyword may be used at any time, but a level 3 keyword may be used only following a level 2, 3, or 4, keyword. A level 4 keyword may be used
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.
27
Keyword values and documentation descriptions

What may follow the = for a keyword depends upon the criteria for the keyword. In the documentation, each keyword description begins with a criteria list enclosed within |...|. Any of the following letters (case sensitive) within the criteria list indicate what type of data must be entered for the keyword.
Letter C D F Description Character -- any valid text string, but only the first character is used. Double Double-precision real numbers. Filename -- filenames in a format acceptable to the operating system. If the name is to contain any special characters that may be in conflict with the system delimiters, the name must be enclosed within double quotes. (Single quotes may be used, but if the operating system allows single quotes in the filename, double quotes are required). If a filename contains a question mark (?), the ? is immediately revised to PPPP, where PPPP is the Cube Voyager prefix that has been set by the user. In some cases, if the filename does not contain an extension (.ext), the program may want to append an appropriate extension (.NET, .MAT, .DBF, etc.). To preclude the program from appending an extension, the file name should end with a dot (.) (For example, MYFILE.) Integer -- numbers that are entered without decimal points. If a decimal point is entered, the value will be processed as the nearest integer. Real -- numbers that may contain decimal points. If the number is to be entered with a negative exponent (for example, 1.23E-2), the system reader doesnt know if the dash is an exponent sign or a field separator. With such values, the entire field must be enclosed within '...' (for example, '1.23E-2'). This same restriction does not apply to constants within an expression because ranges are not allowed. Real numbers are entered as single precision values: precision is restricted to the 6-7 most significant digits (system dependant). Boolean Response -- true/false character. Programs may accept various responses depending upon the native language of the user. In English, for example, a true response could possibly be any of (Yes ,1, True), and the negative response could be (No, 0, False); only the first character will be processed.
Letter N s
Description Numeric expression -- expressions that will result in a number. See Numeric expressions on page 30 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 36 for details of expressions. String -- text string, usually used for naming or identifying something. If the string is to contain any of the delimiter characters (including space), it must be enclosed within '...'. If it is to contain a ', it must be within "...".
Other characters in the criteria list provide more information about the keyword. Possible characters and their meanings are:
Character a K Description Ascending order Values must be listed in ascending order. Trigger keyword -- The program recognizes the keyword directly without specification of the control statement. Therefore, you may specify trigger keywords as the first word on a statement; the program treats the entire statement as if the first word was the appropriate control statement. Pairs -- The values may be entered as single values or as pairs of numbers (two numbers separated by a dash.) Vector -- The keyword is vectored; multiple values may be entered. An index may be appended to the keyword to indicate the loading point in the keyword array. An index should not be appended if a number does not follow V, and any index may not exceed the value of the number. If a number follows V, it is the maximum index allowed for the keyword array. For example, V100 means the highest index may be 100. The repetition operator * may be used to enter the same value multiple times for a V keyword. The data are loaded into successive locations in the vector. If [n] follows n, the keyword is doubly dimensioned, and the [n] is the size of the second dimension. For example, V10[20] means the array referenced as the keyword has 10 rows with 20 columns each.
P V
[n]
29
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:
[ddd] [.] [ddd] [fmt[sn]ddd], where: [ddd] [.] [fmt] optional digits (0-9) optional decimal point optional e or E
Character constants are entered as strings enclosed in '...'. A program that deals with a variable number of matrices may have the work matrices referenced by using MW[] or MW[][]. Usually, matrices are referenced within a J loop (J refers to the destination, or column, cell in the matrix), but that is not always the case. At times, it may be beneficial to use a computed variable to indicate which work matrix to reference, and/or which cell in the matrix to reference. When that format is used, it is the users responsibility to ensure that the computed subscripts are within the correct ranges. Unpredictable results could be obtained, or the program could fatally terminate, if the subscripts are incorrect. A general rule is that when a MW is on the left side of an expression (the result) the subscripts must be constants or variables, and when MW is within an expression, the subscripts may be expressions, constants, and/or variables.
Function MW[#] MW[#][n] MW[#][X] MW[W] MW[W][X] Description The Jth cell in work matrix #. The nth cell in work matrix #. The Xth cell in work matrix #. The Jth cell in work matrix W. The Xth cell in work matrix W.
# is a hard-coded constant. X and W may be dynamically computed (users responsibility). Most programs will detect an invalid index, and terminate with a fatal condition.
31
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) Exponential e to the x (-103 < x < 88)
Function INLIST(n,str)
Description 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) Maximum value from the list Minimum value from the list 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)
INT(x) LN(x) LOG(x) MAX(x,y,...) MIN(x,y,...) 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:
33
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.
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. Deletes trailing spaces from str. Returns the numeric value contained in 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)
1. str is either a character constant '...', or a character variable
35
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 51 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.
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-hand side string is exhausted. In other words, the number of characters compared is the string length on the right-hand 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-hand 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
37
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.
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.
39
The possible filename variables formats (illustrated by example) are:

Filename format MI.3.varname Description refers to the matrix named varname found on the file designated by MATI[3]= on the FILEI control statement. If varname is a number, it refers to a relative matrix on the file refers to the variable named varname found in the node portion of the network file designated by NETI[3]= on the FILEI control statement. refers to the variable named varname found in the link portion of the network file designated by NETI[2]= on the FILEI control statement. refers to the array named varname generated by the file designated by ZDATI[5]= on the FILEI control statement. Zonal data are read into zonal arrays; each variable is an array with zones cells. Usually, the reference to a zonal value would also include a subscript; for example, ZI.5.POP[I].
NI.3.varname
LI.2.varname
ZI.5.varname
NOTE: LI.name and NI.name are used when there is only one NETI
allowed in the program (currently applies to only the Highway program).
General Syntax Standard control statements
Standard control statements

This section discusses details about specific control statements. Topics include: Control statement introduction (general syntax) COMP CONSOLE FILEI FILEO GLOBAL ID IF ... ELSEIF ... ELSE ... ENDIF LOG LOOKUP PRINT PRINTROW READ SORT
Control statement introduction (general syntax)

Many programs will share the same type of control statements; however, the data entered on them may vary between programs. This section briefly describes the common format of statements that are used in many of the Cube Voyager programs. All statements follow the format that the statement type is identified by the first word that appears on it. Usually, the first word is the ControlWord. However, in some cases it is more expedient (and/or convenient) for the user to start the statement with one of the special keywords that is acceptable for that type of statement.
41
Those keywords (termed trigger keywords) are identified in their respective program detailed descriptions. The general format for describing Control Statements in this document is:
ControlWord
Key1 Key1 Key1 (Key2 Key2 (Key3 Key3) ) Key1 (Key2) ... ControlWord is the statement type and must be the first keyword on each statement, unless the statement contains trigger keys, and the first keyword is a trigger keyword followed by an equals sign. See the keyword description below for details about trigger keys, denoted by K within the |...|.
Key Key1 Key2 Key3 Description A keyword that must be followed by an equals sign and appropriate value(s). A keyword that is valid only if it follows the values for its Key1, an equal level Key2, or any key3 or key4 (for the same Key1). A keyword that is valid only if it follows the values for its Key2, an equal level Key3, or a key4 (for the same Key2).
The parenthesis () are used only to indicate the key level; they are not coded on the statement. A keyword must always be followed by an equals sign and appropriate value(s). The following example illustrates the hierarchy of control statement description:
CTLWRD
AAA BBB (CCC DDD) EEE FFF (GGG (HHH III) JJJ (KKK) ) This description indicates that AAA, BBB, EEE, and FFF are all valid keywords. They must be followed directly by an equals sign and the associated values, and may appear any place a keyword is allowed. CCC and DDD are valid level 2 keywords, and may appear only following the values for either BBB, CCC, or DDD. GGG may follow the values for FFF, GGG, HHH, III, JJJ, and KKK. HHH and III are level 3
keywords, and may appear only following the values for GGG, HHH, or III. KKK is also a level 3 keyword and may appear only after the values for JJJ or KKK.
Keyword values AAA=3 BBB=5 DDD=2 EEE=25,FFF=Y AAA=3 DDD=2 BBB=5 KKK=27 FFF=Y HHH=5 BBB=5 CCC=6 DDD=7 CCC=8 BBB=9 Description Valid. Invalid: DDD must follow BBB or CCC Invalid: KKK must follow JJJ. Invalid: HHH must follow GGG Valid.
COMP
COMP statements are used to dynamically assign values to variables and/or matrices. COMP statements contains one, or more,
keywords with associated numerical and/or character expressions. Each expression results in a number or a character string; its mode is usually determined by the first term in the expression. If the first term is a number, or numeric variable, it is a numeric expression, or if the first term is a character function or literal character string (beginning with a quote), it is a character expression. Every term within the expression must be known to the expression at the time the COMP statement is to be compiled. Often a variable is defined by its presence as a keyword in another COMP statement. If there are multiple expressions on a COMP statement, they are solved in left to right order.
K = j + 2 ; defines K as a numeric variable. name=' ' ; declares name as a variable that is 4 characters long. namx=substr(name,1,3)+'abcde'+str(k,4,1) ; declares namx as a character variable that is 12 characters long.
All numeric variables that are declared by the user in this manner are internally treated as double precision floating point variables. Some programs (mostly those involving zonal matrices) may allow the use of INCLUDE and EXCLUDE keywords on the COMP statement. When the statement contains either, or both, of these keywords, it means that the statement will be subjected to a zonal
43
filter before being processed. The zonal filter will refer to either I (origin zone) or J (destination zone); the program definition will clarify which. If an INCLUDE is present, the zone number will be checked against the zones in the INCLUDE list. If it fails the INCLUDE list specifications, the statement is bypassed. Then, if there is an EXCLUDE, the zone is checked with the EXCLUDE list. If it meets the EXCLUDE list specifications, the statement is bypassed.
CONSOLE
A CONSOLE statement is used to set certain switches relative to dynamic display of messages in the message area of the window.
Statement CONSOLE ONLINE=Y CONSOLE ONLINE=N CONSOLE MESSAGE=text Description Causes all subsequent text written to the standard print media to also be written to the console. Turns off the ONLINE=Y switch Causes text to be written to the console.
FILEI
FILEI tells the program which input files to process. In most cases, if there is no FILEI statement, the program will assume a default
statement, or simulate certain required defaults. Typical keywords on a FILEI statement are NETI, MATI, and ZDATI. When the program accepts FILEI vectored keywords, such as MATI in various programs, the keyword may contain [i]. If [i] is not specified, [1] is assumed. Most times the statement may begin with the keyword itself, thus eliminating the need to code FILEI. The exact format of the FILEI statement will vary between programs.
FILEI MATI=?01.mat, ?02.mat, ?03.mat, NETI=??.mat MATI[1]=?01.mat, MATI[2]=?02.mat, MATI[3]=?03.mat NETI=??.mat ; this would be the same as the above FILEI statement.
Some FILEI keywords may allow sublevel keywords that are associated with the file keyword. In some programs, all FILEI statements must be in the beginning of the control stream,
because later control statements may reference variables that are to come directly from the files. The documentation for each program will indicate where the FILEI statements are valid. Generally, the programs will delay opening the FILEI files, until it is absolutely necessary, but it is wise to form the habit of placing all FILEI statements first in the control stream. Hint: It is relatively easy to miscode FILEI statements by either omitting or including line delimiters. For example:
FILEI MATI[1]= MATI[2]= MATI[5]=, Abc=def ; ; ; ; this is single FILEI statement this is a single FILEI statement this is a FILEI statement with continuation but this is probably an invalid FILEI continuation
NOTE: Application Manager automatically writes all FILEI
statements to the script file when you define input file boxes. If you use Application Manager, do not manually edit the file path or file name elements of the FILEI statements, as both the script file and the applications .app file stores this information. Editing the file path or file name will result in a mismatch between the file that the script uses when it runs and the file Application Manager opens when you double-click an input file box. (See Chapter 14, Application Manager, in the Cube Base Reference Guide.)
FILEO
FILEO is the counterpart to FILEI; it names the output files to be written by the program. If there is no FILEO statement, some
program will simulate an appropriate statement. The exact format of the FILEO statement will vary between programs.
NOTE: Application Manager automatically writes all FILEO statements to the script file when you define content for output file boxes. If you use Application Manager, do not manually edit the file path or file name elements of the FILEO statements, as both the script file and the applications .app file stores this information. Editing the file path or file name will result in a mismatch between the file the script writes during runs and the file Application
45
Manager opens when you double-click an output file box. (See Chapter 14, Application Manager, in the Cube Base Reference Guide.)
GLOBAL
Alters the size of a page on the standard print media. The keywords are trigger keywords; you need not specify GLOBAL.
GLOBAL keywords
Keyword PAGEHEIGHT |KI| Description Resets the maximum number of lines on a page, so that the system knows when to start a new page with appropriate headers. The value must be in the range 1032767. Hint: If the print file is going to be viewed primarily on-line (instead of actually being printed), it is suggested that PAGEHEIGHT be set to a large number to reduce the number of interspersed page headers. The PAGExxxx values can also be set when Cube Voyager is initially launched from its menu. Resets the maximum number of characters to be printed on a single line. Usually this value is either 80 or 132 to accommodate most character printers. It only comes into play when certain reporting processes need to know the width of a print line, so it can form the report properly. The value must be in the range 50-250.
PAGEWIDTH
|KI|
If these parameters are specified, they remain in effect through subsequent programs until revised.
Example
PAGEHEIGHT=32767 ; preclude insertion of page headers
ID
An ID statement is used to revise the page headings for each printed page. The length of the ID text will be truncated to 60 characters. The ID is specified as: ID=newid string. The ID is revised in one of two ways: with the ID statement, and (in some programs)
by a COMP ID=text expression. ID statements in Cube Voyager Pilot program are dynamic; they cause the ID to be revised when the statement is processed in the Cube Voyager operations stack. ID statements in the application programs cause the ID to be revised only when the statement is encountered in the statement reading and editing phase prior to actual program execution. This can cause the sign-on ID to be revised at a time different than what might be expected. Because of this situation, it is suggested that ID statements be used before a RUN statement. That way, the sign-on page for the application program will contain the desired ID.
Example of improper ID location
RUN PGM=MATRIX ID=this is the MATRIX ID ENDRUN RUN PGM=HIGHWAY ID=this is the HIGHWAY ID ENDRUN
In this situation, the first page (sign-on) for the Matrix application will not contain the this is the MATRIX ID as its header, but the first page of the Highway section would contain it. If the RUN and ID statements were reversed, the sign-on IDs would be correct. When ID is specified as the destination in a COMP statement, the ID can be computed, and it is revised at that time (but will not be reflected in the headers until a new page is required). In the COMP statement, parts of the ID can be computed. This would most likely be used in a Cube Voyager loop situation:
Example of Computing the ID
LOOP PASS=1,5 COMP ID=This is Pass+str(PASS,2,0) RUN PGM= ENDRUN ENDLOOP
Example
ID=This is the new Page Header
47
IF ... ELSEIF ... ELSE ... ENDIF

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

Value of I -1 3 9 >9 Statements executed S1 S2 S3 S4
If, in the example, there were no ELSE statement, then any time I is greater than 8, no statements between the IF and the ENDIF statement would be executed. A variation of the IF statement (sometimes referred to as a simple or short IF) is one in which a single control statement is appended after the IF expression. In such cases, the program automatically generates the required ENDIF. This shortcut statement is provided to help reduce the amount of coding required. Note: if a short IF is used and the statement appended to the statement is not acceptable in that context or is mis-structured, the error diagnostic stated about the line may be somewhat confusing. This is because the system can not always fully ascertain exactly what the problem is. It is diagnosing an IF statement, but the appended statement has errors, so it doesnt know exactly where to place the blame because it is diagnosing the IF statement at the time. Note that there is no corresponding short ELSEIF statement and no control statements may directly follow ELSEIF or ELSE or ENDIF statements on the same line or they will be ignored by the processor.
IF ( i == 1) counter=0 IF ( i == zones) print ... IF (j==3 & k==5) k=3 ; This statement will be OK, ENDIF generated. cnter = cnter + 1 ; and this is OK ENDIF ; This will fail, because there is no associated IF. IF (j==3 & k==5) k=3, ; This statement will be OK cnter = cnter + 1 ; and this will continue it ; Generated the ENDIF here ENDIF ; So, this will be an error.
LOG
Writes values to the log file PREFIX VAR Cube Voyager maintains a file called the log file; it has a filename with an extension of .VAR. Whenever a RUN statement is encountered, Cube Voyager updates the values in the .VAR file with
49
the values for all the variables that Cube Voyager is maintaining plus the values that were logged by any programs. If a program is requested to LOG any values, the program appends values to the .VAR file, and Cube Voyager retrieves the values when the program terminates. The values in the .VAR file can be accessed in two different ways: 1.) in Cube Voyager, the variable can be accessed directly; 2.) in other programs, the values can be retrieved by the use of the @@ token process. In the latter case, the value from the .VAR is substituted directly into the control statement as it is read. A LOG statement is used to have a program write values to the .VAR file. The variables in the .VAR file can be retrieved by other Cube Voyager programs (including the Pilot program) in the same job. Examples may help to clarify this process.
RUN PGM=MATRIX ; (Cube Voyager tests the value from MATRIX): ZONES=5 MW[1] = 1 TOTMW1 = TOTMW1 + ROWSUM(1) LOG VAR=TOTMW1 ENDRUN IF (MATRIX.TOTMW1 == 0) ABORT MSG=Nothing in MW1 RUN PGM=HIGHWAY ; (HIGHWAY obtains a value from MATRIX): . X = @MATRIX.TOTMW1@ . ENDRUN
The records that are written to the file are written as PREFIX.VAR=value. The current version of Cube Voyager truncates .VAR string values with embedded or trailing spaces at the first space when it reads the values. This is scheduled for revision in a subsequent release of the system.
LOG keywords
Keyword PREFIX |S| Description Sets the prefix of the logged variable(s). This string is added to the start of the names of all variables that follow PREFIX. If PREFIX is not specified, the program name will be used. This could be confusing if different applications of the same program log the same values. Indicates which variables will have their values written to the .VAR file.
VAR
|S|
Example
RUN PGM=MATRIX . LOG PREFIX=MATRIX1, VAR=TOTMW1, AVEMW LOG VAR=GRANDTOTAL ; will be written as MATRIX1.GRANDTOTAL=#####
LOOKUP
NAME (LOOKUP (RESULT)) LOOKUPI FILE FAIL SIZE INTERPOLATE LIST R SETUPPER NEAREST TOLERANCE
A LOOKUP statement is used to define a lookup function and to enter data for the function. The statements are not dynamic, they are processed at the appropriate time by the program, prior to their actual use. Lookup functions are referenced from within numerical expressions. When the function is referenced in an expression, the correct number of arguments enclosed within parenthesis must follow it. The function returns a single value to the expression solver. A lookup array is allocated and initialized with the data referenced by the LOOKUPI, FILE or R keywords. In most cases, a lookup statement will define a single set of lookup data, but if a LOOKUP subkeyword follows the NAME, the function will be
51
defined as one that requires at least two arguments (curve number and the value to be searched for). This latter format is useful for entering friction factors for use in the Distribution program. Data referenced by LOOKUPI or FILE keywords can be either in DBF, MDB, or delimited ASCII format. A new wizard feature has been added to Cube to automate the coding of a LOOKUP function when linking a DBF file to a LOOKUPI file box in Application Manager. See Chapter 12, Job Script Editor Window, in the Cube Base Reference Guide for information about this wizard.
LOOKUP keywords
Keyword FAIL Subkeyword Type |RV3| Description Defines the results to be returned by the function if the lookup value is not contained within the data. By default, if the value is less than the lowest value in the table, the result for the lowest value in the table is returned, unless FAIL[1] is explicitly specified. If the value is greater than the highest value in the table, the result for the highest value in the table is returned, unless FAIL[2] is specified. If the value is not found within the data, FAIL[3] (default value is 0) is returned. If a call to the function has more arguments than is required, the argument following the required arguments is the value that will be returned if the lookup fails for any reason. Note that versions prior to 1.5.5 did not return the extreme results of the data for low and high failure; they returned FAIL[1] and FAIL[2], respectively. If FAIL[1-2] were not specified, they were set to 0. FILE |F| Name of the file that contains the data to be associated with the function. This keyword must be specified, unless R or LOOKUPI is specified. FILE, R, and LOOKUPI are mutually exclusive. Indicates if the returned function value is to be the result of interpolating between rows in the lookup table. The default value is false, meaning that there must be a direct match in the table. Indicates if the program is to format and list the lookup table.
INTERPOLATE
|?|
LIST
|?|
LOOKUP keywords (continued)

Keyword LOOKUPI Subkeyword Type |I| Description The # of the FILEI LOOKUPI[#] file where this LOOKUP statement is to obtain values. Note that FILE, LOOKUPI and R are mutually exclusive. The data formats supported for LOOKUPI= and FILE= when referencing data from an external file are ASCII and DBF. ASCII data MUST be delimited with either spaces or commas. Name of the lookup function that the statement defines. Used when data for one, or more, curves is to be obtained from a single data record. The LOOKUP keyword must be indexed [1-n], and its value must be followed by RESULT=value. The values provided for the LOOKUP and RESULT keywords are either the field numbers in the input data (ASCII, DBF, or MDB data) or the field names when the input data is in DBF or MDB format. The LOOKUP index indicates the curve number and the LOOKUP value indicates which column or field in the input data file holds the lookup values for the indexed curve. The value following the RESULT keyword indicates the field number or name on the data record where the return value for the curve on the LOOKUP index is to be found. The use of the LOOKUP keyword implies that the call to the lookup function must contain at least two arguments (a curve number, and a value to be searched for). For example on the LOOKUP statement with NAME=FUNC1, LOOKUP[1]=1 RESULT=2, a call to this function like X=FUNC1(1,5) implies for curve 1 (first argument in the function call), lookup a value of 5 (second argument of the function call) in the data field defined by the LOOKUP value (the first field in this example) and return the value from the field in the data file defined by the RESULT value (the second field in this example). The returned value from the function would be placed in the variable X. Field number or name of the field from the data record that contains the result to be returned when the function is called. Specifies that the function should return a value based on the nearest value found in the table to the lookup value when an exact match cannot be found.
NAME NAME LOOKUP
|S| |S|
NAME
RESULT
|S|
NEAREST
|?|
53
LOOKUP keywords (continued)

Keyword R Subkeyword Type |SV| Description Used in place of the FILE or LOOKUPI keywords to enter data records for the function. If R is specified, FILE or LOOKUPI may not be specified. FILE, LOOKUPI and R are mutually exclusive. Any number of R records can be entered. The string values following R represent data records that are in the same format as the FILE records would be. Each R value must be enclosed within single quote marks '...'. A single R= may specify the entire file, or multiple R= records may be entered. See Example: Double value function Typical friction factor curves on page 58 for an example showing the use of LOOKUP to define friction factor curves for the usage of R= to read data directly from the body of the script file. Specifies that the function is to simulate an upper limit for a lookup row when only a single value is entered for the row. This option is useful when the data is input with single values, and the function can not find an exact match, and it is to return a value based upon the lower of two ranges. For example, a curve is entered with single values that begin at 1 and increment through 10 by 1. A lookup for 1.5 would fail. If INTERPOLATE were true, the return value would be computed, otherwise the return would be error. In such cases, if SETUPPER were true, the result for 1 would be returned. SETUPPER takes precedence over INTERPOLATE, and only comes into play for rows without both limits explicitly provided. Optional variable that specifies the total number of entries in a LOOKUP array. The value should be the number of resulting values to be searched for multiplied by the number of records. As of v4.1 of Cube Voyager and TP+ systems, this keyword is no longer required as the memory allocation process is now automated to optimize within the resources of the computer it is using. However, it is maintained to insure backward compatibility with previous versions of the software. Specifies a tolerance to be applied to the lookup value. This can be useful when the lookup value is the result of a computation and due to processor differences there may be differences in the level of precision associated with the result.
SETUPPER
|?|
SIZE
|I|
TOLERANCE
|R|
Lookup functions are referenced in numerical and selection expressions. When a function is referenced, it is supplied a lookup argument within parenthesis, and the function returns a value for the argument. The returned value is obtained by searching the lookup function data table for the lookup argument. The table is composed of rows of data. If the LOOKUP subkeyword is in effect, the call to the function requires at least two arguments: the lookup curve number and the lookup argument. Otherwise, the function requires only one argument: the lookup argument. If the function can not find a match for the lookup curve number, FAIL[3] is returned, regardless of the value of INTERPOLATE. If the argument is less than the lowest value for the lookup number the return value is set to FAIL[1]. If the argument is higher than the highest value, the return value is set to FAIL[2]. If the value is not found in any range, the return value is set to FAIL[3] unless INTERPOLATE is set to true. If interpolation is used, the return value is the result of interpolating between the high limit of the lower row and the low limit of the upper row. For either a single or double value function (functional call with 1 or 2 arguments) and additional argument value can be provided. If this optional argument is provided ANY failure will not return the FAIL value defined by the FAIL keyword or its default values but the value for this optional argument will be the returned value on any failure. This in effect gives you the ability to override the default FAIL values for specific situations. Possible data records include: Data records when LOOKUP subkeyword is NOT used and data source is ASCII: Each data record must have at least two fields delimited by white space, or commas or may be separate fields on a DBF file. The first field on a record is the lookup result, and the fields following it are the lookup values. If two numbers are separated by a dash, they form the low and high limits of a row. Numbers not separated by dashes are entered as both the low and high limits of a row. Ranges may not overlap, but the upper limit of a
55
row may be equal to the lower limit of the next row. If the argument matches a high limit of a row and the low limit of the next row, the result is obtained from the upper row. (For example, first row limits=1-2, second row limits =2-3. The result for 2 would be obtained from the second row.) Data records when LOOKUP subkeyword is not used and data source is DBF or MDB: Only the first two fields on the DBF or MDB lookup file will be used. The first field is the lookup result and the second field is the lookup value. The first two fields should be numeric fields but character fields are ok as long as the content can be converted to numerics, otherwise the program will report a lookup input error. Data records when LOOKUP subkeyword is used: Each data record may have any number of fields delimited by white space, or commas or may be separate fields on a DBF or MDB file. The data for each LOOKUP is obtained from the record according to the field numbers or names specified for the LOOKUP and RESULT keywords. If either field number exceeds the number of fields on the record, there is no row generated for that curve. If both fields exist, they form a row with the low and high limits equal to the value from the LOOKUP field. When the lookup format designates multiple curves, special consideration is given to blank fields. Blank fields are not treated as zeroes, but indicate there is no data point. For example, assume the following records:
T, 1, 2, 3, 4, 5, v1, v2, v3 101, 201, 301 102, 202, 302 103, , 303 104, 204 , , 305
There will be no data points for T=3,V2, T=4,V3, T=5,V1, and T=5,V2. The V1 curve will have points for T=1-4, the V2 curve will have points for T=1-2,4, and V3 will have points for T=1-3, 5. The result for a lookup of T=3 in V2, will depend upon the options of the LOOKUP statement (SETUPPER, INTERPOLATE, or none). Be aware that this situation exists only for comma delimited and dbf data; space delimited records dont have any way to designate null fields; the first empty field indicates the end of the record, and no more points appear on the record. With space delimited records, the T=3 record would appear as 3 103 303, which would be interpreted as points for V1 and V2; V3 would be blank.
Example: Single value function
COPY FILE=C:\LOOK1.DAT ; this is the data for the function 1 2 3 4-8 23 15 50 2 1 3 9-10 ENDCOPY LOOKUP NAME=DISTRICTS, FILE=C:\LOOK1.DAT LIST=Y
The lookup table will be represented as:

Lower Limit 1 2 3 4 9 23 50 Upper Limit 1 2 3 8 10 23 50 Result Value 2 1 1 1 3 1 15
DISTRICTS(6) results in the value 1. DISTRICTS(9) results in 3. DISTRICTS(50) results in 15.
57
Example: Single value function using LOOKUPI

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

Curve # 1 1 1 1 1 1 2 2 2 2 2 3 3 3 3 Lower Limit 0.01 1 3 4 5 120 0.01 1 3 4 120 0.01 1 4 120 Upper Limit 0.01 1 3 4 5 120 0.01 1 3 4 120 0.01 1 4 120 Result Value 1200 1200 300 100 50 50 1000 1000 500 100 100 800 800 100 100
59
Example: Double value function LOOKUP with DBF LOOKUPI file

FILEI LOOKUPI[1] = "C:\CUBETOWN\TAZ\TAZ.DBF" LOOKUP LOOKUPI=1, ;references the input DBF file NAME=TAZ, ;name for this function LOOKUP[1]=TAZ, RESULT=ACRES, ;lookup a value in TAZ return ;a the value from ACRES LOOKUP[2]=TAZ, RESULT=POPULATION, LOOKUP[3]=TAZ, RESULT=AGE_5_14, LOOKUP[4]=TAZ, RESULT=AGE_15_17, LOOKUP[5]=TAZ, RESULT=ENROL_ELEM, LOOKUP[6]=TAZ, RESULT=ENROL_HS, LOOKUP[7]=TAZ, RESULT=TOTAL_JOBS, LOOKUP[8]=TAZ, RESULT=RET_JOBS, LOOKUP[9]=TAZ, RESULT=SERV_JOBS, LOOKUP[10]=TAZ, RESULT=OTH_JOBS, INTERPOLATE=F ; example of use: v=TAZ(10,25) ; look for 25 in the TAZ field and returns the OTH_JOBS value
Example: Double value function Using LOOKUP to get constants and populate internal arrays with the values
FILEI ZDATI[1] = "C:\MTA_GEN\STEP1.DBF" FILEI LOOKUPI[1] = "C:\MTA_GEN\CFACS.DAT" cc=zi.1.cc ;cc = county code (1=LA,2=OR,3=RV,4=SB,5=VN) ; lookup county correction factors O&D Survey LOOKUP LOOKUPI=2 LIST=Y NAME=CFAC, LOOKUP[1]=1, RESULT=2, LOOKUP[2]=1, RESULT=3, LOOKUP[3]=1, RESULT=4, LOOKUP[4]=1, RESULT=5, LOOKUP[5]=1, RESULT=6, INTERPOLATE =N ; dimension user arrays to 5 array c0=5 cv=5 c2=5 ; fill arrays for factors by county LOOP cc=1,5 c0[cc]=CFAC(cc,1) cv[cc]=CFAC(cc,2) c2[cc]=CFAC(cc,3) ENDLOOP /* ;external LOOKUPI file in this example 1 3.4108 3.4137 3.7070 3.4132 3.2278 2 0.6088 0.6767 0.6505 0.6389 0.6759 3 0.5665 0.6518 0.5778 0.5757 0.6642
*/
Example: Double value function Using LOOKUP with DBF data in a trip Distribution application
RUN PGM=DISTRIBUTION PRNFILE="DISTRIBUTION.PRN" FILEI ZDATI[1] = "TRIP ENDS.DBF" FILEI MATI[1] = "TRAVEL TIMES.MAT" FILEI LOOKUPI[1] = "FRICTIONFACTORS.DBF" FILEO MATO[1] = "PERSON TRIP TABLE.MAT", MO=1-4, NAME='Home_Based','NonHome_Based','School',EI_Trips ; Set a maximum number of iterations and convergence criterion PARAMETERS MAXITERS=99, MAXRMSE=5 ; Link the input production and attraction values to internal variables SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1, P[2]=ZI.1.P2, A[2]=ZI.1.A2, P[3]=ZI.1.P3, A[3]=ZI.1.A3, P[4]=ZI.1.P4, A[4]=ZI.1.A4 ; Put the travel time matrix into a working matrix for distribution MW[20]=MI.1.TIME ; Put the friction factors into a LOOKUP for distribution LOOKUP LOOKUPI=1, NAME=FRICTIONFACTORS, LOOKUP[1]=TRVLTIME, RESULT=HOMEBASED, LOOKUP[2]=TRVLTIME, RESULT=NONHOME, LOOKUP[3]=TRVLTIME, RESULT=SCHOOL, LOOKUP[4]=TRVLTIME, RESULT=EXT_INT, INTERPOLATE=T ; Distribute trips using a standard gravity model formulation GRAVITY PURPOSE=1, LOS=MW[20], FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=2, LOS=MW[20], FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=3, LOS=MW[20], FFACTORS=FRICTIONFACTORS GRAVITY PURPOSE=4, LOS=MW[20], FFACTORS=FRICTIONFACTORS ENDRUN
Where the FRICTIONFACTOR.DBF file contains:
61
PRINT
Formats data items and writes them as a single line to the standard printed output, a file, or both. The program prints one line for each PRINT statement. The length of the printed line is determined by the formatting of each listed item.
CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT)
PRINT keywords
Keyword CFORM Subkeyword |S| Description Optional. Default format for subsequently appearing character strings, except for literal values, specified with the LIST keyword. Explicit formats defined for particular items take precedence. This default format is effective until the program reads the next CFORM value. See Defining a character print format on page 67. Default value is 0. CSV |?| Optional. Flag indicating whether to print the output file in CSV format (with commas between the LIST items). Possible values: FILE |F| T Print in CSV format, with commas between each LIST item F Do not print in CSV format
Default value is F. Optional. File where the program writes the formatted list. If not specified, the program writes the standard printed output file. If specified, the program writes only to the specified file unless subkeyword PRINT is set to T. The program writes each formatted list to one record. Thus, the endof-file character is at the end of the last record. You might need to add a \n to the end of the file if you concatenate the file with another file.
PRINT keywords (continued)

Keyword FILE Subkeyword APPEND |?| Description Optional. Flag indicating whether to overwrite or append to the specified file. Possible values: T Append the formatted list to the specified file. F Overwrite the existing file when writing the formatted list.
NOTE: If set to T for a file at least once in a step, then all PRINT statements executed at that step will append to that file, even if other statements set APPEND to F. Default value is F. FILE PRINT |?| Optional. Flag indicating whether to write record to standard printed output in addition to specified file. Possible values: FILE REWIND |?| T Write the record to the standard printed output in addition to the specified file F Only write the record to the specified file
Default value is F. Optional. Flag indicating whether the program repositions to the start of the file before writing contents. Possible values: T Reposition to start of file before writing formatted list. Program overwrites previous contents. F Write to the current position in the file.
REWIND is dynamic; therefore, you can control the rewinding on each PRINT statement. Default value is F. FORM |S| Optional. Default format for subsequently appearing numbers specified with the LIST keyword. Explicit formats defined for particular items take precedence. This default format is effective until the program reads the next FORM value. See Defining a numeric print format on page 66. Default value is 10.2.
63

Keyword LIST Subkeyword |KS| Description Optional. List of items (variables, strings, and expressions) to format and write to a printed line. Enclose expressions in parentheses. Specify no more than 500 items. To assign an explicit format to a particular item in the list, place the format in parentheses next to the item. The format only applies to that item. See Defining a numeric print format on page 66 and Defining a character print format on page 67. For example:
I, J, ITEM1(6), 'abcde', (sqrt(4))(8C), 'i='(8R), I(L).
Append appropriate subscripts to any array and matrix variables in the list. If you do not specify a subscript, the program will supply one, depending on the variable, program, and phase. Subscripts may be constants, variables, or valid expressions. For example: P[i*3-1]. NOTE: MW[n] normally implies MW[n][J], where J is the current value of J. The PRINT statement recognizes four special character strings as special control characters: "\n" new line control "\f" new page control "\t" tab control "\\" ignore new line control
For example, a literal string may contain the newline character string ("\n" ; lowercase), to generate a new line at that location (the \n will not be printed). As long as a PRINT statement has at least one LIST item, the program automatically inserts a newline character prior to the first item. You can override the automatic newline character by making the first LIST item a literal string that begins with the \\ characters. The \\ will not be printed, and the printing will continue from the current line position. NOTE: Because special characters are treated as these special controls, problems can arise when printing strings for a system path due to the "\" character. For example, upon reading LIST="C:\n2020\output\" the program would treat the embedded \n as the new-line control and insert a new line at the location. Because the special control is case sensitive and directory folder names are not, you can avoid this issue by using LIST="C:\N2020\output".

Keyword LIST (continued) Subkeyword Description In some cases, you might prefer to form character variables using the string functions of a COMP character expression and include those variables in the list. The string functions might provide some flexibility that is better suited to the specific task. |I| PRINT |?| Optional. Index number of the FILEO PRINTO file where the program writes this output. Optional. Flag that indicates whether to write record to standard printed output in addition to specified PRINTO file. Possible values: PRINTO REWIND |?| T Write the record to the standard printed output in addition to the specified file F Only write the record to the specified file
PRINTO PRINTO
Default value is F. Optional. Flag indicating whether the program repositions to the start of the file before writing contents. Possible values: T Reposition to start of file before writing formatted list. Program overwrites previous contents. F Write to the current position in the file.
REWIND is dynamic; therefore, you can control the rewinding on each PRINT statement. Default value is F.
Examples
Report a mixture of numeric and character variables.

PRINT FORM=0 LIST=I, J, TOTAL(6.2CS) FORM=LRCD, LIST=N, JLOOP_J; 'ABCDE'(6.3),
Use LIST keyword without the control statement name.

LIST= I(6) J(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001, APPEND=T
Output to file and rewind file at the end.

PRINT FORM=6.0CDLRS LIST=I, J, TOTAL1, TOTAL2 FILE=PRINTFIL.002, REWIND=T
Interpret sqrt(6) as a variable sqrt with form=6
65
PRINT FORM=LRS LIST= 'I =', I, ' J=', J, MW[1]=', MW[1][1], MW[1][2], MW[1][3], time+dist/sqrt(xyz), (sqrt(6))
'
Output directly to CSV format
FILEO PRINTO[1]=c:\data\mydata.csv If (I=1) PRINT CSV=T LIST=I,J,TIME,COST,DISTANCE PRINTO=1 PRINT CSV=T LIST=I(6.0L),J(6.0L),MW[1](8.4L),MW[2](8.4L),MW[3](5.2L) PRINTO=1
Defining a numeric print format

Use FORM to format numeric items. For FORM or individual numeric LIST items, specify print format as:
w.dCDBTLRS
where: w Total field width. For strings, you might set w to 0, indicating that the field width depends on the string length.
NOTE: If the format specifies L, w must be wide enough to accommodate the number.
d For numbers, number of digits printed after the decimal point; for strings, number of leading spaces printed. The program sets d to 0 if the format begins with w, and you do not specify d. C Insert commas into numbers. D Display zero-value numbers as a pair of right-justified dashes. B Display zero-value numbers as blanks. B overrides D, if both are coded. T Truncate numbers on the left if they cannot fit the field width. Normally, the program formats such numbers with all asterisks.
L Trim numbers on the left and print the result beginning with the left-most digit. With L, w indicates the fields maximum width; the result will be left justified and only as long as required. However, the number must fit within the specified w. R For numbers, replace a numbers trailing 0s (right side of decimal point) with spaces. Program replaces zeros after normal formatting and removes decimal point if there is no trailing 0. For strings, right justify. S Insert a space before the digits of any numbers formatted with L.
All characters are optional. The CDBTLRS characters (case insensitive) may be in any order, but must follow w.d, if w and d are specified. Citilabs recommends using a varying length format unless you must align reported values. The program attempts to accommodate fixed formats. When values do not fit the specified field width, the program drops commas, and then reduces the number of decimal places. If necessary, the program reformats with scientific notation (1E+ppp), if possible, otherwise the program truncates. If printing an unknown range of values, FORM must have a width adequate to accommodate all possible ranges. For delimitedformat output, FORM=16.4LRS is probably adequate. When printing fixed fields, do not specify L, R, and S.
Defining a character print format

Use CFORM to format text items. For CFORM or individual string LIST items, specify print format as:
w.dCDBTLR
where:
67
w Total field width. Set to 0 to indicate that the field width depends on the string length. Specify w anywhere in the format string; any number not preceded by a period specifies w. If a format string specifies multiple w values, the program uses the last value.
NOTE: If the format specifies L, w must be wide enough to
accommodate the number. d Number of leading spaces printed (or periods, if D specified). Specify d anywhere in the format string; any digit preceded by a period specifies d. If a format string specifies multiple d values, the program uses the last value. Valid values range from 0 through 9. The default value is 0. C Center-justify text item. Program applies T first. C overrides L or R. D Print periods (.) in the d characters preceding the field. B Replace blanks with underscore characters (_). T Trim leading or trailing spaces from text item. If L is specified, delete leading spaces. If R is specified, delete trailing spaces. If both L and R are specified, delete leading and trailing spaces and center-justify text item. L Left-justify text item. R Right-justify text item (truncating beginning characters if length exceeds field width).
All characters are optional. The CDBTLR characters (case insensitive) may be in any order, but must follow w.d, if w and d are specified. Unlike FORM, order of w and d is not fixed with CFORM. Citilabs recommends using a varying length format unless you must align reported values. The program attempts to accommodate fixed formats. When text does not fit the specified field width, the program truncates.
PRINTROW
Formats and prints all cells or selected cells of a matrix row to the main print file. Row formatting can be quite voluminous; use this statement judiciously. None of the PRINTROW keywords are trigger keys. You must code all on a PRINTROW statement.
PRINTROW keywords
Keyword BASE1 |?| Description Optional. Flag indicating row format when using non-varying print format (that is, FORM does not contain L). Possible values: T Begin every printed line with a zone number ending in 1. F Begin each printed line with appropriate zone number based on FORM and page width.
MAXPERLINE takes precedence over BASE1: if MAXPERLINE is specified and is not modular ten, BASE1 has no effect. For example:
PRINTROW MW=1-2, 8 FORM=LRD TITLE='form=LRD' PRINTROW MW=1-21 FORM=8 BASE1=Y MAXPERLINE=10
FORM
|S|
Optional. Default format for row values. See Defining a numeric print format on page 66. Default value is 20.5LRD The default value (20.5LRD) provides efficient reporting while maintaining precision. (The L in the format value triggers varying-formatted numbers separated by a single space.) Three spaces precede zone values ending in 1, providing zone distinction. For printing traditional integer boxes, set FORM to 7D. See also PRINT on page 62.
69
PRINTROW keywords (continued)

Keyword J |IP| Description Optional. List of zone numbers formatted for printing. Program sets excluded zones (those not listed) to zero. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. Delimit each number or pair with a comma. For example J=1,3-5,10,12-20 selects zones 1,3 through 5, 10, and 12 through 20 for printing. Valid values range from 1 to the number of zones. Default value is all zones. MAXPERLINE |I| Optional. Maximum number of columns printed on a line. By default, program allows any number of values to be printed on a line, provided line length does not exceed the standard page width. If MAXPERLINE is specified, program ignores page width. MW |IP| Optional. List of work matrices to print. Program prints matrices in ascending order, regardless of specified order. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. Delimit each number or pair with a comma. For example MW=1, 3-10, 13 selects work matrices 1,3 through 10, and 13 for printing. Default value is no work matrices. TITLE |S| Optional. Title printed at the beginning of each MW. The program truncates titles longer than fourteen characters. Enclose the value within quotes ('...') or literal marks ("..."). You may specify only one title per PRINTROW statement, even if printing multiple MWs. By default, the program prints no title.
For neat-appearing reports, Citilabs suggests specifying FORM without the LD, setting BASE1 to true, and setting MAXPERLINE to some integral of 10.
Example
PRINTROW mw=1-2,8 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10
READ
Switches reading of control statements to a different file. The format is:
READ FILE=filename, oldstring=newstring, oldstring=newstring, ....
READ keywords
Keyword FILE Description File to be read. When the end of file is encountered on that file, reading of control statements will continue with the statement following this READ statement. Character string that will replace oldstring in the records in FILE that contain oldstring. Newstring is case sensitive; it will be replaced directly. Character string (not case sensitive) that is to be replaced by newstring. As each record is read from the file, it is scanned to see if oldstring exists in it. If it does, the string is replaced with newstring, and the scan is continued. If either oldstring or newstring contains any special characters it must be enclosed with '...'. It is suggested that strings always be enclosed within '...', but it is not mandatory.
newstring
oldstring
READ statements can be nested up to five levels. A nested READ
may not point to a file that is already in the nest. There is no specific limit to the length and number of replacement strings. The replacement process is designed to not allow a replacement string to replace an earlier replacement. Replacements are done in the left to right order as specified in the READ statement.
Example
READ FILE=BUSLINES, MODE=5 = MODE=3
71
SORT
Sorts an array, or series of arrays. The format is:
SORT ARRAY=name, name, NUMRECS=x
SORT keywords
Keyword ARRAY |S| Description Names of the arrays to be sorted. All names must be declared in an ARRAY statement or as a DBI AUTOARRAY name. A name may be preceded by a + or sign to indicate the order of sort to be applied for that array (within the series of arrays). If a leading + sign is used, the sign and name must be enclosed within quotes (for example, '+myarray'). A + means ascending, and a means descending. If there is no sign for the first name, ascending is assumed. Signs need not be specified, but if they are, a signed array may not follow an array without a sign. Unsigned arrays are carried along in parallel with the sorted records. All the arrays in a SORT statement must be declared with the same size. For example, if one wanted to see a sorted listing of the number of households per zone, two arrays would be required: ZONENO and HH. The SORT statement would be SORT ARRAY=-HH,ZONENO. This would sort the HH array in a descending order and keep the ZONENO array records parallel to it. NUMRECS |S| Specifies the number of records to sort; it may be either the name of a variable, or an integer number. It may not exceed the length of the arrays.
Example 1
SORT ARRAY=A,B,C ; Sort on ascending values in A, carry B & C along with A SORT ARRAY=-A,B,C ; same as above, but sort order for A is descending SORT ARRAY=-A,'+B',-C,D,E ; sort on descending on A, ascending B, descending C SORT ARRAY=-A,B,'+C' ; *** ERROR *** signed name (+C) follows unsigned (B)
Example 2 (Matrix, Fratar, Distribution, Generation)

ARRAY ZONENO=ZONES, HH=ZONES, INCOME=ZONES . . ZONENO[I] = I HH[I] = ZI.1.HH[I] INCOME[I] = ZI.1.INCOME[I] . . SORT ARRAY=-INCOME,-HH,ZONENO LIST= Zone Income HHs JLOOP PRINT FORM=8, LIST=ZONENO[J], INCOME[J], HH[J] ENDJLOOP
Example 3 (Network)
ARRAY AN=LINKS, BN=LINKS, VMT=LINKS ; NETI must be a binary network PHASE=LINKMERGE _L = _L + 1 AN[_L] = A BN[_L] = B VMT[_L] = V_1 * DISTANCE ENDPHASE /* note: The User has to keep count of the records entered into the arrays If links are deleted, the number of entries will be less than the original number of links. */ PHASE=SUMMARY SORT ARRAY=-VMT, AN,BN, NUMRECS=_L LOOP _K=1,30 ; only want to see the highest 30 LIST=AN[_K](6),BN[_K](6),VMT[_K](10.2c) ENDLOOP ENDPHASE
73
Pilot Program
This chapter describes the Pilot program, the basic driver for Cube Voyager application programs. Topics include: Using Pilot program Control statements Examples
75
Pilot Program Using Pilot program
Using Pilot program

The Pilot program is the basic driver for Cube Voyager application programs, but it is also a calculator by itself. Most users will use Pilot only to invoke the individual programs in the order desired. Pilot can check the return codes of the individual programs, invoke system commands, and even perform complex mathematical computations, either for its own use or to pass on to the application programs. Through the use of loops and conditional branching, application programs can be run in any order desired. This section discusses: Output files Process Statement tokens (%...% and @...@)
Output files
A project file, pppp.PRJ, is maintained (generated, if necessary) in the working sub-directory. It contains certain values that help the program to establish unique project identifications between applications that are run at separate times, and those that might be run simultaneously in a separate thread in a multitasking environment. Each application run generates a print and a variable file. The file names are ppppnnnn with extensions of PRN and VAR, respectively. The pppp portion of the name is the project prefix obtained from the P argument on the command line. The nnnn is a sequential number assigned in conjunction with data obtained from the project file. The variable file will contain a list of all the variables and their values that are in the Vars array when the program terminates. If there are no specific Vars to be written; this file will be deleted. Otherwise, the VAR file is renamed to pppp.VAR. Consequently, there will be only one VAR file for each prefix.
NOTE: If Cube Voyager does not seem to sign on correctly, or
indicates strange filenames or default parameters, most likely the pppp.PRJ file has been corrupted. In such cases, the remedy is to
delete the pppp.PRJ file and restart the process. Cube also uses .PRJ files, and it is possible for the user to confuse the two and store Viper configuration information into a Cube Voyager .PRJ, and vice versa.
Process
Recent changes in recommended planning analysis dictate that the simple serial processing may become inadequate. There will need to be recursive applications that are driven by intermediate results. Ideally, this process could be written into a large program, and handled as such. But there are disadvantages to that approach (not discussed in this document). A typical simplified highway application would require that the following steps be run (after the network and trip end data have been compiled and checked):
1. Build paths, and add distribution parameters (terminal and
intrazonal times).
2. Distribute trip ends according to the paths and user functions. 3. Adjust person trip matrices to account for non-model
characteristics, peak period factors, and auto occupancy.

4. Assign trips to the network.
After the application of a series of programs to accomplish this has been completed, you would have to verify the results, and decide if the process needs to be rerun with adjustments, or if the results are satisfactory. The decision process usually will include some type of numerical analysis. If the results of the analysis are not satisfactory, the process may be repeated with some adjustments in the input data, or parameters. Typically, the repeat process is just that: the input data and/or parameters are modified, and the process is resubmitted. Cube Voyager simplifies this process by allowing the user to program the process to adjust the data and/or parameters and automatically repeat the entire process, or just selected portions of it. In the simple case, if the final speeds are not acceptable, the process could be looped until speeds come into a reasonable
77
balance, or until it is decided that a proper balance can not be achieved. That is only a simple portion of the capabilities of Cube Voyager. As the user learns more of its capabilities, he/she will find that he/she can control the process in many innovative ways. The input is comprised of computational, flow control, program, and system statements. The program begins by reading and editing the Cube Voyager specific statements. The non-Cube Voyager statements (system statements, and the statements that follow a RUN statement until its terminating statement) are not edited by Cube Voyager. When all Cube Voyager statements have been edited for basic syntax, and have been stored in the control stack, the program builds a list of variables and their values from all the COMP and LOOP statements and the variables found in the optional VARI file. The list is stored in the Vars array. It then begins processing the control stack at the beginning. Each stack statement is executed, and flow branches to the next appropriate stack statement. When the end of the stack or an EXIT statement is reached, the program terminates. Stack statements fall into several categories:
Computational statements Cause variable values to be updated. Typical control statements are:
COMP (often invoked by simply: var = )

Flow control statements Help to determine which statement is to be performed next. Typical flow control statements are:
GOTO :LABEL ONRUNERRORGOTO CLEARERROR LOOP BREAK CONTINUE ENDLOOP IF ELSEIF ELSE ENDIF EXIT
The program provides the user with the capability to react to fatal returns from Citilabs programs. When a RUN PGM=program statement is executed, the program sets a return code that indicates what type of messages it issued. The return code is either 0 (No messages), 1 (Warning messages), 2 (Fatal messages), or 3 (program aborted); this value is stored in a variable named RETURNCODE. If RETURNCODE is greater than 1, the run is automatically terminated. However, if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate label statement in the script, the run will continue at the labeled statement if the return code is 2. At the labeled statement, the user can further control what is to happen with the run. Typically, the user will issue a message, and possibly continue the run. To continue, the user will have to clear the internal RETURNCODE variable, or subsequent tests of the run status may cause termination. The CLEARERROR statement is used to reset the internal return code; it can not be cleared by setting RETURNCODE=. The CLEARERROR statement also provides a keyword to allow the user to resume executing script at the point following the RUN statement that caused control to be switched to the label specified by ONRUNERRORGOTO.
Program statements Execute a Cube Voyager program. A
program statement always begins with: RUN PGM=

System statements Program initiates an operating-system
command. A system statement is one in which the first field begins with a *, and is at least two characters long. Typically, system statements are used only in pure DOS applications; they will function within Windows applications, but their use is not recommended.
Example
*COPY *.DAT d:
79
Warning: Do NOT use a system statement to initiate another Cube
Voyager application. With the capabilities of these statements, the user can cause the stack to be processed in almost any order desired. With the flow control capabilities, stack segments can be repeated until desired results are achieved. A typical example would be the repeated application of a series of programs beginning with trip distribution and progressing through assignment. If the adjusted speeds from the assignment program differ too much from the speeds that were used in the distribution process, the series should be repeated. Another example could be the repeated application of a program with a slightly different set of parameters, or different input files. It is up to the user to control the flow.
Statement tokens (%...% and @...@)

Any statement may contain tokens for substitution. There are two types of tokens: %...% and @...@. If a Cube Voyager control statement contains a %...% token, the token is replaced by the value of the operating system (OS) environment variable between the % signs. If there is no matching variable name in the environment, the token is unchanged (the variable name is case insensitive). It should be noted that the environment is a copy of the environment prior to the execution of Cube Voyager. (NOTE: Any *SET statements will NOT alter the environment; it is suggested that *SET statements not be used.) There is not much use for %...%, but there might be times where it can be quite helpful. The @...@ tokens are processed only when the statement is being processed by a program called via the RUN PGM= statement. When a program is called, it is provided access to the .VAR file with the current values from the Cube Voyager Vars array. The program can update the file when it terminates, but the Vars array is not updated until Cube Voyager is back in control. If the program reads a control statements that contains a @...@ token, the token is replaced by the value of the file variable named between the @ signs. (NOTE: the
token is replaced literally at the time the program reads the statement; a subsequent change to that variable will not alter the value as read.) If the named variable does not exist in the Vars file, the token is unchanged.
Example
MAX_LOOP = 20 LOOP loop_cnt=1,20 RUN PGM=program ID = This is the @loop_cnt@ out of @MAX_LOOP@ ENDRUN ENDLOOP
In this example, MAXLOOP had to be set because LOOP currently accepts only constants for it limits. To keep it entirely generic, MAXLOOP could be set into the environment (SET MAXLOOP=20) prior to launching Cube Voyager; then the sample could be coded as:
LOOP loop_cnt=1,%MAXLOOP% RUN PGM=program ID = This is the @loop_cnt@ out of %MAXLOOP% ENDRUN ENDLOOP
The READ statement (see Chapter 3, General Syntax) also has capabilities for setting replacement strings in control statements. READ statements are recognized in all Cube Voyager applications.
81
Pilot Program Control statements
Control statements
This section describes the control statements available in the Cube Voyager Pilot program.
Control statement *command BREAK CLEARERROR COMP CONTINUE COPY ... ENDCOPY DOWNLOAD EXIT FILEI FILEO GOTO IF ... ELSEIF ... ELSE ... ENDIF LOOP ... ENDLOOP NEWPAGE ONRUNERRORGOTO PARAMETERS PRINT PROMPT REPORT RUN ... ENDRUN SENDMAIL Description Perform an OS system command with OS window minimized Break out of current loop Clear a run error to allow continued processing Compute variables Continue to end of loop Copy records to a file Download specified file(s) from a URL Exit current phase Specify input file with existing variable values Specify output file PRINTO[#]=fname Jump to a specific control statement Standard IF block Setup a user loop Control new-page processing Jump to a specified :label when an error condition is encountered Specify basic parameter values Print variable values Pause execution and wait for user input Turn reports on/off Runs a specified program Send mail with attachments based on conditions of the run
*command
A statement whose first field begins with a *, and is more than 2 characters long, is considered as a command for the operating system. Cube Voyager will invoke the COMSPEC processor to execute the command. The command will return a code that will be stored in the ReturnCode variable. It is the users responsibility to test ReturnCode, since Cube Voyager does not know the meaning of the return codes. It should be noted that some system commands return 0, even if they are unsuccessful. For example: COPY source dest will return a 0, even if one of the filenames is illegitimate.
NOTE: The *command will be executed in a minimized command
window. This prevents disruption of the display, allowing other tasks to be performed more comfortably while the script is running. If it is required that the command window appear on the display, use the alternate **command rather than *command; for example, '**pause' rather than '*pause'. The '**' approach will be appropriate if the command requires some interaction with the user, or perhaps if it displays some progress which the user always wants to be able to view.
Example
*DEL ABCD*.TMP *IF EXIST OLD.NET DEL OLD.NET
Or:
**DEL ABCD*.TMP **IF EXIST OLD.NET DEL OLD.NET
BREAK
BREAK can be used to break out of a LOOP ENDLOOP block. It must be within a LOOP block. When BREAK is encountered, flow
immediately branches to the statement following the appropriate

ENDLOOP statement. The contents of the LOOP variable are not
altered.
83
Example
LOOP i=1,3 IF (condition) statements ELSE BREAK ; get out of loop ENDIF ENDLOOP
CLEARERROR
CODE RESUME The CLEARERROR statement is used primarily in conjunction with the variable ONRUNERRORGOTO. When the statement is encountered, it automatically resets the internal error code value to 1 and the resume switch to false. It is then the users responsibility to set those values with the keywords.
CLEARERROR keywords
Keyword CODE RESUME |I| |?| Description Internal error code is reset to this value. Can be a value of 0,1. If the value is True (1), and the program detects that it is in an error recovery process set by ONRUNERRORGOTO, control will switch to the statement following the RUN statement that caused control to switch to the recovery process.
Example
ONRUNERRORGOTO = 'MYERROR' :STEP1 RUN PGM=MATRIX ENDRUN ;At this point control will transfer to :MYERROR :STEP2 RUN PGM=. ENDRUN
:STEP3 RUN PGM= ENDRUN :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 RESUME=T ; At this point, control will return to :Step2
COMP
var=expression ID=expression Lambda=expression, etc.
COMP statements compute numeric values and store the value into the var on the left side of the equals sign. Results can be either numeric or character strings (obtained when literal text '...' or text functions are in the expression). It is not permissible to change the mode of a variable during an application. A variable must be defined before it can be used within an expression; it must have appeared as a var= in a statement prior to the expression. The program is designed with this check, to ensure that an edit can be made prior to beginning processing. It could be a big waste of time, if, in the middle of a complicated loop, the program had to abort because it couldnt find a variable at that time. However, this causes a problem with using variables returned from a Cube Voyager program invoked by the RUN PGM= statement. Cube Voyager does not know the mode of the variable and can not edit it prior to actual application. To avoid this problem, Cube Voyager automatically assumes any variable that contains a dot (".") within its name as numeric.
Var is the variable that is to have a new value computed for it. If
the variable matches a name in the Vars array, the result will be updated after the COMP is completed. If it does not exist in the Vars array, it is added as a new variable that can be referenced in subsequent control statements.
85
ID is a special case variable that allows the user to compute a
new ID. Because of the potential conflict with the Cube Voyager system ID control statement, ID may not be the first keyword on a COMP statement. If the result of the expression is not numeric, then the resulting character string is copied to the system ID area. In any event, ID then becomes a working variable.
Lambda is a special case variable, and Lambda must also be a
variable within the expression. When this form is specified, the program solves the expression for various values of Lambda between 0 and 1.0 in hopes of determining a Lambda that will result in a value of 0. The logic for searching is as follows: Set a min and max Lambda (0 and 1.0) Divide the difference between min and max into equal intervals. Solve for all the interval points between min and max. Find the interval that surrounds 0; if none do, it is an error. If more than one interval surrounds 0, the solution is ambiguous, and it is an error. Reset the min and max Lambdas to the interval points that contain 0. If the interval size is not within the accepted tolerance, repeat steps 2-5. When the interval size is within tolerance, perform a straight line interpolation to zero. Store the results into Lambda. This is not a perfect solution, but if the expression is appropriate (does not contain any transverse slopes, and crosses zero one time), a Lambda between 0 and 1 will be found. The current process works on a bisecting principal for developing the test ranges and uses an tolerance interval of 0.000001. For obvious reasons, an expression that contains Lambda as an expression multiplier without any other terms, will always result in Lambda = 0. A division by Lambda will cause program failure when Lambda is tested for 0.
The statement need not have COMP, it may begin directly with var=.
Example
COMP i=matrix.time_to_cbd/100 + sqrt(loop) i=3, j=6, k=9, ijk=1*100+j*10 + k Lambda = 1.2 - lambda * ... COMP ID='This is a new ID for loop' + str(loop_cntr,3,0)
CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements. When CONTINUE is processed flow immediately branches to the ENDLOOP statement in a LOOP ENDLOOP block. It must be within a LOOP block.
Example
LOOP i=1,3 IF (condition) statements ELSE CONTINUE ; jump to ENDLOOP ENDIF ENDLOOP
COPY ... ENDCOPY

FILE=filename Copies records from the input file to a specified file. All the records following the COPY statement, up to, but not including, its matching ENDCOPY statement are copied. The copied records and the ENDCOPY are not processed by Cube Voyager. If there is no matching ENDCOPY, the end of file is considered as the ENDCOPY. The actual COPY takes place when the COPY statement is processed (it can be bypassed or repeated). If there are any COPY or ENDCOPY statements between this COPY statement and its
87
ENDCOPY, they are copied as a data records to the designated file.
The copy process does not scan the records for special features (/*...*/ %...% etc.). If there is no filename, or the filename is invalid, the error is not diagnosed until the COPY statement is actually processed. For that reason, it may be better to place most COPY statements near the beginning of the input file. The primary use of COPY is to allow the user to include small data files within the input file, so that they can be always be associated directly with the control statements. If the COPY fails, ReturnCode is set to 255; an IF statement can be used to test the results.
COPY and ENDCOPY keyword
Keyword Description |F| Name of the file onto which the records are to be copied. Must be an acceptable name for the operating system.
FILE=filename
Example
COPY FILE=temp1; copy lookup file for HIGHWAY . . ENDCOPY COPY FILE=temp2 ;copy with imbedded COPY ... will be copied to temp2 COPY FILE=temp3 ; " " " " " ... " " " " " ENDCOPY " " " " " ENDCOPY signals that the prior record was last IF (ReturnCode==255) ...
DOWNLOAD
URL FILEO CLEARFILEO
Downloads a file from the internet from the specified URL.

DOWNLOAD keywords
Keyword CLEARFILEO |?| Description <1> is a switch to indicate if the local file should be cleared prior to beginning the download. If the file is cleared and the download fails for some reason then the file will not exist on the local machine. If CLEARFILEO=0 then the local file will be overwritten by a successful download but if the download fails then the original local file will remain in its original form. FILEO |S| Local path and file name for the download. Example: 'C:\CITIDOWNLOADS\myfile.dat' URL |S| URL for the target file to download. Example:
URL= 'ftp://www.citilabs.com/outgoing/yourfile.dat'
The site address component (ftp://www.citilabs.com) is not case sensitive but the path and filename component is (/outgoing/yourfile.dat).
EXIT
Terminates the program.
Example
IF (expression) EXIT
FILEI
NOTE: See FILEI on page 44 for general information about FILEI
and for important limitations when using Application Manager. Specifies an input file for Pilot variable initialization. This statement is executed before any step is run, no matter where it is specified in the script.
89
VARI=filename
FILEI keywords
Keyword LOOKUPI |FKV999| Description Name of file containing records for a lookup function implemented with the LOOKUP control statement. Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI. VARI |KF| Specifies the name of the file which is to be read to initialize variables. If not specified, no file is read. The data extracted from the file are stored in the Vars array. If duplicate variables are encountered, the latest one read prevails. Each record from the file contains two fields: a variable name, and its value. The fields may be separated by any number of space(s), with, or without, an = sign. The names may be any reasonable variable names.
The statement need not contain the FILEI control word; it may begin directly with VARI. Normally, VARI is not used; it is used only if there are many variables to be initialized. This could be the case if the application is the continuation of a previous application. A var output file will always be written at the termination of the application.
Example
VARI=XXXX.VAR
FILEO
Specifies an output file for the PRINT PRINTO capability when printing from Pilot. PRINTO[#]=filename
FILEO keyword
Keyword PRINTO |KF| Description Specifies the name of the file where the output from the PRINT statement is to be directed
The statement need not contain the FILEO control word; it may begin directly with PRINTO. Note, all PRINTO index numbers must be unique throughout the script. When adding a Pilot box in Application Manager and linking a file to the PRINTO file box, you must ensure that the index numbers used do not overlap with prior PRINTO indices from prior Pilot steps.
NOTE: When processing the first step, the Pilot program opens all the PRINTO files specified in any script. Therefore, statements
intended to create files in folders that do not already exist will fail.
Example
FILEO PRINTO[1] = "C:\Data\My File.CSV" IF (L1=1) PRINT CSV=T LIST='ITER','DIFF','P_DIFF', PRINTO=1 ELSE PRINT CSV=T, FORM=L, LIST=L1,CONV.DIFF(8.0L),CONV.P_DIFF(6.2L), PRINTO=1 ENDIF IF (ABS(CONV.P_DIFF)<0.05 & L1>1) BREAK *COPY Trips_by_Mode.mat LAST.MAT/Y
GOTO
Jumps immediately to a named statement.
GOTO label
When GOTO is processed, flow immediately branches to the target statement, named :label. Each GOTO statement must have an associated :label statement. Use care when the :label statement is within a different IF or LOOP block. The target statement must begin with a semicolon (:).
Example 1
GOTO hwybuild GOTO :hwybuild
91
Example 2
GOTO hwybuild :hwybuild IF (expression) GOTO :hwybuild ;It is permissible to go backwards.

Performs certain operations based on conditions. There are two forms of this control statement: A single statement:
IF (expression) statement
A block of statements:
IF (expression) ELSEIF (expression) ELSE (expression) ENDIF
You must predefine any expression variables in an earlier COMP VAR statement. (The program automatically defines any variables not predefined, but with a dot (.) in their name as numeric variables.) You may nest but not overlap IF ... ELSEIF ... ELSE ... ENDIF blocks. They may not overlap LOOP ... ENDLOOP blocks. You may append the following control statements to a single IF statement:
BREAK COMP CONTINUE EXIT GOTO
Example
; Single IF examples:
IF (matrix.time_to_bcd < 200000) simple statement IF (expression) EXIT ; Typical IF block: IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) ) statements ELSEIF (loop_cntr > 10) statements ELSEIF (loop_cntr > 5 && diff.time < 32) statements ELSE statements ENDIF
LOOP ... ENDLOOP

Initializes a variable, compares the variable to a constant, and branches to the statement following the LOOP block if the comparison fails.
LOOP blocks may be nested, but they may not overlap other LOOP blocks or IF blocks.
LOOP Var = Begin, End, Incr Statement set ENDLOOP
where: Var is the required user-specified name of the loop-control variable. The module does not protect the value of Var during the loop; computation, program, and other LOOP statements may alter the value of Var. Begin is the constant value to which the module initializes Var. You must specify a value. End is the constant value that the module compares Var to when processing the ENDLOOP statement. You must specify a value. Incr is the constant the module adds to Var before processing the ENDLOOP statement.
93
If the result of the comparison is true, the program branches back to the statement following the LOOP statement. If it is false, control is passed to the statement following ENDLOOP. Processing of the ENDLOOP statement depends on the value of Incr: If Incr is positive, when the value of Var is less than or equal to End, the module goes to the statement following LOOP, otherwise the module goes to the statement following ENDLOOP. If Incr is negative, when the value of Var is greater than or equal to End, the module goes to the statement following LOOP otherwise the module goes to the statement following ENDLOOP.
The module tests the ENDLOOP condition (without incrementing the variable value) when initializing the loop-control variable. If the test fails, the module does not perform any statements within the LOOP block.
Example 1
Executes the code within the LOOP block 10 times.

LOOP iter=1,10 . . ENDLOOP
Example 2
A nested loop, with the innermost loop executing twice for each value of variable xyz: 10,8,6,4,2.
LOOP xyz=10,1,-2 LOOP abc=1,2 . . ENDLOOP ENDLOOP
NEWPAGE
beforepgm afterpgm beforesys aftersys Controls the printed output when the program invokes an external process. All NEWPAGE variables are Boolean items that require a true or false type of value. Once a variable is set, it remains in force, until a new value is encountered. The ...sys variables can help provide cleaner output when a system command is performed. The page counter will not be adjusted for the system output. The ...sys variables are ignored if the system command contains a redirection > symbol.
NEWPAGE keywords
Keyword afterpgm aftersys beforepgm beforesys |?| |?| |?| |?| Description Starts a new page after a PGM returns. Starts a new page after a system command. Sets the line counter so that the invoked PGM will start on a new page. Starts a new page before performing the system command.
Example:
NEWPAGE beforepgm=y afterpgm=n beforesys=y aftersys=y
ONRUNERRORGOTO
ONRUNERRORGOTO is a string variable that can be set to point to a legitimate label statement in the script. Use this feature to react to fatal returns from Citilabs programs. When a RUN PGM=program
95
statement is executed, the program sets a return code that indicates what type of message the program returned on closing. The codes returned are:
Code 0 = No messages 1 = Warning messages 2 = Fatal messages 3 = Program aborted Description The job ran to completion successfully. The job ran to completion but generated one or more warning messages. The job failed to run to completion and generated on or more fatal error messages. The job was aborted by user conditions with the ABORT statement.
This code value is stored in a variable named RETURNCODE. If the RETURNCODE value is greater than 1, the run is automatically terminated. However, if the user has set the string variable named ONRUNERRORGOTO to point to a legitimate LABEL statement in the script, the run will continue at the labeled statement if the return code is 2. See GOTO on page 91 for a description of defining a LABEL. At the labeled statement, the user can provide additional statements to further control what is to happen with the run. Typically, the user will set up a PRINT statement to write a message to the run print file or use a PROMPT statement to issue a message, and possibly request a response from the user to continue the run. The user may now also send an e-mail or text message to report results based on a run error. See SENDMAIL on page 106 for an example of using these statements together. To continue the run, the user will have to clear the internal RETURNCODE variable, or subsequent tests of the run status may cause termination. The CLEARERROR statement is used to reset the internal return code; it can not be cleared by setting RETURNCODE=. The CLEARERROR statement also provides a keyword to allow the user to resume executing script at the point following the RUN statement that caused control to be switched to the label specified by ONRUNERRORGOTO.
It is suggested that the script statements to be processed on the return of an error message be placed at the end of the run script and jumped to with the ONRUNERRORGOTO Statement. Note that an EXIT statement should be used just prior to the :label referenced by the ONRUNERRORGOTO. Placing an EXIT statement prior to the :label will allow the program to terminate without executing the statements for the error condition when the script runs successfully without any errors. Refer also to the CLEARERROR statement (see CLEARERROR on page 84).
Example 1
RUN PGM=MATRIX ENDRUN
At this point the job will terminate because there was an error in the Matrix program (no operations).
Example 2
ONRUNERRORGOTO = 'MYERROR' RUN PGM=MATRIX ENDRUN ;At this point control will transfer to :MYERROR if the MATRIX step fails RUN PGM=. ENDRUN EXIT ; if program gets to this point then exit, no errors were encountered :MYERROR PRINT LIST='Special Message' ; Run will terminate from here with a final completion code of 2
Example 3
ONRUNERRORGOTO = 'MYERROR :STEP1 RUN PGM=MATRIX ENDRUN ;At this point control will transfer to :MYERROR if the MATRIX step fails :STEP2 RUN PGM=. ENDRUN :STEP3 RUN PGM= ENDRUN
97
EXIT ; if program gets to this point then exit, no errors were encountered ; or all errors cleared :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 GOTO STEP3
Example 4
ONRUNERRORGOTO = 'MYERROR' :STEP1 RUN PGM=MATRIX ENDRUN ;At this point control will transfer to :MYERROR if the MATRIX step fails :STEP2 RUN PGM=. ENDRUN :STEP3 RUN PGM= ENDRUN EXIT ; if program gets to this point then exit, no errors were encountered ; or all errors cleared :MYERROR PRINT LIST='Special Message' CLEARERROR CODE=0 RESUME=T ; At this point, control will return to :Step2
PARAMETERS
Specifies basic parameter values for the Pilot run. MAXSTRING
<> is the program default value.

PARAMETERS keyword
Keyword MAXSTRING |KI| Description Specifies the maximum length to use for all string variables. Versions 3.0, and lower, had a maximum length of 127 characters, and violations of this length were not detected. This proved to be too short for some users who were developing strings with considerably longer path names in them. Now the user can specify what the longest string variable is to be. If one has many string variables, a large value could cause excessive RAM to be allocated. (We have seen users jobs with more than 200 string variables.) Specifying a reasonable length will help to preserve RAM, and if a string really needs to be longer than 250, this parameter must be specified. If a variable is computed to exceed this length, a fatal error message will be issued. Default value is 255.
PRINT
Formats and prints a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) The standard Cube Voyager PRINT statement can be used (see PRINT on page 62).
Example 1
LIST= ITER(6) TIMEPERIOD(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001 PRINT FORM=6.0CDLR LIST= ITER, TIMEPERIOD,TOTAL1,TOTAL2 FILE=PRINTFIL.002
Example 2
PRINT PRINTO=1 FORM=6.0CDLR LIST=ITER, TIMEPERIOD, TOTAL1, TOTAL2
99
PROMPT
QUESTION= ANSWER= WAIT= Poses mid-run questions that can alter the flow of the job. When encountering a PROMPT statement, the program lists a question (defined by the QUESTION keyword) and the possible answers (defined by the ANSWER keyword) and waits for a response. The response must select one of the answers. The program will not continue until a proper selection is made. The ANSWER number is returned to Pilot in the variable named ReturnCode, which the user can test via an IF statement. The use of the keyword PRNFILE on the RUN statement allows the user to redirect the print file for any job steps. When the PROMPT dialog box opens, the user can peruse the output from any of the previous step(s) to decide how to respond to the question.
PROMPT keywords
Keyword ANSWER |S5| Description Possible answers. The same rules about quotes in QUESTION also apply here. There may be up to 5 ANSWERs. Question to prompt the user with. Enclose with quotes or ""; if it contains any delimiters, it must be within quotes.
QUESTION
|KS|
PROMPT keywords (continued)

Keyword WAIT |R| Description Number of seconds to wait before automatically continuing using ANSWER [1] as the response. If the user makes a choice before WAIT seconds have expired, the program will not continue until a valid choice is made. 0< WAIT < 50000 When running in command line mode, as soon as a valid number is entered, the program continues with that selection without requiring a press of the Enter key. To gain more response time in command mode, enter an invalid key; the program will then wait until a valid number is entered, and WAIT is disabled. When in windows mode, a dialogue box is opened, and the user can make a choice and then click on the OK button to proceed. Once any choice is made, WAIT is disabled.
When Pilot is launched a Windows dialog box opens, and the user responds by selecting a button.
Example
QUESTION=What do you want to do?, ANSWER=Continue, ; 1 Break out of Loop, ; 2 ABORT ; 3 IF (ReturnCode==3) abort IF (ReturnCode==2) break RUN PGM=MATRIX PRNFILE=myfile.txt . . ENDRUN PROMPT QUESTION=Examine myfile.txt to determine response to, ANSWER=Sum Too High, Sum Too Low, Sum Acceptable Get Out of Loop IF (RETURNCODE==3) break PROMPT
REPORT
VARS STACK TRACE
REPORT keywords
Keyword STACK |?| Description Writes the internal stack. This is mostly used for program debugging, but can be useful for relating TRACE information to internal notation. STACK is static; if set to true, writes occur at the beginning of stack processing. Controls the listing of the stack statements as they are processed. TRACE can be turned on and off at any time, thus controlling the amount of output as desired. Each statement will be listed with an internal number, the control statement name, and, in most cases, additional information. TRACE is a trigger key. When set to true, the program lists the current variables and their values from the VARS array.
TRACE
|K?|
VARS
|?|
Example
REPORT Vars=y REPORT Trace=y ; turn stack tracing on REPORT Trace=n ; turn stack tracing off
RUN ... ENDRUN

Loads and executes a program. PGM=name CTLFILE=name PRNFILE=name REDIRECTIN REDIRECTOUT PARAMETERS
Pilot loads and executes the program specified by PGM. Pilot attaches any control statements between the RUN and ENDRUN command to the specified program. Only the specified program will read and edit these statements.
ENDRUN signals the end of the RUN statement. Though optional, Citilabs recommends always using ENDRUN. A system command (*....) or another RUN statement also signals the end of a RUN statement.
You can disable a RUN statement by changing it to !RUN. However, a !RUN statement requires a corresponding ENDRUN. You can also disable a RUN statement by placing the statement in a null block (/* .... */) or by using a GOTO statement. Pilot expects to load a Cube Voyager program; the associated DLL and TDF files must be directly accessible. If you are running a nonCube Voyager program, you may use additional keywords. The program name may be a standard OS file name (path is optional, but is recommended for non-TRIPS programs). The program may be a TRIPS program, a Cube-related program, a clientdeveloped program to run in accordance with Citilabs specifications, or a standard OS executable RUN file.
RUN keywords
Keyword CTLFILE |F| Description Optional. File be used as the programs standard input. If CTLFILE is not specified, it is assumed that the data follows the RUN statement (up to, but not including, the next ENDRUN statement), and the those records are copied to a temporary file. If there are no data records following the RUN statement, CTLFILE is ignored. Optional. Parameters that the program expects to find on the invoking command line. If a parameter will contain any special characters (comma, space, dash, math operator, semi-colon), enclose the parameter within quotes ( or ""). If a parameter is to contain quotes, the quoted parameter must be enclosed by the opposite quote. For example, if the program requires abc to be passed to it, it should be coded as "abc", or if it requires "def ghi", it should be coded as "def ghi". Parameters may be coded as a series of values, or, in most cases, as one string of many parameters enclosed within one set of quotes.
PARAMETERS
|SV|
RUN keywords (continued)

Keyword PGM |S| Description Program to be run. Pilot determines if it is a Cube Voyager program by searching for both program.DLL and program.TDF in the directories discovered in the following order: Directory from which Pilot was loaded Current directory Windows system and then the Windows directories Directories that are listed in the PATH environment variable
If the program is not located that way, it assumes that it is a non-Cube Voyager program and tries to locate it by applying a somewhat different set of criteria to determine the full name for the program, and to locate the directory where it resides. If program has no file extension and the last character is not a dot (.), append .exe to program. If program contains path information (has a \ or :), use that path If program does not contain path information, locate the program by searching the directory from which Pilot was loaded, and then the directories as registered with the operating system If program*.exe is found, look in that directory for the latest version of the program by assuming program#.exe and use the highest # file. Thus, if name.exe, name1.exe, and name3.exe are all found, name3.exe will be assumed. PRNFILE |F| Optional. File where the program expects to write its standard system print output. PRNFILE will be ignored if it is determined that a TRIPS program is being run. Optional. Switch to indicate that CTLFILE is to be directed into the program. Optional. Switch to indicate that the program is to direct its output to PRNFILE, if PRNFILE is also specified.
REDIRECTIN REDIRECTOUT
|?| |?|
If it is determined that a TRIPS program is being run (by the presence of &FILES OPRN keyword in the CTLFILE), PRNFILE, REDIRECTIN, and REDIRECTOUT are ignored. The RUN statement is designed to allow easy integration of nonCube Voyager programs directly in line with a standard run and to have the printed output of the program directly incorporated into the standard Cube Voyager print file. There may be programs
whose basic operations will not allow this type of integration. In those situations, it is possible that the use of the Pilot * statement will allow the direct running of the command. The RUN statement for non-Cube Voyager programs generates a system command that is structured and executed based upon the following decision table. If PGM is a TRIPS program (contains &FILES OPRN=):
pgm ctlfile parameters >tprn
If PGM is not a TRIPS program:

RDI F F F F T T T T RDO F F T T F F T T prnfile T F T F T F T F Generated command
pgm ctlfile prnfile parameters pgm ctlfile parameters pgm ctlfile parameters >prnfile pgm ctlfile parameters >tprn pgm prnfile parameters <ctlfile pgm parameters <ctlfile pgm parameters <ctlfile >prnfile pgm parameters <ctlfile >tprn
NOTE: 1. If ctlfile has no length, it is not placed on the command line 2. tprn is a temporary file which is copied to the Cube Voyager
print file.
3. DRI/RDO = redirectin/redirectout Examples
RUN PGM=program parameters=datain, dataout Command: Path\program.exe datain dataout RUN PGM=abc.exe ctlfile=datain prnfile=dataout parameters=abc Command: Path\abc.exe datain dataout abc RUN PGM=ME ctlfile=datain parameters="/m=20" "/demo"
Command: Path\MVESTM70.EXE datain /m=20 /demo RUN PGM=ME ; ctlfile follows this statement; will be copied to tfile Command: Path\MVESTM70.EXE tfile RUN PGM="c:\util\pkzip.exe" parameters="junk.zip t*.", "-v c", prnfile=zip.txt, redirectout=t Command: c:\util\pkzip.exe junk.zip t*. -v c >zip.txt RUN PGM=MATRIX ; standard Cube Voyager run
SENDMAIL
SMTPSERVER FROM TO CC SUBJECT MESSAGE ATTACHMENTS USERNAME PASSWORD PORT
Immediately sends an e-mail. Use to transmit the status of a job or job step to a recipient. The keywords SMTPSERVER, FROM, TO, and SUBJECT must be specified; the others are optional. E-mail messages can also be sent as text messages to a cell phone.
SENDMAIL keywords
Keyword ATTACHMENTS CC FROM MESSAGE |S| |S| |S| |S| Description List of file names sent as attachments. There is a maximum of 1000 attachments. E-mail address(es) for copied recipient(s). E-mail address to be sent as the return List of individual lines to send in the message area of the e-mail. Each string is a separate line. There is a maximum of 1000 messages. Password for the account specified in USERNAME, if the SMTP server requires secure logon. If coding your script in Cube, you can insert the password value with the Insert menu command then selecting Password for email. Cube opens a Password Entry dialog box, which t allows you to mask the password for security.
PASSWORD
|S|
PORT SMTPSERVER
|I| |S|
<25> is the TCP PORT number. The typical SMTP server uses PORT number 25. Name of the send-mail server. An example might be: smtp.sbcglobal.yahoo.com
SENDMAIL keywords (continued)

Keyword SUBJECT TO |S| |S| Description Subject of e-mail. E-mail address(es) of the recipient(s). Separate multiple recipient addresses with a comma. You can also send mail as a text message to a phone and account that supports text messaging. Examples of cell phone provider messaging e-mail addresses are: T-Mobile: {phone#}@tmomail.net Sprint:
{phone#}@messaging.sprintpcs.com
Verizon: {phone#}@vtext.com
Check with his/her cell phone service provider to verify the appropriate address. USERNAME |S| User name for mail account, if the mail SMTP server requires logon.
Example
Using SENDMAIL with ONRUNERRORGOTO, RETURNCODE, and CLEARERROR to generate e-mail with attachments for various conditions
;======================================================================== ONRUNERRORGOTO='ONERROR' ; set LABEL to jump to if an error occurs StepName='Step 1 - Network' RUN PGM=NETWORK NODEI=DTWNNOD.DBF, LINKI=DTWNLNK.DBF NETO=DTWNTPP1.NET ZONES=24 ENDRUN StepName='Step 2 - Network' RUN PGM=NETWORK NODEI=xDTWNNOD.DBF, LINKI=DTWNLNK.DBF NETO=DTWNTPP1.NET ENDRUN SENDMAIL SMTPSERVER='smtp.yourname.com', FROM='[email protected]',
TO='[email protected],[email protected]', CC='The Boss<[email protected]>', Subject='Email from Voyager, Run Completed, No Error', Message='Voyager Run Completed', 'There is no run error', ATTACHMENTS='DTWNTPP1.NET' Exit ; if no errors then this step gets executed and terminates the run :ONERROR ; if an error occurs the processing jumps to this location rcode=str(returncode,2,0) ; returncode will have value=0,1,2,3 SENDMAIL SMTPSERVER='smtp.yourname.com', FROM='[email protected]', TO='[email protected]', Subject='Email from Voyager, Run Error', Message='There is a run error, returncode:',rcode, 'On Step ',StepName ; Also text message a cell phone SENDMAIL SMTPSERVER='smtp.yourname.com', FROM='[email protected]', TO='[email protected]', Subject='Email from Voyager, Run Error', Message='There is a run error, returncode:',rcode, 'On Step ',StepName ; If the error happens on step 2, ignore the error, resume the run if (StepName='Step 2 - Network') CLEARERROR resume=t code=0 endif
Pilot Program Examples
Examples
This section contains examples using the Pilot program: Pilot example 1 Pilot example 2 Pilot example 3
Pilot example 1
/* Example 1: Typical application, with no logic. */ RUN PGM=NETWORK . data for NETWORK to build a network ENDRUN RUN PGM=HIGHWAY . data for HIGHWAY to build LOS files ENDRUN RUN PGM=DISTRIBUTION . data for DISTRIBUTION to distribute trip ends ENDRUN RUN PGM=MATRIX . data for MATRIX to combine and factor matrices ENDRUN RUN PGM=HIGHWAY . data for HIGHWAY to load trips to highway network ENDRUN RUN PGM=NETWORK . data for NETWORK to analyze assignment ENDRUN
Pilot example 2
/* Example 2: A little more complicated. All the RUN statements would have statements following them (including an ENDRUN statement). They are excluded, so that process can be presented more briefly. */ LOOP iter=1,5 COMP ID='This is iteration' + str(iter,2,0) RUN PGM=NETWORK
RUN PGM=HIGHWAY RUN PGM=DISTTRIBUTION RUN PGM=MATRIX RUN PGM=HIGHWAY RUN PGM=NETWORK ENDRUN IF ( NETWORK.RESULT <= 0.02) BREAK ; criteria already satisfied ENDLOOP
Pilot example 3
/* Example 3: more capabilities. */ LOOP iter=1,5 COMP ID='This is iteration' + str(iter,2,0) RUN PGM=NETWORK RUN PGM=HIGHWAY RUN PGM=DISTTRIBUTION RUN PGM=MATRIX RUN PGM=HIGHWAY RUN PGM=NETWORK ENDRUN IF ( NETWORK.RESULT <= 0.02) GOTO Early_Converge ELSEIF (NETWORK.RESULT <= 0.04) LIST=' exit early ' + str(iter,2,0) + ' iterations GOTO TRANSIT ENDIF ENDLOOP LIST='Speeds did not converge' EXIT :Early_converge LIST='Convergence after ' + str(iter,2,0) + ' iterations' :TRANSIT ID=BEGIN TRANSIT PROCESSING REPORT vars=y ; list current variables Newpage BEFORESYS=y, AFTERSYS=y ; copy transit files to ramdisk *COPY d:\transit\neta\altx*.* r: RUN PGM=PUBLIC TRANSPORT read r:altx01.set ENDRUN IF (RETURNCODE > 0) EXIT *COPY r:trnnet d:\transit\neta
Fratar
This chapter discusses Fratar distribution, a process for modifying a matrix values. Topics include: Using Fratar Control statements Examples
Fratar Using Fratar
Using Fratar
Fratar distribution is the process of modifying a matrix of values based upon a set of production and attraction factors for each of the zones in the matrix. The process is a relatively simple iterative one: In the first iteration, each row in the matrix is factored according to its production factor. At the end of the iteration, the row totals will match the target row values, but the column totals will most likely not match their targets. In the second iteration each column in the modified matrix is factored according its attraction factor. At then end of the iteration, the column totals will match the target column values, but the row totals may not match their targets. This process continues for some number of iterations; the row and column totals should converge towards the target totals. When the criteria for convergence is met, the process is complete. A complete convergence (target row and column totals obtained for all zones) can be obtained only if the target grand control totals for rows and columns are the same. The program makes adjustments to guarantee that the target grand totals do match. It is possible that the user input values and specifications can preclude obtaining matching totals. In such cases, the program will fatally terminate. This section discusses: Specifying target values Controlling target totals Convergence Iteration control Multiple purposes
Fratar Using Fratar
Specifying target values

There are several typical ways in which the control totals can be specified: direct values, growth factors (explicit and implicit), or some combination of both. All specifications are via the SETPA control statements. An array of production values (Ps) and an array of attraction values (As) are maintained for each purpose. To simplify this description, the term value will be used to mean either direct values or growth factors. There must be a set of production values and attraction values for each matrix to be factored. They are input to the program via P, A, PGF, and AGF expressions. If direct values are to be input, the P and A expressions are used. If growth factors are to be input, the PGF and AGF expressions are used. Direct values and growth factors can be mixed for a purpose, but a complete understanding of the SETPA statement is necessary. Each of the keyword expressions is computed for an array of values for all zones. P[1] = ZI.1.HBWP2000 would cause the program to simulate the expression:
JLOOP J=1,ZONES P[1][J] = ZI.1.HBWP2000[J] . ENDJLOOP
Similarly, A[]=, PGF[]=, and AGF[]= expressions are computed for corresponding arrays. To provide the capability of mixing P and PGF for a purpose, the SETPA statement may include the basic INCLUDE and EXCLUDE filter specifications. If either, or both, of these filters are specified on a SETPA statement, they apply to all expressions on that statement. To specify P and PGF for the same purpose, separate SETPA statements are used; each would have its own zonal filter set. If the sets overlap, the latest SETPA values replace any prior values. If the final value for a P or A is 0, the program revises it to a growth factor of 1.0.
Example 1
SETPA P[1]=ZI.1.HBWP2000, A[1]=ZI.1.HBWA2000 INCLUDE=1-500 SETPA PGF[1]=ZI.2.EXTW/2 AGF[1]=PGF[1] INCLUDE=501-550
Fratar Using Fratar
In this example, the values for zones 1-500 would be the direct values obtained directly from the ZI.1.HBWP2000 array, and the values for zones 501-550 would be the growth factors obtained from the ZI.2.EXTW array (divided by 2). In most cases the values will be obtained from ZDATI (zonal data) files, or LOOKUP functions, but that is not an absolute requirement. Standard numerical expressions (J being the only viable variable that could be included) are used to compute the values. Sometimes, it is desirable to input specific values.
Example 2
SETPA P[1]=5000 INCLUDE=255 ;input a specific value SETPA A[1]=sqrt(J/2+25**3.5) ;would be possible, but weird.
A special feature of these expressions is that if the result is less than zero, it is not stored. After all SETPA P,A,PGF, and AGF expressions are processed, the program performs a zonal (I) loop, obtaining the matrix values for each purpose. The matrices are obtained by solving the SETPA MW[]= expressions. Again, the INCLUDE and EXCLUDE filters are employed, but care must be exercised, if they are specified. The MW expressions are array notation, but applied for each I zone. Therefore the filters will apply to both the I and J zones.
Example 3
SETPA MW[1]=... INCLUDE=1-500 ; will compute only the I=1-500 to J=1-500 portion of the matrix.
Controlling target totals

After processing the input matrix, the target totals for any growth factor values can be fully determined (value = gf * input). Next, the program adjusts the values to insure that the P and A totals match for each purpose. There are several options for adjustment; they are specified by the use of the CONTROL keywords on the SETPA statement. There may be a CONTROL specification for each purpose, and if the CONTROL for any purpose is specified more
Fratar Using Fratar
than one time, the latest value prevails. If no CONTROL is specified it defaults to PA. The valid values for CONTROL are: P, A, PA, PL, AL, and PAL. The meanings are:
Value P A PA Description The P totals control; all values in the A array will be factored so that the A totals will match the P totals. The A totals control; all values in the P array will be factored so that the P totals will match the A totals. All values in both the P and A arrays will be factored so that their totals will match the average of the initial totals.
Sometimes only certain zones are to be modified, and the remainder of the zones are to be kept constant. The program keeps track of the zones that are eligible for modification by noting which zones have target values that differ from the input value by more than one. If the letter L is appended to any of the CONTROL values, it indicates that the modifications are Limited to only the zones that have change. Use of the this feature can, in some cases, lead to a situation where a matrix grand total can not be properly computed. If that is the case, the program will fatally terminate.
Value PL AL PAL Description The P totals control. The changed zones in the A array will be factored so that the final A total will match the P total. The A totals control. The changed zones in the P array will be factored so that the final P total will match the A total. The values in P array for zones that have P changes, and the values in the A array for zones that have A changes will be factored in such a manner that the final P and A totals match the average of the initial P and A totals.
It is impossible to modify any cell, column, or row, that has zero to begin with. If a target value is specified for a zone that initially had no total, a warning message is issued. Traditionally, some modelers would scale a matrix by a value (usually 10, or 100), and then fill in all empty cells with one. This is not necessarily a good, or bad, solution. But, because of the potential problems associated with this approach, zero accountability is not included in this program
Fratar Using Fratar
directly. If the scaling scheme is to be applied, a prior application of the Matrix program can be used to scale and fill in a matrix in any desired manner. It could also be achieved by setting the SETPA MW expression to: max(1,mi.n.n*10).
Convergence Iteration control

A concern is when to stop the iterating process; there are several ways to control it. The user can specify a maximum number of iterations, so that no matter how the convergence is progressing, the process will not exceed that number. After each iteration, the program computes an RMS error value based upon the integer differences between the computed and target row or column totals. After odd iterations, column total differences are checked, and after even iterations, row differences are checked. If the RMSE value is less than the MAXRMSE parameter value, the solution is achieved. It is believed that this process will eventually reach convergence. But if, due to some unforeseen conditions, the RMSE value begins to oscillate, the program detects the oscillation, and terminates the process at the minimum RMSE. If there are multiple matrices being factored, they may reach optimum solutions at different times. If this happens, the solved matrices are held steady, and the others continue to be processed. A small example of this process:
After Iteration 1: RMSE = 22.87
Zone 1 2 3 Total Target 1 57 64 102 223 240 2 24 106 61 191 200 3 19 30 137 186 160 Total 100 200 300 600 600
Fratar Using Fratar
As dictated by row factoring, the row totals are correct. But, the column totals do not quite match the target. Another iteration is performed, and the results appear as:
After Iteration 2: RMSE = 7.94
Zone 1 2 3 Total 1 61 69 110 240 2 25 111 64 200 3 16 26 118 160 Total 102 206 292 600
The column totals are now on target, but the row totals are not quite on target. This process goes on, back and forth, until either the RMSE drops to the MAXRMSE level, or the number of iterations reaches the MAXITERS value. In this example, the final solution is reached after 5 iterations (MAXRMSE=0.01 and MAXITERS=10).
After Iteration 5: RMSE = 0
Zone 1 2 3 Total 1 60 70 113 240 2 25 190 64 200 3 16 26 118 160 Total 102 206 292 600
All values are shown to the nearest integer and thus may not total exactly. Internally, the values are carried with more precision.
Multiple purposes
The number of purposes is determined by the highest P, A, PGF, AGF, or MW index found on any SETPA control statement. The program assumes that there will be purposes from one, monotonically, through that highest index. The distribution is performed prior to entering the main Matrix program I loop. When the main I loop is processed, MW[1] through MW[highest purpose]
Fratar Using Fratar
are initialized with the final matrices from the Fratar distribution. After the factoring process is complete, a standard Matrix program I loop is performed.
Fratar Control statements
Control statements
All the standard Matrix statements are valid in Fratar, and a few additional ones are available. Fratar is a subset of the Matrix program. This section only describes the differences between the Matrix and Fratar control statements. For descriptions of other control statements see Chapter 9, Matrix Program. Fratar statements not in Matrix:
SETPA
Fratar keywords not in Matrix:

PARAMETERS MAXITERS= MAXRMSE= REPORT ACOMP= PCOMP=
This section describes: PARAMETERS REPORT SETPA
PARAMETERS
Sets general parameters. MATOEVERY MAXITERS MAXPURPS MAXRMSE ZONES
In addition to the standard Matrix parameters (see PARAMETERS on page 518), you may specify the parameters described here.
PARAMETERS keywords
Parameter MATOEVERY |K?| Description Switch that can force the program to write output matrices for every iteration, instead of waiting until the last iteration. For large systems, not writing output matrices for each iteration saves considerable computer time, but forces another processing iteration to write the matrices after reaching convergence. Writing output matrices for each iteration increases run times for each iteration, but prevents the program from having to run another iteration to write the output matrices after reaching convergence. If you anticipate that there will be many iterations before reaching convergence, set this switch to false. If you anticipate that the process will involve only a few iterations, set this switch true. MAXITERS |KI| Maximum number of iterations. If the MAXRMSE criterion is met, the number of iterations actually performed could be less than this value. The default is 9, and the max is 99.
PARAMETERS keywords (continued)

Parameter MAXPURPS |KI| Description Number of purposes to process in this application. The keyword is not required, because the program will determine the value from the detection of the values on the SETPA statements. But, if this value is provided, and it conflicts with the SETPA statements, a fatal message will be issued. Cutoff criteria. If the RMSE for a purpose does not exceed this value, a solution is assumed for the purpose. The default is 10, and the minimum is 0. ZONES |KI| Highest zone number to process. If the number of zones cannot be ascertained from the project file or from any binary input matrices, ZONES must be provided, or the value will default to 100. If present, this value controls the application. Normally, there will be an input matrix file, so this keyword should not be required.
MAXRMSE
|KR|
REPORT
PCOMP ACOMP In addition to the REPORT keywords available for Matrix, the following are also available for Fratar:
REPORT keywords
Keyword ACOMP |KIP| Description Requests report comparing computed to target attractions for specified purposes. The report is in a format that is similar to the MARGINS report. The values are reported as nearest integers (without decimal places). Only the purposes specified by the keyword are reported, but they are reported for all odd iterations. Same as ACOMP, but refers to productions, and refers to only even iterations.
PCOMP
|KIP|
Example
ACOMP=1-3,5 ;request reports for the specified purposes
SETPA
Establishes base productions and attractions. P A PGF AGF MW CONTROL INCLUDE EXCLUDE The SETPA statement is required; if it is not included, the program will fatally terminate. These statements define how the production and attraction factors are to be obtained, and how many purposes are to be processed. There should be a P[]= and A[]= and MW[]= expression for every purpose beginning with 1 and continuing, monotonically, until all purposes are defined. The highest index encountered establishes the number of purposes. If there are any holes in the purpose scheme, the program will issue a warning statement. The Ps and As are computed from the expressions that are supplied. In most cases, the expression will simply point to a ZDATI file variable. Complex expressions are allowed, but the use of any variables in the expression could cause unpredictable results. In a purpose where the Ps and As are the same for each zone, it is acceptable to set the Ps, and then set the As equal to the Ps. The SETPA expressions are computed in the order in which they appear in the control stream, and they are computed only one time -- prior to the first iteration. For each array, the expression is solved in a loop of J=1-Zones, and the results are stored in the A,P,MW [n][J] cells. The keywords may not have a zone index in the SETPA statement. If the same purpose is referenced more than one time, the subsequent values will replace the prior values. Duplication of purposes might be helpful if values for different zones for a
purpose are to be obtained from different sources, or if different INCLUDE/EXCLUDE filters are to be used (different SETPA statements must be used for different filters).
SETPA keywords
Keyword A AGF |NV| |NV| Description Expression solved to set the target attraction totals for the indexed purpose. Expression solved to set the target attraction growth factors for the indexed purpose. The final totals are obtained by multiplying the growth factors by the initial input matrix totals. String indicating how to adjust final target totals to enable convergence. The possible values are: P A PA PL Production totals control; As will be adjusted Attraction totals control; Ps will be adjusted Both Ps and As will be adjusted to the average of the P and A totals. Same as P, but only As in adjustable zones will be adjusted
CONTROL
|SV*|
AL Same as A, but only Ps in adjustable zones will be adjusted PAL Same as PA, but only adjustable zones will be adjusted EXCLUDE |IP| Processed the same as EXCLUDE on COMP statements (see COMP on page 43). If it is used, the loop will not be processed for any zones in the list. EXCLUDE filtering follows any INCLUDE filtering. Processed the same as INCLUDE on COMP statements (see COMP on page 43). If it is used, the loop will not be processed for any zones not in the list. INCLUDE filtering precedes any EXCLUDE zones.
INCLUDE
|IP|
SETPA keywords (continued)

Keyword MW |NV| Description Expression solved for each zone during the first iteration. The result is the matrix row for that zone. Usually, this expression will be a single variable name such as MI.n.n, but that is not required. Expression solved to set the target production totals for the indexed purpose. Expression solved to set the target production growth factors for the indexed purpose.
P PGF
|NV| |NV|
Example
Using single CONTROL keyword:

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

SETPA P[1]=(ZI.1.P1) A1=(ZI.1.A1) MW1=1 CONTROL[1]=A SETPA P[2]=(ZI.1.P1) A2=(ZI.1.A1) MW2=1 CONTROL[2]=P SETPA P[3]=(ZI.1.P1) A3=(ZI.1.A1) MW3=1 CONTROL[3]=PA
Fratar Examples
Examples
/* The following two steps (MATRIX and FRATAR) setup and run the small example used in the Introduction to illustrate convergence. It is a good example of different ways to play with MATRIX. The MATRIX step generates a 3 zone matrix, and the FRATAR step modifies it. */ RUN PGM=MATRIX ZONES=3 MATO=3ZONE.MAT,MO=1 IF (I==1) MW[1][1]= 57 MW[1][2]= 24 MW[1][3]= 19 IF (I==2) MW[1][1]= 64 MW[1][2]=106 MW[1][3]= 30 IF (I==3) MW[1][1]=102 MW[1][2]= 61 MW[1][3]=137 ENDRUN RUN PGM=FRATAR MATI=3ZONE.MAT MATO=3ZONEF.MAT,MO=1 LOOKUP NAME=TOT,LOOKUP[1]=1,RESULT=2,LOOKUP[2]=1,RESULT=3, R='1 100 240', '2 200 200', '3 300 160' MAXRMSE=0.01 MAXITERS=10 SETPA P[1]=TOT(1,J) A[1]=TOT(2,J) MW[1]=MI.1.1 ACOMP=1,PCOMP=1 MARGINS=1 ENDRUN
Fratar Examples
Highway Program
This chapter discusses the Highway program. Topics include: Using the Highway program Phases Control statements Theory Examples
The junction file is part of the Highway program. For information about the junction file, see Chapter 7, Intersection Modeling.
Highway Program Using the Highway program
Using the Highway program

This section provides helpful information about using Cube Voyagers Highway program. Topics include: Highway introduction Highway program control statement overview Functions and built-ins Getting started with assignment Path-based tolls
Highway introduction
The Highway program now supports junction or intersection constrained assignment as well as the typically link based capacity constrained assignment. Junction-constrained assignment requires the coding of the junction or intersection movements and controls. The descriptions below refer to link based traffic assignment. Refer to Chapter 7, Intersection Modeling, for a detailed description of intersection modeling and the data requirements. The Highway program now can write the full path file from an assignment run including full results from every iteration. This makes many forms of path based analysis directly accessible in Cube without having to rerun the assignments with specific commands in the scripts. See the description of PATHO in FILEO on page 196 and PATHLOAD on page 223; also refer to Highway path display on page 278 of the Cube Base Reference Guide for information about path-based analysis in Cube. The Highway programs primary function is to assign trips to highway network links. A highway network, zonal matrices, zonal data, junction data and turn penalties can be input, and a loaded network, new matrices, turning volumes, final junction delay and reports can be output. There are basic default operations, but the user can control much of the process
A typical assignment program builds paths based upon link costs (impedances) and assigns trips to those paths for each origin zone. After all origin zones have been processed, link costs are updated based upon the level of congestion on each link. Then the entire path and assignment process is repeated. This process continues until some criteria for termination is reached. The volumes from each iteration are combined to form a weighted assignment. Different criteria are used to determine when enough iterations have been performed. Almost all of the operations follow a fixed pattern, and are driven by basic parameters. Various options are usually available to provide the user with additional outputs. Select link analysis is a major tool for most users. This process traps the trips that meet the select link criteria, and usually writes them to output matrices. The Highway program provides the same capabilities as a traditional assignment program, but functions somewhat differently. There are only a few automatic operations, and global parameters are used sparingly. The program operates by processing in various phases. In each phase the program performs certain specific operations, and optionally processes a stack of operations provided by the user for that phase. In addition to phase operations, the user can enter FUNCTION statements (in the form of numerical expressions) that are to be performed in place of default functions at certain times by the program. For normal processing, there must be a way of computing certain required values for each link. If there is no automatic way for the program to determine these values, the user must supply the process to obtain them. Normally, the values are computed directly from the variables in the input network, but since there is no fixed format of the network, the required variables may not be present. In that case, the LINKREAD phase can be used and formulated to provide these values. The underlying assumption is that path building and capacity restraint are based upon a generalized cost on each link. In most cases, the cost is time. There are several ways to obtain the free flow time (T0), and the initial path time (T1). The hierarchy of the processes to obtain T0 and T1 is outlined below, in the description of the LINKREAD phase.
The best advice is that the network should contain a variable that can be used directly for T0, or that it contains variables so that DISTANCE and SPEED information can be easily obtained. If the variables DISTANCE, LANES, and SPDCLASS are in the network, T0 can be computed from the DISTANCE and the values from the SPDTAB speed table. If the network is the result of conversion from a TRANPLAN network, it will usually contain variables named DISTANCE, TIME1, and CAPACITY. DISTANCE and TIME1 are usually in hundredths of miles and hundredths of minutes, respectively. CAPACITY is normally the total capacity for the link. TIME1 is the starting time for assignment, and is not necessarily a true T0 (free flow time). If such a network is used directly, the LINKREAD stack should contain the following statements:
DISTANCE=LI.DISTANCE/100 ; not absolutely necessary T0 = LI.TIME1/100 C = LI.CAPACITY * CAPFAC ; factor to get on same scale with trips
In reality, it would be better to rename and scale the variables appropriately during the network conversion process, so that it is not necessary to remember to deal with them in the Highway program. ProductName converted networks will be in nearly the correct format, but the user should also be aware to scale the variables to the correct values. If the network distance is properly scaled, T0 will be computed from the DISTANCE, SPDCLASS, LANES, and the SPEED portion of the SPDCAP tables. The major phases in the process are: SETUP Optionally, initialize basic user arrays and processes LINKREAD Obtain required values for each link ILOOP Build paths and assign trips from each origin zone ADJUST Examine iteration results, test for convergence and adjust link values for next iteration
CONVERGE Optional phase where user can specify their own convergence rules and stopping criteria
These phases are processed even if the user does not explicitly specify any controls for them. However, if there is no explicit ILOOP phase, the program will terminate with an appropriate message. The phases are specified by using PROCESS PHASE=PhaseName statements; for simplistic purposes, most users simply use the short form: PHASE=PhaseName without the PROCESS control word. A PHASE is closed with either an ENDPROCESS or an ENDPHASE statement. These two statements are interchangeable. A PHASE will also be closed if an new PROCESS PHASE=PhaseName or PHASE=PhaseName statement is encountered prior to an ENDPROCESS or ENDPHASE. For more information about phases, see Phases on page 150.
Highway program control statement overview

There are several types of control statements in the Highway program:
Definition statements Define static processes. Examples
include: FILEI and FILEO which define the input and output data FUNCTION LOOKUP PARAMETERS
Computational statements Update variable values. Examples
include: COMP PATHLOAD SET

Reporting statements Accumulate or dynamically display
values. Examples include:
PRINT PRINTROW REPORT

Flow control statements Set statement order. Examples
include: GOTO :label LOOP BREAK CONTINUE ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For details about control statements, see Control statements on page 174.
Functions and built-ins

This section lists built-in variables, arrays, and functions that can assist in performing most desired operations: Built-in variables Built-in arrays Built-in functions Built-in variables available in the CONVERGE phase Built-in functions available in the CONVERGE phase
NOTE: The names are not case sensitive, but capitalization may
make them a bit more meaningful. You can also use FUNCTION statements to enter single expressions for computing certain values. See FUNCTION on page 206.
Built-in variables
Only the variables with a * may be stored into by the user; the others are reserved.
Variable _SKIPTOI Description In the ILOOP phase, jump to the specified zone immediately. Its value is checked at the end of the current I. If specified, Cube Voyager sets I to that value. The specified value must be greater than the current I. See Example of _SKIPTOI on page 141. Capacity used in congestion expressions; Link distance expressed in miles or kilometers. Current rows zone (ILOOP). Current iteration number. Column index, usually 1, and varies (1-Zones) for MW[] and JLOOPs. Lambda value computed for this iteration; do not be reset. Last iteration indicator, usually set to the MAXITERS parameter Class of the current link; you can modify in LINKREAD. Link number (available during any implied link loops) Result of LOWEST(). Number of nodes. Number of links. Zero value means do not include in equilibrium; you can modify in LINKREAD. Link speed. Link free flow time. Initial iteration time. Total link volume used in ADJUST; by default, it is the sum of all VOL[] sets. Number of zones.
C* DISTANCE*
I
ITERATION
J
LAMBDA LASTITERATION LINKCLASS* LINKNO LOWCNT NODES NUMLINKS PROJECTLINK
SPEED*
T0* T1* V* ZONES
Built-in arrays
There are arrays that can be referenced with [] to indicate a specific value from the array. Most times, the link-oriented arrays need not be referenced with an index; the default [linkno] is supplied by the program. The names with a * can be stored into, the others are reserved.
Array A B COST DIST* LI.name LW.name* MW[]* TIME* VOL[]* Description A-nodes for each link. B-nodes for each link. Link cost values. Link distances. Link values from the network. User generated values for links (currently accepts numeric values only). A work matrix; see COMP on page 177 for more details. Link times. Link volumes.
Built-in functions
These built-in functions are described in COMP on page 177.
Function ROWSUM(mw) ROWCNT(mw) ROWMIN(mw) ROWMAX(mw) ROWAVE(mw) ROWFIX(mw) ROWFAC(mw,fac) ROWADD(d,s1,,sn) ROWMPY(d,s) Description Row total. Number of cells whose values != 0. Minimum value in the row. Maximum value in the row. Average cell value where value!=0. Convert mw to integer values (start at column intrazonal + 1). Factors the row by fac. Add matrixes mw[1] + + mw[sn] into mw[d]. Multiply mw[d] by mw[s].
Function ROWDIV(d,s) LOWEST(mw,#) LOWCNT SPEEDFOR(lanes,class) CAPACITYFOR(lanes,class) PATHTRACE(value) LINKNUM(a,b)
Description Divide mw[d] by mw[s]. Sum of lowest valued cells in a matrix row. Actual number of cells found by LOWEST function. Speed from spdtab. Capacity from captab. Sum of link values (Time, Cost, LI. or LW.) on path for I to J. Link number for link a-b.
Built-in variables available in the CONVERGE phase

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

Variable RAADCUTOFF* PDIFFCUTOFF* RMSECUTOFF* Description Initialized to the value PARAMETERS RAAD; may be reset anytime Initialized to the value PARAMETERS PDIFF; may be reset anytime Initialized to the value PARAMETERS RMSE; may be reset anytime.
Built-in functions available in the CONVERGE phase

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

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

Function RAADCHANGEMAX RAADCHANGEAVE PDIFFMIN PDIFFMAX PDIFFAVE PDIFFCHANGEMIN PDIFFCHANGEMAX PDIFFCHANGEAVE RMSEMIN RMSEMAX RMSEAVE RMSECHANGEMIN RMSECHANGEMAX RMSECHANGEAVE Description Maximum change in RAAD between the last n iterations, where n = the number of iterations to process. Average change in RAAD between the last n iterations, where n = the number of iterations to process. Minimum PDIFF between the last n iterations, where n = the number of iterations to process. Maximum PDIFF between the last n iterations, where n = the number of iterations to process. Average PDIFF between the last n iterations, where n = the number of iterations to process. Minimum change in PDIFF between the last n iterations, where n = the number of iterations to process. Maximum change in PDIFF between the last n iterations, where n = the number of iterations to process. Average change in PDIFF between the last n iterations, where n = the number of iterations to process. Minimum RMSE between the last n iterations, where n = the number of iterations to process. Maximum RMSE between the last n iterations, where n = the number of iterations to process. Average RMSE between the last n iterations, where n = the number of iterations to process. Minimum change in RMSE between the last n iterations, where n = the number of iterations to process. Maximum change in RMSE between the last n iterations, where n = the number of iterations to process. Average change in RMSE between the last n iterations, where n = the number of iterations to process.
In many applications, only a few ILOOP statements will be required. For example, an assignment would require only the following statements:
Example of most simple assignment
Assume NETI contains values to obtain T0.

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

Using the Highway program is simple if all the input data is in the proper format and the normal procedure is adhered to, but it can be somewhat more difficult if deviations from the normal procedure is desired. In this section we would like to walk the novice users through the steps of setting up the scripts for typical situations. To perform a typical traffic assignment, all that is needed is an input network and a trip matrix. If the network is in the proper format (contains the required variables) only a few statements are required. While the program bases its computations upon generalized costs, most users tend to think of assignments in terms of time. To accommodate this, the program assumes that cost is equal to time, unless the user specifies otherwise. In our examples
we will assume that time is the basis for the process, we wish to do a peak-hour assignment, and the network has the following variables.
Variable T0 DISTANCE C Description Link free flow time Optional, but useful for certain statistics Link capacity in veh/hr
Base case is therefore:

RUN PGM=HIGHWAY ; simple case NETI = mybase.net MATI = mytrips.mat ; peak O-D trips NETO = loaded.net PHASE = ILOOP PATH=TIME, VOL[1]=mi.1.1 ENDRUN
This script will assign the trips from MATI[1] to the paths based upon TIME. It will adjust link times between iterations based upon the congestion levels. By default, up to 10 iterations of assignment and capacity restraint will be run; it will stop sooner if equilibrium convergence is reached before 10 iterations. In the following examples we will work from this same template and to keep reading to a minimum, we will not include the RUN, NETI, MATI, NETO, and ENDRUN statements. Thus, our illustration script would look like this:
PHASE = ILOOP PATH=TIME, VOL[1]=mi.1.1
Examples show: Daily assignment Add select link loading Add truck assignment on same paths Add truck assignment on separate paths Use preloaded truck volumes
Separate trips on separate paths Assignment of trips to HOV facilities
Daily assignment
Now lets add a few complications: The trip matrix contains daily trips, and we wish to do a daily assignment. The only thing that we need to do is to get the capacity into the correct units (well assume that daily capacity is 10 times the hourly capacity). We can do this in one of several ways, but lets just do the simplest, by adding a capacity factor.
PARAMETERS CAPFAC=10; factor NETI capacity by 10 to get daily capacity PHASE = ILOOP PATH=TIME, VOL[1]=mi.1.1
Add select link loading

Back to base case, but assume that you wish to do an assignment and get the volume on each link that is associated with only the trips that use a certain link. We do this by the typical process, but add an additional select link assignment to the typical assignment. Because this adds another volume set to the process the program will automatically want to sum the two volume sets together to perform capacity restraint. We have to tell the program to not add the selected link volumes. The volume used in each links capacity restraint is determined by the program by performing the V function which by default is: V=VOL [1]+ VOL[n], where n is the highest volume set in the setup. So, we merely replace the function in the following manner:
FUNCTION V=VOL[1] PHASE = ILOOP PATH=TIME, VOL[1]=mi.1.1, MW[1]=mi.1.1, SELECTLINK=(L=2001-2002), VOL[2]=mw[1]
In this case, work matrix 1 (MW[1]) is computed to be only the trips from MATI whose paths use the selected link. That matrix is then assigned to volume set 2 (VOL[2]). Because we supplied the V function, capacity restraint will only involve VOL[1].
Add truck assignment on same paths

Base case plus assigning the trucks from the second matrix on MATI. Trucks use same paths as cars and the combined volumes are used in the capacity restraint.
PHASE = ILOOP PATH=TIME, VOL[1]=mi.1.1, VOL[2]=mi.1.2
Add truck assignment on separate paths

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

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

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

Base case plus LINKREAD to flag HOV links. We will use 2+ and 3+ facilities, which are flagged in the network variable named HOV. The trip matrices have been previously split into matrices that could not use any HOV links, those that could use 2+ facilities, and those that could use 3+ facilities, stored in mi.1.1, mi.1.2, and mi.1.3, respectively.PHASE = LINKREAD
IF (LI.HOV==2) ADDTOGRP=2 IF (LI.HOV==3) ADDTOGRP=3 PHASE = ILOOP PATH=TIME, EXCLUDEGROUP=2-3, VOL[1]=mi.1.1 PATH=TIME, EXCLUDEGROUP=3, VOL[2]=mi.1.2 PATH=TIME, VOL[3]=mi.1.3
Path-based tolls
This section describes how to incorporate path-based tolls. This section discusses: Network development Path development
Network development
To use the path-based tolling TOLLMATI function, you must follow several rules when coding closed toll systems. Violating any of these rules causes Cube Voyager to terminate. Each toll facility must operate as a completely closed system where users can access and egress the facility only by crossing specified toll gates. Every on-gate must have a unique number (1-999). Every off-gate must have a unique number (1-999). Every toll-road link must be identified as such (that is, value is not 0). Each network link must have three attributes, which designate the links role in the toll system. You specify the attribute names in a FILEI TOLLMATI statement. A link can have a non-zero value for at most one of these attributes. The attributes store: On-gate number Off-gate number Toll-road indication A toll record must specify the toll for every possible on-off combination of toll gates. You specify toll records in a FILEI TOLLMATI file. Toll access rules: Toll on-ramps:
Inbound link must be a non-toll-road link or a toll offlink. Outbound link must be a toll-road link or a toll off-link. Inbound link must be a toll-road link or a toll on-link. Outbound link must be a non-toll- road link or a toll onlink. Inbound link must be a toll-road link or a toll on-ramp. Outbound link must be a toll-road link or a toll off-link.
Inbound link must be Non-toll-road off-ramp Toll-road onramp Toll-road onramp Outbound link must be Toll-road offramp Non-toll-road on-ramp Toll-road offramp Inbound link may not be Toll-road onramp Non-toll road Non-toll-road off-ramp Outbound link may not be Non-toll-road on-ramp Toll-road offramp Non-toll-road on-ramp
Toll off-ramps:
Toll-road links:
Toll type On-ramp Off-ramp Toll road
Path development
To include tolls in path development, specify the keyword TOLLMATI= on a PATHLOAD statement. The first value for TOLLMATI refers to the FILEI TOLLMATI[#]. An optional second value can specify which toll set from the TOLLMATI records to use. The specification for the TOLLMATI records is as follows:
FILEI TOLLMATI[#]=filename, ENTRYGATE= EXITGATE= TOLLS= NETIENTRY= NETIEXIT= NETITOLLROAD=
The file may be a DBF, an MDB-element, or a delimited text file. For DBF or MDB files, you must name ENTRYGATE and EXITGATE to indicate which fields on the record contain the on- and off-gate numbers, and TOLLS must name the fields containing the toll values. The first value for TOLLS is toll set 1, the second value is set 2, and so forth. For delimited text files, the values are field numbers
instead of names. There may be up to ten TOLLMATI record numbers, and up to ten toll sets. If any of these values is not specified, the default is the relative field on the record (ENTRYGATE is 1, EXITGATE is 2, and TOLL is 3).
NOTE: If a record exists for a gate-to-gate combination (for the
TOLLMATI#), but does not contain a specific toll (value missing or blank), Cube Voyager assumes a toll value of zero. The NETI... keywords indicate the NETI link attributes that contain the values for the ramp and road links. You can use these keywords on any FILEI TOLLMATI statement. If you use the keywords on more than one such statement, they must have the same values. If any are unnamed, the defaults names are: TOLLENTRY, TOLLEXIT, TOLLROAD. The program will fatally terminate if: A link has a nonzero value on more than one of the required toll attributes. More than one link has the same on-ramp value. More than one link has the same off-ramp value. A possible on-to-off route does not have a toll specified. Zero is an acceptable value. There is a violation of the above access rules.
At the beginning of each iteration, the program determines the onoff combinations that are possible for each PATHLOAD statement. It checks if there is a toll for each of those combinations, and if not, it fatally terminates. It saves those on-off combinations and uses them during the PATHLOAD statement; therefore, do not revise the PATH=array within the iteration. With most toll systems, altering the array would probably not cause a different routing between on-off ramps, but, the on-off travel costs could become incompatible with the array costs. In some systems, changes in the path array might cause a different on-off routing, but since the toll routings and costs are fixed for the iteration, the application does not consider
such changes. The PATHLOAD path-building process does not directly use the toll facility links; instead, the process uses the predetermined combinations. During path building, the new PATHTOLL keyword value can be used to skim the toll values for the paths (MW[1]=PATHTOLL). Any I-J path that traversed one or more combinations of entry and exit gates will have the accumulated toll along the path placed in the matrix. For an example of a script using TOLLMATI, see Highway example 8 on page 259.
Highway Program Phases
Phases
This section provides more details about the different phases in the Highway program: SETUP and LINKREAD phases ILOOP phase ADJUST phase CONVERGE phase
SETUP and LINKREAD phases

This section describes the SETUP and LINKREAD phases: SETUP phase LINKREAD phase
SETUP phase
The stack for this phase is processed after all control statements have been read and edited. The only operational statements allowed in this stack are COMP and SET. There is no specific header for SETUP; it is the phase that precedes the first actual PHASE= statement. It is used to initialize certain variables and/or arrays.
LINKREAD phase
This phase follows the SETUP phase. The primary purpose is to obtain the initial values that are required from the input network, and to compute link values that the user can reference in other phases. The values obtained directly from the network are referenced using the network name prefixed by LI. Any variables, other than those obtained directly from the network, that the user wishes to reference later in any phase must be named as LinkWork variables. LinkWork variables must be given names that begin with LW. The statement: LW.TOLLTIME = LI.TOLLTIME / 100 would generate a value that is available for every link at any stage in the
application. On the other hand, the statement: TOLLTIME = LI.TOLLTIME / 100 would generate a variable that has no meaning beyond the current link. The LinkWork variables are stored as LinkWork arrays (see Built-in arrays on page 136). An internal loop is processed based upon the Linkno variable which loops from the first link through the last link (Linkno=1, NumLinks). For each value of Linkno, the program obtains a link data record from the input network (NETI), and processes the LINKREAD phase stack, if present. After the LINKREAD stack is finished, it ensures that certain link variables (T0, T1, and C) are set and fills in the link TIME and COST values. There are different ways that these variables can be set. The logic that the program uses is described below. Note that while DISTANCE and SPEED are examined, they need not be specified by the user. Usually, T0 is computed by dividing DISTANCE by SPEED. Therefore, the program will try to obtain DISTANCE and SPEED values. If they are not set by the user stack statements, the program will try to set them, and then compute T0 from them. On the other hand, if the user has set T0 directly, the values of DISTANCE and SPEED are merely academic. The logic that is applied to get the required values (after the user LINKREAD stack is processed) is as follows: DISTANCE (possibly used to compute T0): If set by LINKREAD, use that value, Else if there is a LI.DISTANCE, DISTANCE = LI.DISTANCE, Else DISTANCE = 0. If DISTANCE < 0, set DISTANCE = 0. LINKCLASS (essential for selecting appropriate Functions): If set by LINKREAD, use that value, Else if there is a LI.LINKCLASS, LINKCLASS = LI.LINKCLASS, Else LINKCLASS = 1. If LINKCLASS < 1, set LINKCLASS = 1. SPEED (possibly used to compute T0): If set by LINKREAD, use that value,
Else if there is a LI.SPEED, SPEED = LI.SPEED, Else If there are LI.LANES and LI.SPDCLASS and their values are valid (1-9, and 1-99), SPEED = SPEEDFOR(LI.LANES,LI.SPDCLASS). Else SPEED = 0. C (capacity, used later in restraining process in the ADJUST phase): If set by LINKREAD, use that value. Else if there is a LI.CAPACITY, C = LI.CAPACITY* CAPFAC, Else If there are LI.LANES and LI.CAPCLASS and their values are valid (1-9, and 1-99), C = CAPACITYFOR(LI.LANES,LI.CAPCLASS) * CAPFAC. Else C = 0. If C < 0, set C = 0. Note: the program treats a link capacity of 0 (zero) as infinite capacity. T0 (free flow time): If set by LINKREAD, use that value. Else if there is a LI.T0, T0=LI.T0 Else if there is a LI.TIME, T0 = LI.TIME Else if there is a LI.TIME1, T0 = LI.TIME1 Else if SPEED > 0, T0 = DISTANCE*60/SPEED If T0 < 0, T0 = 0. T1 (initial iteration time): If set by LINKREAD, use that value. Else T1 = T0;
TIME (a LinkWork variable, without the required LW. prefix, of T1 values): TIME is set equal to T1 after the LINKREAD stack is processed; the user may not reference TIME in LINKREAD because its value is unpredictable at that time. COST (a LinkWork variable, without the required LW. Prefix, of cost values): COST is ALWAYS computed by the COST function for the LINKCLASS after the user LINKREAD statements are exhausted. The user may not reference COST in LINKREAD. DIST (a LinkWork variable, without the required LW. prefix, of DISTANCE values): DIST is set equal to DISTANCE after the LINKREAD stack is processed; the user may not reference DIST in LINKREAD. When the LINKREAD stack is processed for each link in the capacity restraint process, the TIME, COST and DIST values are not touched following the stack operations. Another important function of LINKREAD is to allow the user to specify GROUP codes for links. Group codes can be used in various applications. Links with certain GROUP code values can be disabled during path building to preclude those links from being included in the path. (See PATHLOAD on page 223 for more details.) For example, it is possible to build low occupancy vehicle paths by precluding the use of HOV links. There are additional types of applications that can take advantage or this capability. GROUP codes can be very useful in select link processing. Paths which use links with certain GROUP codes can be easily identified and used for extracting matrices. It is even possible to identify the paths that have a certain level, or combination of levels, of GROUP coded links. See SETGROUP on page 244 for more details about this capability. COMP statements can be used to alter, or set, link values in LINKREAD.
PRINT statements can be useful for listing information about individual links. It should be noted that listing TIME, COST and DIST will display meaningless values during LINKREAD.
NOTE: It is important to note that the entire LINKREAD stack is
processed for each link every time a network link data record is read. In order to ensure consistency, the LINKREAD stack is also processed for each link as it is read and processed in the ADJUST (capacity restraint) phase also. That is primarily why the user may not reference TIME, COST and DIST in LINKREAD; it could alter the internal arrays that are being used and dynamically altered by the capacity restraint process. If there are no special LINKREAD operations to be performed, there need not be any stack statements in this PHASE.
ILOOP phase
This phase performs a zonal loop (I = 1, Zones). Almost all control statements are valid within this stack. There MUST be a PHASE=ILOOP statement, and the stack MUST have at least one PATHLOAD statement. The ILOOP stack is executed one time for each value of I. Almost all the functions of the Matrix program can be performed within this stack. MW[#]= statements are performed for all Js (J=1,Zones), unless the statement occurs within a JLOOP block, or both indices (MW[][]) are specified. For assignment, the PATHLOAD statement is the most important. It specifies a set of values that are to be assigned to the links in a specified path set. The following examples illustrate the PATHLOAD statement: Volume sets Stratifying vehicle distance traveled by average trip speed Select link Selected zone loading
Subarea trip extraction
Volume sets
A volume set is an array in which assignments for each link are accumulated. There may be up to twenty volume sets; the highest set number is 20, but set numbering need not be monotonic. The volume sets are addressed as VOL[#], and each of these is cleared at the beginning of each iteration. Values are entered into the VOL sets by using PATHLOAD VOL[] = expressions. In example 1, VOL[1]=MI.1.6 instructs the program to route the values from the expression MI.1.6 along the paths from the origin zone (I) to each of the destination zones (J). A VOL[] = expression implies an internal loop of J=1,Zones. In the example, as J loops, the value (normally trips) for I to J from MI.1.6 will be routed along the path from I to J.
Example 1
PATHLOAD VOL[1]=MI.1.6, PATH=TIME
Example 1 establishes that the set of link volumes (VOL[1]) is to have values added to it by assigning the values from matrix 6 from the MATI[1] file to the links in the paths based upon the link values of TIME.
Example 2
PATHLOAD PATH=LI.DISTANCE, VOL[3]=I*10+J
Example 2 establishes that the set of link volumes (VOL[3]) is to be have values added to it by assigning the values computed from the I*10+J expression to the links in the paths based upon the link values for LI.DISTANCE. (A value will be assigned for each J in: J=1,zones.)
Example 3
PATHLOAD VOL[4]=MW[5]+MW[6]+MI.2.8, PATH=LW.TOLLTIME
Example 3 specifies that a PATH is to be built based on the link values from LW.TOLLTIME, and the values to be assigned to those paths are obtained by solving the expression: MW[5] + MW[6] + MI.2.8.
Stratifying vehicle distance traveled by average trip speed

During a multiple iteration assignment, the trips from any I to J may use various paths. The paths are based upon the times on each link in effect in that iteration. After all iterations, the final link volumes, along with the travel times associated with those volumes are used to obtain vehicle time. There are those who believe that emission estimation based upon individual link volumes, distances, and times is not as useful as vehicle distance based upon the average trip speed. To allow vehicle distance to be obtained based upon average trip speed, the REPORT VDTSPD must be requested. With this option, considerably more processing must be undertaken, and a considerable amount of disk space might be required. The program saves the paths for each I-J movement during normal assignment. Following the assignment, the paths are retrieved and the all the assigned trips are retraced along the paths they used in assignment. However, the final link times are used to obtain the individual trip time and distance. The average speed for the trip can then be calculated. The speed is used to stratify the vehicle distance of travel. The user can specify multiple stratification schemes; additional schemes do not require additional resources.
Select link
There are several ways in which select link processing can be undertaken, and they are all initiated via the PATHLOAD statement. A PATH keyword specifies the link values that are to be used to develop the paths. Any MW[]= expressions that are followed by SELECTLINK=, SELECTGROUP=, or SELECTLINKGROUP= will solve the MW= expression for only those destination zones (J) where any
of the SELECT expressions results in a true condition. If a subsequent VOL= is used, any of the select link matrices can be assigned at that point.
Example (simple code inefficient)
MW[1]=0 JLOOP ; this illustrates selective gathering IF ((I=... & J=...) || (I=... & J=...) ) MW[1] = MI.1.1 ENDJLOOP VOL[1]=MW[1],path=...
Since solving complicated selections can be somewhat time consuming, the IF process would probably be faster if the zonal ranges are not too complicated.
Example (most efficient)
IF (I=...) PATH=..., VOL[1]=MI.1.1, INCLUDEJ=...
Example (using SelectLink)

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

Many times it is desirable to load only the trips between selected zone pairs. There are several ways to do this. One way would be to establish a work matrix with the trips to be loaded. The unwanted I-J pairs are cleared, and then that matrix is referenced by the PATHLOAD VOL statement. Another alternative is to use IF statements to do I testing, and INCLUDE and /or EXCLUDE keywords to select the Js. And, another way is to use the SelectLink option, specifying: (a=range of Is && b=range of Js).
Subarea trip extraction

To obtain matrices of trips that have some portion of travel in a selected region (subarea network polygon) of the network, the following keywords must be used:
FILEI SUBAREANETI To define the region FILEO SUBAREAMATO To define where the selected trips will be saved PATHLOAD SUBAREAMAT[] To specify which values are to be written to SUBAREAMATO
After the PATH is built for current I zone, the values computed from the SUBAREAMAT expression for each J zone are traced along the path from I to J. If the path uses any links that are in the subarea network, the value for J is placed into the subarea matrix. In this process, there are several types of records that can be extracted:
Description X-X X-I I-X I-I path begins and ends outside subarea, crossing the cordon line only 2 times. path has origin outside the subarea and destination inside the subarea. path has origin inside the subarea and destination outside the subarea. both ends of the path are inside the subarea.
When a path enters the subarea by crossing a cordon link, the A node of that link becomes the origin zone of the extracted record, and the B node of the cordon link used to exit the subarea becomes the destination zone. If the path terminates at an internal zone, the internal zone becomes the destination zone. When a path exits the subarea, the internal zone where the path began, or the A node of the cordon link that was used to enter the subarea, becomes the origin zone of the extracted record, and the B node of the exit cordon link becomes the destination zone. If a path begins and ends inside the subarea, but never crosses the cordon line, a single I-I record is extracted. The A node of the origin zone becomes the origin, and the destination zone becomes the destination. The intrazonal value for an internal zone will be extracted even though there is no path.
Multiple records can be extracted for a path. (For example, a path begins outside, enters, exits, enters, and either exits again, or terminates an internal zone.) The final matrices are combined values from all iterations of assignment, but if requested during a non-assignment application, only 1 iteration is processed. The subarea network is obtained from the Viper software, using the Polygon Subarea network extraction process.
Example (subarea trip extraction)
PATHLOAD PATH=TIME, SUBAREAMAT[1]=MI.1.1, SUBAREAMAT[2]=1
ADJUST phase
This phase is automatic, and follows the ILOOP phase in each iteration. A major purpose is to compute the congested time (Tc) on each link and to revise the link TIME values for use in the next iteration. If some special processing on each link is to be performed following the normal adjustment process, the Phase=ADJUST control must be input and followed by a stack of control statements that are to be performed. A common application for user supplied ADJUST statements is to list the effect of the normal process on each link and to make adjustments to LW. values. If an LW.value is based upon any values that are revised by the ADJUST process (most likely Time and/or Cost), LW.value should be re-calculated by the user at this time. For example, assume that there is a set of LW.TOLLTIME values, and those values need to be updated to reflect the change that were made in TIME. It is the users responsibility to make the changes in LW.TOLLTIME; the program does not know the intention of the user, so it can not make any adjustments automatically. It is permissible to alter TIME values with ADJUST statements, but it is not advised. After the user ADJUST statements are completed, the program recalculates the COST values using the Cost Function. (See Functions and built-ins on page 134 for a description of the built in functions, variables and arrays the program uses.
The ADJUST phase runs an automatic LINKLOOP across all links on the input network. All control statements coded in this phase are executed once per link. If summary values are to be accumulated during the link loop, it is the users responsibility to properly initialize them at the beginning of the link loop. This can be done by testing for the value of Linkno: IF (Linkno=1)... (Hint: Iteration and LastIteration can also be tested by the user). Congestion is based upon the variable V, which is computed for each link. By default, V is the sum of all VOL[]s that appear on any PATHLOAD statements. This may not be exactly what is desired, so a FUNCTION V= statement can be used to override the default computation of V. The default Function for V should not be used if a standard assignment is being made along with a select link assignment; some volumes would be duplicated. In most cases, multiple iterations are performed, and the final volumes are obtained by combining the volumes from each iteration. The maximum number of iterations can be specified, but it is usually better to let the program determine when more iterations will not result in any assignment improvements. Various combination processes can be specified; the PARAMETERS COMBINE value is used to specify the method to be used: Equilibrium (the default) Average Weighted average Iterative Summation (often referred to as incremental)
Equilibrium assignment is performed within the ADJUST phase. If the term assignment is used to indicate the actual accumulation of trips on link volumes, the term equilibrium assignment is somewhat of a misnomer. Most users tend to think of equilibrium assignment as the process of determining a weight factor for an iteration, and then applying that factor to the current iteration volumes and a complementary factor to the previously weighted volumes to obtain new weighted volumes. If the network is well
behaved, and the appropriate processes are included, eventually a state of equilibrium is reached. That state is reached when further adjustments in the link costs used for routing, will not produce significant differences in the system as a whole. In theory, equilibrium is reached when there is no ability for individual I-J path costs to improve, without causing degradation in other parts of the network. If a system has a significant degree of congestion, it may be difficult (practically impossible) to reach a true state of equilibrium. The basic measure of equilibrium is total system user cost, and in most situations, cost involves some measure of time. Time is generally the measurable quantity that can be directly related to congestion. Thus, most equilibrium formulations are based upon time. To determine the weight to apply to each iterations volume in the volume combining process, a factor (generally referred to as Lambda) is estimated for the iteration. Lambda is a factor between 0 and 1. It is impossible to solve directly for Lambda, so it is estimated using a linear approximation method. The user can select one of two Lambda search processes using the PARAMETERS COMBINE LAMBDASEARCH = AREA/EQUATION. Note that both processes estimate Lambda so the results might be slightly different. In most cases, the results will be quite similar, but the EQUATION method can save considerable computation and I/O time. If the AREA search process is used, the program minimizes the area under all the V vs. Cost curves computed for incremental estimates of lambda for every link. This process provides a Lambda calculation that is up to 6 digits in precision. If a standard function for computing TC is used, the estimation process could be considerably more efficient.
If the EQUATION search process is used, the program solves the expression for only a limited number of Lambdas, using the following expression if the default BPR form is used for the TC functions or no TC functions are coded (default TC function is BPR form with default BPR constant and exponent): Y() = (VOLk Vk-1) * T0(1 + TCCOEFF * ((Vk-1 + * (VOLk - Vk-1))/C) ^ TCEXP) where:
VOLk Vk-1 T0 = the summation over the links in the input network = the AON volume assigned in iteration k to COSTk-1 paths based on Vk-1 = the equilibrium weighted volume from the prior iteration = the free flow time
TCCOEFF = value of the TC functions coefficient term defined on the PARAMETERS statement C TCEXP = the link capacity = value of the TC functions exponent term defined on the PARMETERS statement
If the user has specified his own alternate form for the TC functions using the new PARAMETERS TCCOEFF and TCEXP and requests the EQUATION search process then the program uses the following expression to solve for Lambda: Y() = (VOLk Vk-1) * TC(V,TCCOEFF,TCEXP) Where TC(V,TCCOEFF,TCEXP) is the TC functions evaluated for link volumes V, and the appropriate values of TCCOEFF and TCEXP, where V= Vk-1 + * (VOLk - Vk-1). The resulting curve is examined, and the Lambda which provides Y=0 is obtained by interpolation. This value is then used to weight the current volumes: Vk = * VOLk + (1- )*Vk-1.
There are several iteration volume combination processes available; the PARAMETERS COMBINE= specifies the one to use. EQUI is the default. The available processes are:
Process EQUI AVE WTD ITE SUM Description Equilibrium assignment. Iteration volumes are factored by the equilibrium weights computed for each iteration. Average assignment simply keeps a running average of the volumes on each link. Weighted Average assignment is the same as Average, but the user can specify a specific weight for each iteration. Iterative assignment keeps only last iteration volumes are output; prior iteration volumes are not considered. Sum assignment is one in which the final volumes are the result of adding the volumes from each iteration. This is traditionally known as incremental loading.
Convergence tests
If the optional CONVERGE phase has not been specified then default convergence testing is performed at the end of the ADJUST phase to determine if more iterations are necessary.
Convergence testing is not performed for Combine=Sum assignment. There are several tests that can be made to determine if more iterations are necessary. The items that are used in the tests are Keywords set with the PARAMETERS statement and include:
Keywords GAPk Description ABS(SUML(VEk*COSTEk) SUML(Vk-1*COSTEk-1))/ SUML(Vk-1*COSTEk-1) Where k is the current iteration and SUML denotes summation over the links and, if appropriate, the turning movements in the network, VEk is the equilibrium weighted volumes for iteration k and COSTEk is the cost based on the equilibrium volumes VEk. RGAPk (SUML(VEk-1*COSTEk-1) - SUML(VAk*COSTEk-1) )/ SUML(VEk-1*COSTEk-1) Where VAk is the link volume from an all or nothing assignment to the minimum cost paths based on COSTEk-1. AAD RAAD Pdiff RMSE MAXITERS Average absolute volume difference: based upon successive iterations Relative AAD: DiffV/V Percent of links whose change in V between iterations is less than a set value. Root mean squared error of the differences in V between iterations. Sets a fixed maximum number of iterations for convergence
The ADJUST phase process is as follows: Major Link loop: Linkno = 1, NumLinks (multiple passes if equilibrium is specified): Obtain link values (as in LINKREAD and LINKREAD stack, except TIME is not altered). If Iteration > 1, obtain prior combined iteration volumes (CVOL is prior V). Apply the appropriate TC and Cost Functions (based on LinkClass) to compute revised Time and Cost.
If this is an Equilibrium pass, compute link contribution (Y) to Lambda estimations. Else if Iteration > 1, combine V with prior combined Vs Process LinkAdjust stack (if present), and recompute Cost. End Major Link Loop. Determine if this is to be the last iteration: If Iteration = MaxIters: LastIteration = 1, go to write Neto Test for Convergence if CONVERGE phase not specified (true if any of following conditions met minimum values are those set with the PARAMETERS statement): GAP RGAP AAD RAAD PDIFF RMSE < MinGap < MinRGAP < MinAAD < MinRAAD > MaxPdiff < MinRMSE
NOTE: Under the default convergence criteria, convergence is
considered to be achieved if ANY of the above PARAMETERS minimum values are obtained. Note that all of these PARAMETERS have default values so they do have minimum targets even though the user has not explicitly coded them. For example if you have specified PARAMETERS GAP=0.001 in order to stop further iterations beyond this value of GAP but have set no other controls, the assignment may stop after 10 iterations because the default value of MAXITERS=10 is reached before reaching a GAP<0.001. Or, the assignment may stop in less then 10 iterations and before GAP<0.001 because one of the other PARAMETERS has reached its default minimum. In order to insure that a specific GAP value is achieved (if that is your goal) you must set all of the other convergence PARAMETERS to zero. For example:
PARAMETERS MAXITERS=99, GAP=0.001, RELATIVEGAP=0, AAD=0, RAAD=0, RMSE=0
Would continue performing iterations until GAP<=0.001 or 99 iterations were preformed. If you would like to specify alternate rules for when the program determines convergence is reached, this can now be achieved by using the CONVERGE phase. See CONVERGE phase for examples of specifying alternate convergence rules. If PHASE=CONVERGE is present, process the stack statements in the CONVERGE Phase until BALANCE=1 or MAXITERS is reached. If Convergence satisfied by BALANCE=1 (LastIteration set to Iteration, if true), or LastIteration: Write Neto.
CONVERGE phase
This phase, if specified, follows the ADJUST phase in each iteration. At the end of the ADJUST phase, the program checks if additional iterations are necessary. Convergence testing is not performed for Combine=Sum assignment or for Iteration=1. There are several tests that can be made to determine if more iterations are necessary. The default items that are used in the convergence tests are: GAPk ABS(SUML(VEk*COSTEk) SUML(Vk-1*COSTEk-1))/ SUML(Vk-1*COSTEk-1) Where k is the current iteration and SUML denotes summation over the links and, if appropriate, the turning movements in the network, VEk is the equilibrium weighted volumes for iteration k and COSTEk is the cost based on the equilibrium volumes VEk.
RGAPk
(SUML(VEk-1*COSTEk-1) - SUML(VAk*COSTEk-1) )/ SUML(VEk-1*COSTEk-1) Where VAk is the link volume from an all or nothing assignment to the minimum cost paths based on COSTEk-1.
AAD RAAD Pdiff RMSE
Average absolute volume difference: based upon successive iterations Relative AAD: DiffVE/VE Percent of links whose change in VE between iterations is less than a set value. Root mean squared error of the differences in VE between iterations.
MAXITERS Sets a fixed maximum number of iterations for convergence There are different philosophies as to what measures are best to determine if convergence has been reached, or if further assignment iterations will improve the assignment depending on the assignment method used. Some networks may never be able to reach a true balance because there is too much congestion, or there is insufficient capacity in certain parts of the network. Things can not be completely smooth because a slight adjustment in a few links may cause a large shift in a slug of traffic. Sometimes, the test statistics will begin to oscillate near the desired test limit, and may never reach a desired result. The CONVERGE phase process is provided to allow the user to program his/her own method of setting convergence. The user can write script to determine if the desired measure has been met. When the results are satisfactory, the script should set the variable BALANCE to 1. That will indicate to the program that further iterations are not to be undertaken.
Note that if PHASE=CONVERGE is detected within the script, the standard tests are not performed; termination will be determined by the value of BALANCE after the phase is completed. If BALANCE is never set to 1, the program will continue until MAXITERS is satisfied. BALANCE is automatically set to 0 when the phase begins. To help the user set BALANCE, various variables and functions are available.
Variables available for BALANCE
Variable GAP RGAP AAD RAAD PDIFF RMSE Description The GAP for the current iteration, Must be indexed GAP[] for previous iterations The RELATIVEGAP for the current iteration, Must be indexed for previous iterations The AAD for the current iteration, Must be indexed for previous iterations The RAAD for the current iteration, Must be indexed for previous iterations The PDIFF for the current iteration, Must be indexed for previous iterations The RMSE for the current iteration, Must be indexed for previous iterations A variable initialized to the value Parameters GAP, may be reset anytime A variable initialized to the value Parameters RELATIVEGAP, may be reset anytime A variable initialized to the value Parameters AAD, may be reset anytime A variable initialized to the value Parameters RAAD, may be reset anytime A variable initialized to the value Parameters PDIFF, may be reset anytime A variable initialized to the value Parameters RMSE, may be reset anytime
GAPCUTOFF RGAPCUTOFF AADCUTOFF RAADCUTOFF PDIFFCUTOFF RMSECUTOFF
Functions available for BALANCE

Function GAPCHANGE Description Function that results in change in GAP between the specified iteration (the required argument) and the previous iteration. Function that results in change in RELATIVEGAP between the specified iteration (the required argument) and the previous iteration. Function that results in change in AAD between the specified iteration (the required argument) and the previous iteration. Function that results in change in RAAD between the specified iteration (the required argument) and the previous iteration. Function that results in change in PDIFF between the specified iteration (the required argument) and the previous iteration. Function that results in change in RMSE between the specified iteration (the required argument) and the previous iteration. Function that results in the minimum GAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum GAP between the last n iterations, where n = the number of iterations to process. Function that results in the average GAP between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in GAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in GAP between the last n iterations, where n = the number of iterations to process. Function that results in the average change in GAP between the last n iterations, where n = the number of iterations to process.
RGAPCHANGE
AADCHANGE
RAADCHANGE
PDIFFCHANGE
RMSECHANGE
GAPMIN
GAPMAX
GAPAVE
GAPCHANGEMIN
GAPCHANGEMAX
GAPCHANGEAVE
Functions available for BALANCE (continued)

Function RGAPMIN Description Function that results in the minimum RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the average RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the average change in RELATIVEGAP between the last n iterations, where n = the number of iterations to process. Function that results in the minimum AAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum AAD between the last n iterations, where n = the number of iterations to process. Function that results in the average AAD between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in AAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in AAD between the last n iterations, where n = the number of iterations to process. Function that results in the average change in AAD between the last n iterations, where n = the number of iterations to process.
RGAPMAX
RGAPAVE
RGAPCHANGEMIN
RGAPCHANGEMAX
RGAPCHANGEAVE
AADMIN
AADMAX
AADAVE
AADCHANGEMIN
AADCHANGEMAX
AADCHANGEAVE

Function RAADMIN Description Function that results in the minimum RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the average RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the average change in RAAD between the last n iterations, where n = the number of iterations to process. Function that results in the minimum PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the maximum PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the average PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in PDIFF between the last n iterations, where n = the number of iterations to process. Function that results in the average change in PDIFF between the last n iterations, where n = the number of iterations to process.
RAADMAX
RAADAVE
RAADCHANGEMIN
RAADCHANGEMAX
RAADCHANGEAVE
PDIFFMIN
PDIFFMAX
PDIFFAVE
PDIFFCHANGEMIN
PDIFFCHANGEMAX
PDIFFCHANGEAVE

Function RMSEMIN Description Function that results in the minimum RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the maximum RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the average RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the minimum change in RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the maximum change in RMSE between the last n iterations, where n = the number of iterations to process. Function that results in the average change in RMSE between the last n iterations, where n = the number of iterations to process.
RMSEMAX
RMSEAVE
RMSECHANGEMIN
RMSECHANGEMAX
RMSECHANGEAVE
Example
PHASE=CONVERGE IF (ITERATION < 6) BREAK; Do not even test for Iterations 2-5 IF (GAP < GAPCUTOFF) BALANCE = 1 BREAK ENDIF IF (GAPCHANGEAVE(3) < 0.006 && GAPCHANGEMAX(3) < 0.009 && ABS(GAPCHANGEMIN) < 0.009) BALANCE = 1 ENDPHASE
Example
; This example implements the opposite of the default stopping criteria which is to stop if ANY of the convergence measures go below the values specified on the PARAMETERS statement. In this example the assignment would stop only when ALL criteria fall below their specified values. PHASE=CONVERGE IF (GAP<GAPCUTOFF & RGAP<RGAPCUTOFF & AAD<AADCUTOFF &
RAAD<RAADCUTOFF & RMSE<RMSECUTOFF & PDIFF<PDIFFCUTOFF) BALANCE = 1 ENDIF ENDPHASE
Highway Program Control statements
Control statements
The following control statements are available in the Highway program.
Control statement ABORT ARRAY BREAK COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FUNCTION GOTO IF ... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LINKLOOP ... ENDLINKLOOP LOOKUP LOOP ... ENDLOOP PARAMETERS PATHLOAD PRINT PRINTROW PROCESS ... ENDPROCESS REPORT SET SETGROUP Description Quit current program Set user arrays Break out of current process Compute variables from expressions Go to end of current loop Terminate current phase Input files Output files Set path for temporary files Fill work matrices Define Volume, TimeAdjustment, and Cost functions Jump immediately to :label statement Define IF ENDIF block Define a loop for destination zones (J) Control a link loop for processing link records in the ILOOP phase Define lookup tables (see Chapter 3, General Syntax) Define a user controlled loop Set static parameters Build path, load path, compute selected link matrices Print variable values Print a row of a matrix Set process (phase) blocks Set standard reports Set multiple variables/arrays to same value Set link group codes
Control statement SORT SPDCAP TURNS
Description Sort user arrays Set Speed and Capacity table values Designate intersections where turn volumes are to be accumulated
ABORT
Aborts the entire run. MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager. It normally is not used, but allows for termination due to some conditions that can be detected in the process. For example: if it is discovered that an LOS matrix is empty when it should have data, the run should be aborted.
ABORT keyword
Keyword Description |S| Optional message that can be printed when the program terminates.
MSG Example
IF (MW[1][I] != 0) ABORT ;Intrazonal present in MW[1]
ARRAY
Declares user single dimension arrays. VAR=size, VAR=size Use ARRAY to allocate user arrays that are to be used in the process. An array is different than a variable in that it represents vectored data. Values stored to arrays must be numeric. String values cannot currently be stored in an array. When an array is referenced, it should include an index [], and if the index exceeds the size, the program may fatally terminate. Arrays can be useful for different processes. ARRAY statements are not dynamic (stack oriented); they
are allocated prior to any stack operations. When an array variable appears in a SET statement, all the cells in the array are set to the same value.
ARRAY keyword
Keyword Description |I| Name of the variable that is to be allocated according to the specified size. VAR must be a unique name. The size following the keyword is the highest index possible for VAR. Size may be either a numeric constant, or a special name. Special names are: ZONES, NODES, LINKS (or NUMLINKS).
VAR
Example
ARRAY sum_toll=20 sum_toll[NI.CLASS] = sum_toll[NI.CLASS] + VOLTOT ARRAY VMT=LINKS
BREAK
Breaks out of a loop. Upon encountering BREAK, the script immediately passes control to the statement after the associated loop. If BREAK is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1). If BREAK is not within a LOOP or JLOOP block, the script terminates processing for the I zone but does not bypass output and zonal reporting statistics.
Example
LOOP L1=1,3 IF (condition) statements ELSE BREAK ENDIF
; jump to IF statement
ENDLOOP IF (condition) BREAK ; no more processing for this origin zone
COMP
Computes a variable, matrix, or matrix element from an expression.
VAR=expression MW[n]=expression, INCLUDE=list of J zones, EXCLUDE=list of J zones
Use the COMP statement to compute variable and work matrix values.
COMP keywords
Keyword MW Subkeyword |KN| Description Value for a working matrix. You can specify this keyword in two formats: MW[n] Defines the value for row n of a working matrix. Matrices can contain up to MAXMW rows, as indexed by n. The index n may be either a constant or a variable name. The program solves the expression for all values of J (1 through Zones), filtering values indicated by any INCLUDE or EXCLUDE lists on this statement. Within a JLOOP statement, the program only solves the expression one time only, with J being the value of the loops current J. MW[n][c] Defines the value for column c in row n. The second index, c, must be between one and Zones. The program solves the expression one time only, with J being the loops J if within a JLOOP, or 1, if not.
COMP keywords (continued)

Keyword Subkeyword EXCLUDE |IP| Description Optional. Values of J excluded when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the EXCLUDE list. If the current J is on the list, the program does not evaluate or store the expression for that J. Specified values can range from 1 to the highest zone number. Filter applies to all MW[n] values on the COMP statement. Not permitted if COMP statement within JLOOP ... ENDJLOOP block. Always processed after INCLUDE subkeyword. By default no zones are excluded. INCLUDE |IP| Optional. Values of J included when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the INCLUDE list. If the current J is not on the list, the program does not evaluate or store the expression for that J. Specified values can range from 1 to the highest zone number. Filter applies to all MW[n] values on the COMP statement. Not permitted if COMP statement within JLOOP ... ENDJLOOP block. By default all zones are included.

Keyword VAR Subkeyword |KN| Description Name of a variable where the result of expression is to be stored. The name may be as long as desired (within reason). The expression is solved one time for each encounter, with J being either one (not in JLOOP), or the value of the JLOOP J. If expression results in a character string, the variable must be a character string variable. All variables are assumed to be numeric variables, unless their first appearance as a result in a COMP statement is with an expression that results in a character string. Examples: abc = '123' def = 123 abc = def ; invalid: abc has been declared a string abc = abc + '456' ; valid abc = abc + def ; messy -- dont mix jkl = 1 jkl = xyz xyz = 'xyz' ; jkl is declared numeric ; invalid: xyz is declared a string (later) ; xyz is declared a string
If a COMP statement includes any INCLUDE or EXCLUDE filters, the filters apply to all MW[]= values, and special matrix functions on the statement, no matter where they appear on the statement. EXCLUDE is processed after INCLUDE. INCLUDE and EXCLUDE may not be specified within a JLOOP.
Special matrix variables MW[] MI.n.name MI.n.matnum
The expression is a standard Cube Voyager numeric expression, but there are some special variables that may be used within it:
Matrix variables
Variable MW[Rexpression] Description Value from any work matrix; the column index (not explicitly expressed) will be supplied as J. Rexpression may contain nested MW[]; be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression. Value from the MATI[n].name matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n], must be a constant. MI.n.name[Cexpression] is a variation; the column index is computed. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
MW[1]="MI.1HBW TRIPS"
MI.n.name
MI.n.matnum
Value from the MI[n].matnum matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n] and the matnum must be constants. MI.n.matnum[Cexpression] is a variation; the column index is computed. Value from the ZDATI[n].name matrix; the zone index (not explicitly expressed) will be supplied as I. ZI.n.name[Cexpression] is a variation; the zone index is computed.
ZI.n.name
Special matrix functions
ROWSUM ROWCNT ROWMIN ROWMAX ROWAVE ROWFIX ROWFAC LOWEST LOWCNT ROWADD ROWMPY ROWDIV In addition to the standard numeric expression functions (abs, exp, int, ln, log, max, min, round, sqrt see Chapter 3, General Syntax, for more details), some special purpose functions are available. The matrix-oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists), and should not be used within JLOOP blocks and MW[]= expressions. Normally, they should be used only as VAR = ROWFUNC(#).
Most of these functions could be duplicated with a combination of MW[]= statements. The function format has two advantages: coding is much easier, and processing is more efficient. Combining functions on a single statement is permissible; they will be processed in appropriate order. Example: DUMMY = ROWFAC(3,1.5) + ROWFIX(3) will factor matrix 3 and then convert it to integer. In the following matrix function descriptions, the first argument (mw) indicates the work matrix to process, and must be specified. If lo,hi is allowed, and lo is supplied, and hi is not, hi will be set to lo. Lo and hi are inclusive values. If an invalid argument is detected by a function, the function will return a zero, without any diagnostics.
Matrix functions
Function LOWCNT Description The actual number of cells that was used in the summary is stored in the variable LOWCNT. Warning: Dividing by LOWCNT if it is 0, will cause a program error message (too many will be fatal). Sum of lowest n cells. Sum of lowest n cells, including only cells with values greater than or equal to lo, and less than or equal to hi. Sum of lowest n cells, including only cells with values greater than or equal to lo, and less than or equal to hi, and exclude the values for J=z,z,... LOWEST is quite useful for computing an intrazonal value based upon the proximity to the nearest zones. The range of arguments is to provide for most types of situations. With lo and hi, it is possible to exclude possible dummy zones that may appear as zero in the row. With z, specific zones can be excluded; normally, the intrazonal cell (I) would be excluded. This exclusion is in addition to any that may be on an EXCLUDE list. NOTE: Zeros are treated as regular numbers in LOWEST function. Since all MWs are initialized to zeros, caution should be exercised when applying LOWEST function with no range specified. ROWADD(d,s1...sn) Add matrix mw[1] + mw[sn] into mw[d] Same as:
MW[d] = MW[s1] + MW[s2] + MW[sn]
LOWEST(mw,n) LOWEST(mw,n,lo,hi) LOWEST(mw,n,lo,hi,z,z,...)
Matrix functions (continued)

Function ROWAVE(mw) ROWAVE(mw,lo,hi) ROWCNT(mw) ROWCNT(mw,lo,hi) ROWDIV(d,s) Description Average cell value, including only cells with values not equal to 0. Average cell value, but include only cells with values greater than or equal to lo, and less than or equal to hi. Number of cells with values not equal to 0 Number of cells with values greater than or equal to lo, and less than or equal to hi; can include 0. Divide MW[d] by MW[s] making all divided-by-zero cells equal to 0. Same as:
JLOOP IF (MW[s] == 0) MW[d] = 0 ELSE MW[d] = MW[d] / MW[s] ENDIF ENDJLOOP
ROWFAC(mw,fac) ROWFIX(mw) ROWFIX(mw,n) ROWFIX(mw,n,rnd)
Factors the row by fac. Same as MW[mw] = MW[mw] * fac Convert mw to integer values (start at column intrazonal + 1, with rounding factor = 0). Convert mw to integer values (start at column n, with rounding factor = 0). Convert mw to integer values (start at column n, using specified rounding factor). ROWFIX converts the values in each cell of the matrix to integers (that is, drops all fractional portions of the number) in such a manner to ensure the integer total is consistent with the original total. It converts each cell to an integer value after adding the rounding factor and the accumulated fractional portions from the previously treated cells. With a rounding factor of 0 each cell is truncated and its fractional remainder is carried to the next cell. With a rounding factor of 0.5, each cell is rounded to the nearest integer and the difference (original rounded) is carried to the next cell.
Matrix functions (continued)

Function Description If the process always began at zone 1, the lowest numbered zones would never get their fair share of the fractions. To eliminate this bias, the default condition is to start at the cell after the intrazonal cell and wrap around until the intrazonal cell is the last cell processed. The optional second argument specifies which cell the process is to end with. ROWMAX(mw) ROWMIN(mw) ROWMPY(d,s) Maximum value in the row. Minimum value in the row. Multiply MW[d] by MW[s] Same as:
MW[d] = MW[d] * MW[s]
ROWSUM(mw) ROWSUM(mw,lo,hi)
Row total. Row total, but include only cells with values greater than or equal to lo, and less than or equal to hi.
Example 1
MW[mw][I] = LOWEST(mw,4,0.01,5,I)/max(1,LOWCNT)/2
Example 2
MW[2]=J MW[K]=MW[2] * MW[5]) / SQRT(A*MW[3][MW[22]]) A=1, B=2, MW[A]=A+B INCLUDE=1-5,8,47-93 MW[3]=5*A, MW[4]=MW[3]*2, MW[K][I%10+1]=ODD, INCLUDE=1-100,401-500, EXCLUDE=90,93,452 ; applies to the MW[]s= ABC=LOOKUP(DEF)*3 /* move input matrices to work areas */ MW[11]=MI.1.1, MW[12]=MI.1.2, MW[13]=MI.1.3 MW[21]=MI.2.1, MW[22]=MI.2.2, MW[23]=MI.1.3
CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements.
If CONTINUE is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise, processing for the I zone is terminated, but output statistics will not be bypassed.
Example
LOOP L1=1,3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ; no more processing for this origin zone LOOP L2=K1,K2,KINC LOOP L3=L2,L2+5 IF (condition) CONTINUE ; jump to ENDLOOP for L3 ENDLOOP ENDLOOP
EXIT
Terminates stack processing. When the program encounters an EXIT statement, the program goes to the end of I loop processing.
Example
FILEI
and for important limitations when using Application Manager. Input data files MATI NETI SUBAREANETI TURNPENI (MISSINGLINK LIST)
ZDATI (Z SELECT NAME (DEFAULT) AVE AVEX0 CNT FIRST LAST MAX MIN SUM) JUNCTIONI (PERIOD N SET) LOOKUPI TOLLMATI (ENTRYGATE EXITGATE TOLLS NETIENTRY NETIEXIT NETITOLLROAD TOLLFACTOR TOLLROUND) Matrix data is read dynamically (at the start of each I loop), and must be in origin zone (I) order, whereas zonal data is read prior to the initiation of the I loop, and need not be in any specified order. Data from MATI and ZDATI files are accessed via stack statements, and are identified as MI.n.name and ZI.n.name. The n designates subscript of the file, name designates the matrix name or number. Cube Voyager matrices can have names and/or numbers, other matrices have only numbers, and zonal data files have names only. Example: MI.1.3 indicates matrix number 3 on the MATI[1] file. ZI.6.POP indicates the POP variable from ZDATI[6] file. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
On the FILEI statement the subscript is either explicitly, or implicitly, specified. MATI=... defaults to MATI[1], and MATI[3]=name3,name4,name5 sets up MATI[3], MATI[4], and MATI[5]. Since it is required that ZDATI files have variables explicitly defined for them, the vector form of ZDATI (ZDATI=file1, file2...) will be treated as an error. When an input file is used in an expression, it may have an additional subscript appended to it to specify a zone number. For matrices, the subscript references the column within a row, and for zonal data, it references the nth item in the vector. Zonal data can be viewed as having zones rows with one column per zone, or as one row having zones columns (users choice, it doesnt matter). If there is no subscript specified, the current value of J is used. J will
always be in the range 1-zones. Example: MI.6.3[I] accesses the intrazonal cell. ZI.1.TRMTIME[I] and ZI.1.TRMTIME[J] reference the origin and destination terminal times, respectively.
TURNPENI designates a file that contains intersection movement
functions and penalties. This file may be read and kept in memory for use during any path development processes (specified with PATH on PATHLOAD statements). Even if the file is designated on a FILEI statement, the penalties will not automatically be applied during path development; the user must specify which penalties are to be applied on each PATH selection. The file has two sections: functions and movements. The function section is optional, but allows the user to specify that a penalty is to be computed from an expression. If a function contains a C variable (movement capacity), the penalty will be revised between iterations in the ADJUST phase. Each record in the movement section designates a specific movement (a-b-c), a set identifier for the movement, and the penalty to be assessed. For example,
a b c -------11 23 15 1 12 13 15 58 36 set # -----1 3 8 turnpen ---------1 2 FUNC1(500)
(Prohibitor) (Constant) (Function)
The penalty may be a prohibition, a fixed unit penalty, or a reference to a function in the function section. A prohibition is designated as the constant -1. It is the users responsibility to make sure that the penalty values are in the proper scale and units as the paths to which they are being applied. Turn functions are designated as numeric expressions that may contain constants and the variables: T, C, PrevPen. T is the turn volume at the intersection (it may alternatively be named TURN); C is the capacity of the movement, and PrevPen is the penalty that was used in the previous iteration. T is vectored (that is, it may contain an index []). T is the total volume for the movement; it is 0 at the first iteration, but is the result of the T=expression on the
TURNS statement after the first iteration. If there is no TURNS
statement, T will automatically be the sum of all loadings. T[1] would indicate the turning volume associated with any PATHLOAD VOL[1] statements. T[0] and T are the same variable. If a T is specified with an index for which there is no PATHLOAD VOL[index], the value of T[] in the expressions will be 0. Care must be taken if a fixed penalty is to be established for the first iteration, and then dynamic values are to be used after the first iteration. This is usually done by using the MAX function in the expression. For example: Func1=MAX(2.00,T/C*5.00). In this example, since T would be 0 on the first iteration, the initial penalty would be 2, and it would vary after the first iteration. If the 2 unit penalty was to remain in effect for all iterations, and be increased according to the T/C ratio, the expression would be: Func1=2+ T/C *5. C is obtained from the record in the movement section as an argument of the function. To apply the above Func1 (2+T/C*5), with C=500, the movement record would be coded as: 100 200 201 0 Func1(500). This designates that the movement 100-200-201 is to be penalized 2 units on the first iteration and then the penalty will be increased according to a T/C ratio (with C being 500) after the first iteration. If there were no C affixed to the Func1 on the movement record, the C would be considered as 0 in the computations. (Warning: Be careful not to create divided-by-zero errors when applying functions with C=0.) TURNPENI function records are structured as: FuncName=expression. The name is what the user desires, and the expression is any valid numeric expression that may contain numbers, standard functions, T, C, PrevPen. TURNPENI movement records are structured as: A B C Set Penalty (one set per record). The records are white space delimited (space, comma). A is the entry node to the intersection, B is the intersection node, and C is the exit node. Set is a number in the range of 0-8. If the set number is 0, it is applied any time that penalties are in effect, no matter what the designated sets are. There may be up to 9 records (sets 0-8) for the same movement. During path building, when the movement is detected and PENI= is
specified in the PATHLOAD statement, the penalty process will automatically apply set 0, if there is a set 0 for the movement. If there is no set 0, the penalty is assumed to be 0. Then it will check all the other possible sets for the movements; it there are additional sets, the penalty for the highest set number that matches the highest PENI designation for the PATH process will be used. NOTE that any movements that have functions specified will cause the B node to be included as a node for which TURNS are to be kept, and will be reported on the TURNVOLO file. JUNCTIONI designates a file containing descriptions of junction models. The format of the file is discussed in Chapter 7, Intersection Modeling. N specifies a list of nodes where the intersection modeling is to be invoked during the ADJUST phase. However, invoking intersection modeling for a node where there is no model description has no effect. PERIOD is the model period in minutes. It is used to convert the assigned volumes into units of per hour, and it is one of parameters of the queuing delay equation. Executing a junction model produces turning delays that may be applied during the next iteration of capacity restraint. This form of output is similar to a set of turn penalties, and the turn penalty set numbering system applies. The SET keyword designate the turn penalty set to contain the model results. Turn penalty records may be applied with higher or lower priority (that is, set number) than the calculated delays.
FILEI keywords
Keyword JUNCTIONI JUNCTIONI N Subkeyword |KF| |IP| Description Specifies the input junction file. Specifies the nodes where intersection modeling is to be invoked. A junction model that is not invoked has no effect. Invoking intersection modeling where there is no junction described has no effect. Only those nodes that both have a model description and are listed in this list are actually modeled. Duration of the model period in minutes. The input demand matrix should be in units of vehicles (or PCU) per model period.
JUNCTIONI
PERIOD
|R|
FILEI keywords (continued)

Keyword JUNCTIONI LOOKUPI Subkeyword SET |I| |FKV999| Description Specifies which turn penalty set will contain the delays calculated by the junction models Name of file containing records for a lookup function implemented with the LOOKUP control statement. Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI. MATI NETI |KFV20| |KF| Specifies the input matrix files. The files must be Cube Voyager, TP+, MINUTP, or Tranplan binary matrices. Specifies the input highway network file. It MUST be a Cube Voyager or TP+ binary network, or a Cube geodatabase network stored in an MDB file. If specifying a Cube geodatabase network stored in an MDB file, the NETI keyword designates the filename followed by a backslash and the name of the Cube geodatabase network. The link variables from the network are referred to as LI.name. Specifies a file that contains subarea network information. In most cases the network will be one created by the Polygon SubArea Network Extraction process in Cube. If Cube is used to create the subarea network, the subarea will be set up properly, with the proper node renumbering and cordon link specification. This keyword is used in conjunction with the FILEO SUBAREAMATO = and PATHLOAD SUBAREAMAT[] = expressions. See ILOOP phase on page 154 for details about subarea processing. The node records of the network contain both the subarea node number (N) and the number (OLD_NODE) that N was in the network from it was extracted, The records also contain the variable SUB_TYPE that indicates the type of node with relationship to the original network. The SUB_TYPE values are: 0=insignificant 1=internal (subarea) zone 2=external gateway to the subarea network 3=internal exit from subarea
SUBAREANETI
|KF|
If these values are altered from those that Viper or Cube Base wrote, the results will be unpredictable.

Keyword TOLLMATI Subkeyword |KF10| Description Specifies the input toll matrix files. The specified files are toll-point to toll-point records and may be input as DBF, MDB table or delimited text records. See Path-based tolls on page 146. TOLLMATI ENTRYGATE |S| Field name or field number on the input TOLLMATI file that holds the entry toll gate numbers. If the input file is a DBF or MDB table, the ENTRYGATE value must be a field name from the input table. If the input file is a delimited ASCII file then the ENTRYGATE value is a field number on the input file. If ENTRYGATE is not specified, the first field on the input file will be used. Valid value range for entry toll gate numbers is 1-999. Field name or field number on the input TOLLMATI file that holds the exit toll gate numbers. If the input file is a DBF or MDB table, the EXITGATE value must be a field name from the input table. If the input file is a delimited ASCII file then the EXITGATE value is a field number on the input file. If EXITGATE is not specified, the second field on the input file will be used. Valid value range for exit toll gate numbers is 1-999. NETI link attribute that contains the entry gate numbers. The numbers in this link attribute correspond to the numbers in the ENTRYGATE field of the TOLLMATI file. If NETIENTRY is not specified the name will default to TOLLENTRY and it is assumed this link attribute name is available on the input NETI network. NETI link attribute that contains the exit gate numbers. The numbers in this link attribute correspond to the numbers in the EXITGATE field of the TOLLMATI file. If NETIEXIT is not specified the name will default to TOLLEXIT and it is assumed this link attribute name is available on the input NETI network.
TOLLMATI
EXITGATE
|S|
TOLLMATI
NETIENTRY
|S|
TOLLMATI
NETIEXIT
|S|

Keyword TOLLMATI Subkeyword NETITOLLROAD |S| Description NETI link attribute that contains the toll road indicator. All links with a non-zero value for this attribute are considered part of one or more closed toll systems in the network. The numbers in this link attribute can be used to correspond to one or more unique toll systems in the network. If NETITOLLROAD is not specified the name will default to TOLLROAD and it is assumed this link attribute name is available on the input NETI network. Up to 10 toll factors may be specified, one for each toll set. If specified the factor is applied to all toll values in the TOLLMATI file for the set. The TOLLFACTOR provides a method for quickly factoring tolls for sensitivity analysis. Allows for rounding of tolls or factored tolls to the nearest units specified. For example if a toll, coded in the TOLLMATI file for a particular entry to exit movement is US$1.50, and a TOLLFACTOR of 1.2 has been specified to test a 20% toll increase, the factored toll value would be US$1.80. By specifying TOLLROUND=0.25, the applied toll value for this movement would then be US$1.75 (that is,. rounded to the nearest US quarter dollar). Field name(s) or field number(s) on the input TOLLMATI file that holds the toll values. Up to 10 toll value sets may be coded. If the input file is a DBF or MDB table, the TOLLS value(s) must be a field name from the input table. If the input file is a delimited ASCII file then the TOLLS value(s) is a field number on the input file. If TOLLS is not specified, the third and subsequent fields on the input file will be used for up to 10 toll sets. Tolls can be coded as true toll values or in any units the user desires. Specifies the input file that contains the turn penalty functions and movement records. Switch to designate if the penalty values are to be listed to the print file.
TOLLMATI
TOLLFACTOR
|R10|
TOLLMATI
TOLLROUND
|R|
TOLLMATI
TOLLS
|S10|
TURNPENI TURNPENI LIST
|KF| |?|

Keyword TURNPENI Subkeyword MISSINGLINK |I| Description Designates the level of severity for any turning movements where links appear in the TURNPENI file, but the A-B and the B-C links are not both in the NETI network. Possible values: 0 Ignore completely (default value) 1 Write warning 2 Generate fatal error

Keyword ZDATI Subkeyword |KFV10| Description Specifies the input files containing zonal data. There can be up to 10 zonal data files. Zonal data is data which is specific for each zone. Every zonal record must include a field that identifies the zone to which the record data applies. Aside from the zone number, any fields from the record can be extracted and used by the program. The file format can be any of: ASCII, DBF, MDB, or a Cube Voyager or TP+ binary network. The program will try to detect what type of file it is. If it can not identify the file as a DBF, MDB, or a Cube Voyager or TP+ network, it will assume ASCII. When the program detects a Cube Voyager or TP+ network file, it opens the node database portion of the file as zonal data. If the file is of ASCII format, the fields to be extracted must be named and identified on the ZDATI statement by either relative field number, or by exact column positions on the records. The field that contains zone number must be specified using 'Z=' keyword. If the file is a database or a Cube Voyager or TP+ network, it is not necessary to name the fields to be extracted. All fields will be extracted and can be referenced, in the script, by existing field names from the input file. The specification of zone number field is optional for those two file formats. If 'Z=' is present, the specified field will be used to extract zone number. Otherwise, the program will try to determine the zone number field based on file type. For DBF and MDB files, the program will go through all field names to find a match with one of the following possible zone field names, in the given order: {Z, I, J, ZONE, ZONA, TAZ}. The first matched name will be used to extract zone number. (Note: For files with more than one possible zone field from the list above, it is recommended to specify zone number field explicitly to ensure the correct field is used.) For Cube Voyager or TP+ network files, node numbers (N) will be used as zone numbers by default. ZDATI ZDATI AVE1 AVEX01 |SV| |SV| Average of all records. Average of all records, where the value from the file records is not 0.

Keyword ZDATI ZDATI Subkeyword CNT1 DEFAULT |SV| |R| Description Count of the records that contain the variable. Value with which to initialize the array for the named variable. Then, if there are no records for a zone, or the field is blank on a record, this value will be used. Directly from the record from the FILEI with the lowest index[]. Directly from the record from the FILEI with the highest index []. Maximum value of all the records. Minimum value from all the records. Identifies a data variable that is to be extracted from each record. Only the variables named will be extracted. If the file is a dbf, the value for each name is the name from the dbf dictionary. In most dbf cases, name=name would be the standard, but it is not necessary to keep the same names. For text files, the value assigned to name is either a field number (delimited format), or the columns (fixed format) where the variable is located on the record. All names must be specified with the same format; the first name value (including Z) establishes the format. If the first value is a number, fixed format is assumed; otherwise, delimited format is assumed. If delimited format is specified, each name value MUST end in a number. It doesnt matter what string precedes the number (the value need not be prefixed with a string). Example: Z=#1,POP=#2, AREA=3, SALES=xxx4. These are all be valid, because Z specified triggered delimited format. Z=1-5,POP=#2 would be invalid because Z specifies fixed format.
ZDATI ZDATI ZDATI ZDATI ZDATI
FIRST1 LAST1 MAX1 MIN1 NAME
|SV| |SV| |SV| |SV| |S|

Keyword ZDATI Subkeyword SELECT |S3| Description Used to cause selective reading of zonal data records from ASCII files. The program will compare a field from each record with the string specified in SELECT[1], and if the comparison fails, the record is bypassed. This selection is not used if SELECT is not specified. The second SELECT value specifies the field to be compared with. If the value is a number, it designates the beginning column of the comparison field on the input record, and an optional third value can be specified to designate the ending column. The second and third values must both be numeric and should be separated by a dash. If the second field is not numeric, but ends with a number (Example: #1), it is assumed that the value indicates a relative field number on the data record; that field is the comparison string. The third value is ignored if the second value is a free field definition. Sum of all the records. Identifies where the zone number identifier is found on each data record; Z MUST be specified, even if the file is a dbf. Z is a special case for name= (below).
ZDATI ZDATI
SUM1 Z
|SV| |S|
1. Indicates a process to use in obtaining the value for the variables that are listed following the keyword. The values for the variables will be obtained only from file records that contain the variable. A variable may appear in only one keyword list; any variables that are not in any list will be set to LAST.
Caveat: The program establishes a buffer to read file records into. It has to know how long a buffer is required. With DBFs and fixed format records, the required length is known, but with delimited format, the required length can not be estimated exactly. For delimited files, the record length is estimated by multiplying the highest field number by 10. If the estimated length is inadequate, a dummy variable with a high field number can be specified to generate a larger record length.
Example
NETI=network.net ; TPP binary network file MATI=test11.dat, test12.dat ; MINUTP binary matrix files
MATI[4]=tppltrips.mat ; TPP or MINUTP matrix file TURNPENI=time.pen, MISSINGLINK=1 ZDATI[1]=housing.txt, Z=#1,DU1=#2,DUPLEX=3,MULTI_FAMILY=4, CONDO=5,RETIREMENT=6 ZDAT[4]=pop.txt,Z=1-5,poptotal=6-15,popmale=16-25,popfemale=26-35, popyouth=36-45,pop19-65=46-55,popsr=56-65, poptotal=sum, popmale=cnt
FILEO
Specifies files that the Highway program outputs. ESTMDATO NAME ESTMICPO (CONFVAR COUNTVAR DEFAULTCONF SCREENLINE VAR) JUNCTIONO MATO (FORMAT MO NAME DEC COMBINE) NETO (INCLUDE EXCLUDE APPEND DEC) PATHO (COSTDEC ITERS) PRINTO (APPEND) SUBAREAMATO (FORMAT DEC NAME) TURNPENO TURNVOLO (FORMAT (DELIMITER) DEC INCLUDE0 VARS NAMES) Use FILEO to specify the number and types of files that are to be written by the program. Requested matrices are written for every origin zone for every iteration, but are combined into a single combined matrix at the end of the application. A single network with appended volumes and associated variables is written at the end of the application. A turning volume file must be requested if a TURNS statement is used. There MUST be a NETO specified if assignment is to be made; there would be no use in running the program if there was no way to obtain the results. By default the NETO file will contain all the input variables from NETI plus the variables V, VT, VC, TIME, CSPD
(congested speed), VDT (vehicle distance traveled), VHT (vehicle hours traveled) and a Vn, and VnT for every VOL[n] specified on any PATHLOAD statements. VT and VnT are the non-directional (twoway) counterparts of V and Vn. (Non-directional volumes can be turned off using NETO EXCLUDE=T_.) These appended variables will have an assignment number appended to their names. If there were no prior assignment result variables appended to the link records, the assignment number will be 1. Thus, the first assignment variables will be named V_1, VT_1, VC_1, TIME_1, V1_1, V1T_1 etc. If the NETI file contains any variable whose name ends in _#, the NETO appended variables will have an appended number that is one greater than the highest _# from NETI. If the NETO file is being written to a Cube geodatabase network in an MDB file, the source geometry for links in the output network will come from the geometry of the input network. If the input network is a binary network, then the output NETO file will have no associated geometry and will be displayed as straight-line links when opened in the Cube GIS window.
FILEO keywords
Keyword ESTMDATO ESTMDATO NAME Subkeyword |F| |SV| Description Specifies the file name for the output screenline data file (*.DAT) that is required by Cube Analyst. Specifies the names for the screenlines in the ESTMDATO file. There need not be a name for each screenline, but it is suggested that they be included to help in documentation of the file. A default name of SL A-B will be supplied by Cube Voyager if no NAME is provided for a screenline. Specifies the file name for the output intercept file (*.ICP) that is required by Cube Analyst. Specifies the link array that contains the count confidence values. The value may be an lw.array or li.array. Alternate to using VAR. Specifies the link array that contains the counts. Links that have values in this array will be trapped for inclusion in the matrix estimation. The value may be an lw.array or an li.array. If using COUNTVAR, then do specify VAR.
ESTMICPO ESTMICPO ESTMICPO CONFVAR COUNTVAR
|F| |S20| |S20|
FILEO keywords (continued)

Keyword ESTMICPO ESTMICPO Subkeyword DEFAULTCONF SCREENLINE |I| |S20| Description Default confidence value applied if CONFVAR is not set or contains an illegal value (<=0). Valid range is 1 to 10,000. Specifies the link array that contains screenline numbers for the links. If there is no value in the array for a link that has a count, the program will assign a screenline number to it automatically. If SCREENLINE is not specified, the program will assign a unique screenline number to each link with a value in the VAR array. If a link has a value in the SCREENLINE array, but does not have a value in the VAR array, the link is ignored in the matrix estimation. The value may be an lw.array or an li.array. Replaced by COUNTVAR. Specifies the link array that contains the counts. Links that have values in this array will be trapped for inclusion in the matrix estimation. The value may be an lw.array or an li.array. If using VAR, do not use COUNTVAR. However, Citilabs recommends replacing all instances of VAR with COUNTVAR. JUNCTIONO MATO MATO COMBINE |F| |FV20| |?| Specifies the file name where the results of junction modeling may be stored for display. Specifies the filename for the MATO specified. Specifies that ALL the matrices on this file are to be combined in a manner consistent with the method of volume combination as specified with PARAMETERS_COMBINE. The most common application would be with selected link matrices.
ESTMICPO
VAR
|S20|

Keyword MATO Subkeyword DEC |SV*| Description Specifies the format for the MOs. There is a separate DEC for each MO. The value can be a number (0-9) or the character D or S. A number value indicates the output matrix cells are to be integerized with that many decimal places preserved. The letter D indicates that the cells are to be stored in double precision floating point format, while S indicates single precision floating point. All internal work matrices are maintained in double precision floating point format (eight bytes per cell), but can be written to MATO files in different formats in order to keep the storage requirements to a minimum. The reader is urged to read the description of FILEO MATO DEC in Chapter 9, Matrix Program, for a more detailed explanation of the possible binary options. If no DEC value is defined for a matrix, the default value will be integer with 2 implied decimal places. DEC is not applicable when FORMAT=MINUTP is specified. Specifies the format of the MATO: TPP Standard Cube Voyager or TP+ matrices (default) MINUTP Standard MINUTP matrices MATO MO |IVP| Specifies the MWs that are to be included in the MATO. MW may be indexed, but care should be taken to not leave holes in the final list. The highest implicit or explicit index establishes how many matrices will be included in the file. The same MW may be included more than one time. Example: MO=1-5,11-15, MO[20]=1, MO[6]=31 establishes that 20 matrices will be written. Nine of the matrices (11-19) will be dummy because no data was entered for them. The output matrices are numbered monotonically beginning with 1. Specifies the names for the TP+ and Cube Voyager matrices. Each MO does not require a name, but including names helps document the file. Valid matrix names only contain alphanumeric characters, spaces, and underscores (_). Cube Voyager programs reading the file can reference the matrices by name and/or number.
MATO
FORMAT
|S|
MATO
NAME
|SV|

Keyword NETO Subkeyword |F| Description Specifies the file name for the NETO; there must be NETO if assignment is being performed. The NETO can be a binary Cube Voyager/TP+ network. Alternatively, NETO can point to a Cube geodatabase network stored in an MDB file by designating the file name followed by a backslash and the Cube geodatabase network name. Specifies that the variables that are appended to NETO will have their assignment number set to this value. APPEND=5 would cause V, VC,TIME,V1... to be named V_5, VC_5, TIME_5, V1_5, etc. Specifies the number of decimal places to written to the NETO Volume fields. Values in the range 1-5 are valid. Specifies that the NETI variables that have names ending with the specified strings are to be excluded when copying NETI records to NETO. Thus, EXCLUDE=_1 will exclude all the first assignment variables. EXCLUDE=T_ is a special value that can be used to specify that the A-B and B-A values are NOT to be summed and included in the link records. Specifies that certain new variables are to be included in the NETO file. The intent of this keyword is to allow the user to compute LW.vars and selectively include them in the NETO. All LW.vars named by this keyword will appear in the NETO as LW_NAME_# (# is the assignment number value). You can specify a single variable with INCLUDE, but this only adds a variable that has the same value in each record. The variable will appear as name_# in NETO. Specifies the name of a file upon which paths from a PATHLOAD statement are to be written. Specifies how many decimal places are to be maintained in the cost values when they are written to the PATHO file. The link cost values will be rounded to this many decimal places; this allows for more efficient compressing of the data. The value must range from 1-5. Default value is 2.
NETO
APPEND
|I|
NETO NETO
DEC EXCLUDE
|I| |S20|
NETO
INCLUDE
|S20|
PATHO PATHO COSTDEC
|F10| |I|

Keyword PATHO Subkeyword ITERS |I| Description Indicates which iterations to write the PATHO file. Possible values are: PRINTO |KF| 0 All iterations 1 First iteration only 2 Last iteration only 3 First and last iteration only
Default is 0. Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=# See APPEND under PRINT on page 62. Specifies the file where binary matrices of values from subarea processing are to be written. The matrices on the file will be the final combination of values from all iterations. The number of matrices will be set by the highest PATHLOAD SUBAREAMAT[] index. The zonal configuration for the O/P matrices will be based upon the renumbering scheme obtained from the FILEI SUBAREANETI file. Specifies the maximum number of decimal places to retain in the SUBAREAMATO matrices. The values may be 0-9, S for a single-precision number, or D for a doubleprecision number. If not specified, or any other value is coded, the values will default to 2. This keyword is ignored if the format is not TPP. Specifies the desired output format for SUBAREAMATO matrices. Possible values are TPP, MINUTP, and TRANPLAN; if anything else is specified, or it is not specified at all (normal), the default is TPP. Specifies the individual names for the SUBAREAMATO matrices. This keyword is ignored if the format is not TPP.
PRINTO SUBAREAMATO
APPEND
|?| |KF|
SUBAREAMATO
DEC
|SV20|
SUBAREAMATO
FORMAT
|C|
SUBAREAMATO
NAME
|SV20|

Keyword TURNPENO Subkeyword |F| Description Specifies the file name where the movement delays from the junction model and/or the turn penalties from the turn penalty file will be written. In order to get the final travel time and cost skims from an assigned network it is necessary to pass the loaded network back through the Highway program and build and skim the paths from the loaded network. The TURNPENO file allows the movement delays computed by the Junction Model to be included in the path skims by using the TURNPENO file from the assignment as the TURNPENI file for the skims. The data structure is the same as that of the TURNPENI file but a comment field is added to indicate the movement is delay is from the junction model in lieu of a turn penalty or restriction. An example of the output is show below.
2606 2635 2635 2635 2635 2621 2621 2621 2621 2621 2773 2606 2615 2615 2773 1 1 1 2 1 0.08 ;junct 0.15 ;junct 0.15 ;junct -1.00 0.15 ;junct
TURNVOLO
|F|
Specifies the filename where the turning volumes are to be written. There may be more than one TURNVOLO specified; each may have a different format. Users must also specify TURNS to instruct program to accumulate turning volumes, otherwise, the TURNVOLO will be empty. The default format for this file is binary so that Cube can display it directly. Please note that the presence of the VARS keyword may alter the overall application of this statement. See Example using TURNVOLO on page 205. Specifies the number of decimal places to preserve when the file is either DBF of TXT. Character that is written in a TXT file. If this keyword is specified, the file will be delimited with this character. If it is not specified, the file will be fixed-field format. If the value is a character, it should be enclosed within quotes; but it may also be specified as a number that represents the desired character (for example, 9=TAB).
TURNVOLO TURNVOLO
DEC DELIMITER
|I| |c|

Keyword TURNVOLO Subkeyword FORMAT |S| Description Specifies the format for the file (must be BIN, DBF, or TXT). NOTE: FORMAT=BIN will automatically be reset to TXT if VARS= is specified on the statement. BIN Binary format that is usable only by Cube. The structure is: One header record (at least 64 bytes long): 0-1 total length of this record (bytes) 2-3 length of each turn record 3-6 bits whose position represents the presence of a turn volume 0: 1: 2: 1 always on for T0 1 if T[1] in the data records, 0 if not in data record 1 if T[2] present, o if not
3-31 same for T[3]... 7-64 Cube Voyager TURNVOL pppp.nnnn HIGHWAY date... pppp is the Cube Voyager project prefix nnnn is the Cube Voyager sequence number Individual records (length set in header): 0-1 Anode 2-3 Bnode 3-4 Exit Node 5-12 T[total] All Ts are double precision 13-201st T (T1) 21-282nd T DBF A standard DBF file will be written with each record containing the Anode, Bnode, ExitNode, T[0], and any appropriate T# values. The DBF header will name the variables that are in the data records.

Keyword TURNVOLO Subkeyword FORMAT (continued) Description TXT ASCII format either in fixed format or delimited. There is no header for this file; the structure of each record is: Anode, Bnode, ExitNode, T,T# (The user has to know which individual Ts are written to the file). The T values will be determined either by the DEC keyword, or internally by the program. Each volume will be formatted appropriately. If DELIMITER is specified, the fields will be written with only the delimiter separating them. If no DELIMITER, the fields will be in fixed width format; the program will determine the size. Note that VARS= will cause this format to change. TURNVOLO INCLUDE0 |?| Flag that when set false indicates that a turn movement with T values all equal to 0, is to not be written to the file. The default value is true. May be used if both VARS= and FORMAT=DBF are specified. The names are aligned with the VARS fields and then placed into the created dbf file. Optionally, the NAMES may be indexed [] to set the alignment for renaming only specific variables. Specifies which variables are to be written to the file. Note that if VARS is specified, FORMAT=BIN will be reset to FORMAT=TXT, or if there is no FORMAT specified, that it will default to TXT. Any of the following variables may be specified (in any order, and may even be repeated): A B C T T1 T2Tn, where n is the highest VOL in the application. Optionally, the variable name may have a standard PRINT form appended to it (enclosed within parenthesis). If decimals are to be printed with the values, it is suggested that an appended format be specified instead of DEC=. If a delimiter is desired, FORMAT=TXT, DELIMITER= must be specified.
TURNVOLO
NAMES
|S25|
TURNVOLO
VARS
|S25|
PATHLOAD must have the keyword ESTMO=T specified in order for
the trips assigned from that statement to be included in the matrix estimation. There may be more than one PATHLOAD statement with ESTMO=T on it. It does not make sense to have ESTMO=T on a
PATHLOAD statement that does not have VOL[]= on it. PATHLOAD must have the keyword PATHO=# in order to output the path file specified with FILEO PATHO= Example using TURNVOLO
MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7 NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2 TURNVOLO=AlternateA.Trn.Bin, format=BIN TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0 TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0 TURNVOLO=AlternateA.Trn.TXT, VARS=b(5) a(6) c(6) t(10.2) t1(10.2) t2(8.2) TURNVOLO=AlternateA.Trn.TXT, format=dbf, vars=a(5),b(5),c(5),t(8.2), t1(8.2),t2(8.2), names= Enter thru exit Total Cars Trucks
Example
MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7 NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2 TURNVOLO=AlternateA.Trn.Bin, format=BIN TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0 TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0 ESTMICPO=ESTMO.ICP, VAR=LI.COUNT, SCREENLINE=LW.SCREENLINE ESTMDATO=ESTMO.DAT, NAME='SL#1','SL#2','SL#3', NAME[5]='SL#5'
Example
/* Commands to generate a path file. */ FILEO PATHO[1]=myfile.pth, costdec=2, iters=0 . . . PATHLOAD PATH=TIME, PATHO=1, INCLUDECOST=F, NAME=TIME_PATH, ALLJ=T
FILET
Specifies where the Highway program writes various temporary files.
PATH
FILET keyword
Keyword Description |S| Specifies the path to the disk area where any temporary files are to be written.
PATH
The value for PATH is entered as a standard operating system path. If not specified, it will default to the path in the environment variable named TMP, or TEMP. The logic for determining the appropriate path, and opening the files is: If the PATH=' ', use current directory. If the PATH is specified, use it. If not specified, and TMP is, use TMP. If the operation fails, Fatal.
Example
PATH=' ' PATH=..\ PATH=c:\ ; use current directory ; up a directory ; root of c:
FILLMW
Fills work matrices. See FILLMW on page 510 for a complete description.
FUNCTION
Defines special functions. V TC COST Use FUNCTION statements to enter single expressions for computing certain values. The statements are inoperable by themselves, and can be anywhere in the input stream, the program dictates when they will be processed. It is recommended that they
be placed prior to the first PHASE statement or within the major phase in which they will be processed. If there is no function for a type, a default function will be used. The V function may be defined one time only. Each of the other functions is entered with an index [] to indicate which LinkClass it is to be applied to. All the functions can be on one FUNCTION statement, or they can be on individual statements, or some combination of both. To reduce confusion, some users may wish to code the functions on a single FUNCTION statement with a block control.
FUNCTION keywords
Keyword COST |NV999| Description Computes the cost for a link. COST is processed in LINKREAD and ADJUST to compute the cost. In LINKREAD, it is applied after the stack statements. In ADJUST, it is applied during capacity restraint, usually following a TC application, and after the user stack statements are completed. This is the only way to alter the cost values. Computes the congested time on a link by LINKCLASS. TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs). TC stands for congested time. The LINKREAD Phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. If no TC functions are defined then a default TC function is applied. The default TC function is the standard BPR with the form: TC[1] = T0 *(1 + TCCOEFF * (V/C) ^ TCEXP) where TCCOEFF defaults to 0.15 and TCEXP defaults to 4 if values are not specified with PARAMETERS. Specifying TC[1] alters the function. The user can also code their own functional form if the BPR form is not what is desired. In general, TC[#]=f(T0, V/C, TCCOEFF, TCEXP) but the user is free to experiment with any forms that make sense to them for their application.
TC
|NV999|
FUNCTION keywords (continued)

Keyword V |N| Description Computes the total volume on a link after an iteration. It is applied in the ADJUST phase. If there is no V function, V is assumed to be the sum of all the VOL sets (V[1] + V[2] + ... + V[n]). Some times the total volume should not be the sum of all the VOLs. For example: if a separate select link VOL set is being accumulated in addition to the total VOL set, that VOL set should be excluded from the total volume. Another example would be if one of the VOL sets is for a vehicle type for which it is desired to equate to a passenger car equivalent.
Example
FUNCTION { V = VOL[1] + VOL[3] + VOL[10]*1.3 TC[1] = T0 * (1 + 0.20 * (V/C) ^ 6) TC[201] = MIN(T0*5, T0 * (1.5 + 0.18 * (V/C) ^ 4)) COST[255] = TIME * 2 }
GOTO
GOTO label
NOTE: GOTO is not valid in the SETUP phase. You cannot place a :label statement inside a JLOOP statement. However, you can use a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP. Example
GOTO buildhwy GOTO :buildhwy
Example
GOTO tolls ... :tolls ... IF (expression) GOTO :tolls ; It is permissible to go backwards.

Performs certain operations based on conditions.
IF expression ELSEIF expression ELSE expression ENDIF
Use IF/ENDIF blocks to determine if certain operations are to be performed. IF blocks may be nested, but they may not overlap LOOP, JLOOP, or other IF blocks. If a variable in the expression is MI.n.name, ZI.n.name, or MW[], the same rules for indexing in a COMP statement are applied. MI.n.name or MW[] should realistically only be used within a JLOOP. Lengthy IF expression solutions could be time consuming; use them judiciously. Although IF expressions can be quite powerful for zonal selection, sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples below). You may append the following control statements to a single IF statement:
BREAK COMP CONTINUE EXIT GOTO PRINT
Example
IF (LI.DIST< 20) LIST=a,b,LI.dist; single IF with process
IF (expression) EXIT IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) ) . ELSEIF (loop_cntr > 10) . ELSEIF (loop_cntr > 5 && diff.time < 32) . ELSE . ENDIF
JLOOP ... ENDJLOOP

Controls a loop through the columns of a matrix row. Each row represents an origin zone and each column represents a destination zone. Typically, you use JLOOP ... ENDJLOOP blocks for matrix computations that you cannot complete with a single COMP MW control statement.
JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks. JLOOP keywords
Keyword J |I| Description Optional. List of up to three integers that define the value of the loop control variable. You may define each integer with an expression. Specify as:
J=Jbeg, Jend, Jinc
where: Jbeg defines the initial value of the loops control variable, J. Default value is 1. If you do not define Jbeg, you cannot define Jend or Jinc. In that case, Jend defaults to the number of zones in the network, and Jinc defaults to 1. Jend defines the terminal value of the loops control variable, J. Valid values range from 1 to the networks maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1. Jinc defines the increment for the loops control variable, J. If not specified, set to 1 or -1, depending on the direction from Jbeg to Jend.
Because the list of values for J can be expressions, you must separate the values with commas. Enclose expressions containing commas in parentheses. INCLUDE |I| Optional. List of origin zones that the program will process. If you include this keyword, the program will only process statements for these zones.
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
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
IF (I%2==0) LINKLOOP LW.VAR=LW.VAR*2 ; no [LINKNO] subscript needed ENDLINKLOOP ENDIF
LOOP ... ENDLOOP

Controls a general variable loop.
LOOP Lvar=Lbeg,Lend,Linc ... ENDLOOP
where: Lvar Name of the loop control variable. Lvar is not protected during the loop; computational, program, and other LOOP statements can alter its value. Lvar must be followed by Lbeg, and optionally, Lend and Linc. Lbeg Numeric expression that initializes Lvar. Lend Optional. Numeric expression that Lvar is compared to when processing the ENDLOOP statement. If not specified, no comparison is made and loop ends at ENDLOOP statement. Linc Optional. Numeric expression added to Lvar before making the ENDLOOP comparison. If not specified, Linc is set to 1 (or -1 if Lbeg and Lend are both constants and Lbeg < Lend; a backwards loop).
Use LOOPENDLOOP blocks to repeat a series of statements. LOOP initializes a variable; ENDLOOP compares the contents of the variable to another value, and branches back to the statement following the LOOP statement if the comparison fails. You can nest LOOP blocks, but you can overlap them with IF blocks. The process differs considerably from JLOOP. The logic is as follows: At LOOP: Initialize Lvar to Lbeg. Drop through to next statement.
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
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.

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 SETUP and LINKREAD phases on page 150 for details on how Cube Voyager obtains capacity from input network.) Default value is 1. COMBINE |KS| Specifies the method to combine the results of iteration volumes. Default value is EQUI. Possible values include: EQUI 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) With this method, there are several options that can be specified by the subkeyword LAMBDASEARCH (seeLAMBDASEARCH on page 218). 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.

Keyword COMBINE (continued) Subkeyword Description 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
COMBINE
FRACTIONS
|RV*|
Specifies the fractions to be when COMBINE is set to SUM. The number of fractions sets the value for MAXITERS. The sum of all the values should be 1.00; if the sum is not 1.00, a warning message will be issued. That will not preclude the program from executing. During the ADJUST phase for each iteration, V will be factored according to the FRACTIONS for that iteration, and added to the V accumulated for the prior iterations.

Keyword COMBINE Subkeyword LAMBDASEARCH |S| Description 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.
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 159. 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. EQUITURNCOSTFAC |KR| Factor used to convert turn delays from minutes to cost for estimating Lambda in the equilibrium process. Default value is 0. If the default value (0) is used, turning volumes and delays from JUNCTIONI processing are not included in the estimation. This value is used only if: there are turning volumes and COMBINE is set to EQUI. When use, this value typically specifies the same value as TURNCOSTFAC. GAP1 |KR| Specifies the cutoff point based upon the relative difference in system cost (volume * cost) between two iterations. Default value is 0.005.
CONSOLIDATE
|I|

Keyword MATOADJUST Subkeyword |KI| Description 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 MAXMW |KI| |KI| Specifies maximum number of assignment iterations to be performed. Default value is 10. 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. 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.
MAXSTRING
|KI|
MODELPERIOD
|KR|
PDIFF1
|KR|
PDIFFVALUE1
|KR|

Keyword RAAD1 Subkeyword |KR| Description 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.
RELATIVEGAP1 RMSE1
|KR| |KR|

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.

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|

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
EXCLUDEJ INCLUDEJ LINKIDARRAY (LINKIDCNTMW LINKIDMW LINKIDLASTUSE LINKID#MW) MW (NOACCESS SELECTLINK SELECTGROUP SELECTLINKGROUP) PATH (DEC) PATHO (ALLJ INCLUDECOST NAME PATHOGROUP (FULLPATH)) PENI PENIFACTOR 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
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 218 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. LINKIDARRAY LINKIDARRAY LINKIDCNTMW |S| |I| 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.
PATHLOAD keywords (continued)

Keyword LINKIDARRAY LINKIDARRAY Subkeyword LINKIDLASTUSE LINKIDMW |I| |IP| Description Specifies the MW[] in which to store the information for the last link in the list. List of MW numbers where the monotonic succession of link crossing information (beginning at 1) is to be stored. For example, LINKIDMW=10-13,6,8 means that the first links information will be stored in MW[10]; the second links information will be stored in MW[11]; the fifth links information will be stored in MW[6], and so on. LINKIDARRAY LINKID#MW |IP| List of MW numbers where the monotonic succession of numbers of the links (beginning at 1) is to be stored. For example, LINKID#MW=10-13,6,8 means that the number of the first link will be stored in MW[10]; the second link will be stored in MW[11]; the fifth link will be stored in MW[6]. Link arrays can then be addressed directly by using these values. For example, ANODE = A[MW[1]] xxx = LW.xyz[MW[2]]. MW[] |N| Generates a matrix row, almost in the same manner as a regular COMP MW[]= statement. The primary difference is that this expression has access to the values from the I-J paths that result from the PATH keyword. Two-level indexing is not allowed here; the computation implies a J=1,Zones loop. If there are INCLUDEJ and/or EXCLUDEJ values on the statement, only those corresponding columns in the MW will be processed; the excluded cells will not be altered. There may be multiple MWs specified on the statement; they will be processed in the order they appear on the statement. Typical types of matrices computed include: Path-based matrix A matrix with I-J path values, such as distance, cost, time, etc. This is often referred to as a LOS (level-of-service) matrix. Many traditionalists refer to such matrices as skim values, because the values are skimmed from the network. To obtain zone-zone values, the PATHTRACE(name) function is used. For example, to obtain zone-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.

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.

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|

Keyword MW[] Subkeyword SELECTLINK |s| Description Expression used to determine if the I-J path uses certain facilities. The expression must be enclosed within parenthesis, and can contain any of the following variables: A B N L The A-node of a link; only useful to select links with a path begins at A. The B-node of a link; only useful to select links with a path ends at B. A node that must be used in the path. A link that must be used in the path. Links are coded as A-B (directional) or A-B* (non-directional link may be traversed in either direction).
Any of these variables can have multiple values specified for them. Nodes (A, B, N) can be specified as single values and/or as ranges; L can have multiple links specified. When the multiple value specification is used, the implication is a logical OR amongst the values. Example: N=100,105,200-205 means if N is 100, or if N is 105, or if N is a value between 200 and 205, inclusive. The selection is processed by examining each link/node in the path, on both an individual link and a total path basis. The process is from left to right. Each link/node is processed, and as long as it does not fail any conditions, it is considered as a candidate for processing in the total path. In the total path basis, the link/node is considered in conjunction with other links/nodes in the path. Examples may better illustrate the process.

Keyword MW[] Subkeyword SELECTLINK (continued) Description Sample path: 1-101-102-103-104-105-2 (A=1) Node 1 is on the path in any link except the last: true (A=1 && B=102) Node 1 is on the path in any link except the last, and node 102 is on the path in any link but the first: false (L=101-102,104-200) Link 101-102, or Link 104-200 is on the path: true (L=102-101*) The path contains link 101-102 or link 102101: true (L=101-102* && L=104-105*) The path contains link (101102 or 102-101) and link (104-105 or 105-104): true (N=101 && N=105-110 && L=101-102*) The path contains node 101 and any node in the range of 105-110, and link (101-102 or 102-101): true ((N=100-105) && (N=8,57 || L=105-104)) The path crosses any node 100-105, and (it crosses node (8 or 57) or link 105-104): false. If L=104-105* instead of L=104-105, the expression would be true. Citilabs recommends using nested parentheses to help categorize the comparison sets. With this type of Boolean selection, most any desired combination of path usage can be specified. MW[] SELECTLINKGROUP |s| Expression used to determine if the I-J path meets select link criteria based upon some level of link group codes. The expression should contain mostly GRP[] values and perhaps I and J; nothing else is really appropriate. The tracing mechanism accumulates how many links of each group code are used in the path. Those totals are available to the expression. The following example says if the path uses at least three links with group code 1 and at least one link with group 2 or if the path uses at least five links with group 7 or if the path uses exactly two group 6 links the path meets SELECTLINKGROUP criteria. Example
SELECTLINKGROUP=((grp[1]>3 && grp[2]>=1)|| grp[7]>=5 || grp[6]=2)

Keyword PATH PATH DEC Subkeyword |KS| |S| Description Specifies the link value on which the paths are to be built. Valid values are: Cost, Time, Dist, LI.name, or LW.name. Specifies the accuracy of the link value on which the paths are to be built. Default value is F. Valid values for DEC are: 0, 1, 2, 3, 4, and F, which represent 0, 1, 2, 3, 4 decimal places and floating point, respectively. Using lower accuracy will speed up the assignment process considerably, especially for larger networks. PATHO |I| Number (#) to specify that a path file is to be written to FILEO PATHO[#]. The file will contain I-J paths generated by this PATHLOAD statement. The number of I-J paths will be determined by the value of the PATHLOAD PATHO ALLJ keyword. If PATHO is not specified, the PATHO file will not be written for this statement. The path file can be used in Cube for analysis of what happened during this assignment, or for various post processing capabilities, such as selected link analysis, or recreation of parts of the assignment. The generated file can be very large and writing it can cause a considerable increase in running time. Switch that indicates if PATHO write processing is to be invoked for all I-J paths, or for only the I-J paths where an actual assignment is performed. By default this value is false, unless this application is path building only (No FILEO NETO=value and no PATHLOAD VOL= value). T/F flag used with PATHOGROUP to keep partial or full paths for the specified GROUP(s). Switch to indicate if the path records are to include the cost values (based upon the PATH=array values). The cost through every link in every path is written; this can cause a considerable increase in the size of the file. Name to be applied to the paths written for this statement. A PATHO file may have multiple path sets written to it by different PATHLOAD statements. However, the same NAME path set may not be written to a file more than one time for an I zone. If an attempt to write the same NAME to a file for the same I zone is made, only the first set will be written, and there will be no message indicating that this attempted duplication occurred.
PATHO
ALLJ
|?|
PATHO PATHO
FULLPATH INCLUDECOST
|?| |?|
PATHO
NAME
|S|

Keyword PATHO Subkeyword PATHOGROUP |IP| Description List of numbers (1-32). The numbers are associated with GROUP ADDTOGROUP= process in LINKREAD. The ADDTOGROUP numbers are typically associated with specific LI. or LW. values via a conditional statement thus links are either associated with the group or not. When the trace of a path is examined, if the trace does not contain any of the selected links in the group(s) nothing is written to the PATHO file. If the path does contain a specified link in the group(s), and the FULLPATH subkeyword is F, the trace will contain only I, the nodes of the specified links in the group(s), and J. If the path does contain a specified link in the group(s), and the FULLPATH subkeyword is T, the trace will contain I, all the nodes of any path that uses any of the specified links in the group(s), and J. The use of PATHOGROUP= with FULLPATH=T/F and setting appropriate group(s) with ADDTOGROUP= allows the user to limit the paths written to the PATHO file by keeping only those paths and the portions of the paths the user may be interested in for further analysis and display. This can considerable reduce the size of the stored path file. PENI |IP| Specifies the PENI set(s) that are to be used in building this path. You can specify any combination of valid PENI indices. A set number must be 1-8; the valid numbers on the TURNPENI file. If a JUNCTIONI file is provided, then the SET keyword is required to reserve one penalty set numbers for use with the junction delays. The set number used for the junction delays must be listed on the PENI keyword value along with any additional turn penalty set that may be specified with TURNPENI in the same run. Expression that specifies a factor for all penalties during path building. This is not specifically related to JUNCTION; it applies to all penalties (TURNPENI and SET=).
PENIFACTOR
|N|

Keyword SUBAREAMAT Subkeyword |N| Description Specifies that the program is to compute an expression for every J and write that value onto any subarea extracted records. For example: SUBAREAMAT[1] = MW[3] specifies that for every J of the current I path set, if the path from I-J has some portion within the subarea, a value is to be inserted to the subarea matrix. There must be an index for the keyword. The highest index is used to set the number of matrices on the SUBAREAMAT file. This process is described in ILOOP phase on page 154. SUBAREAMAT MAXMSG |I2| Specifies how many messages to print about improper cordon crossings and the error level to assign to the messages. Two values are allowed: The first value specifies how many messages are printed for the SUBAREAMAT. The second value specifies the error level to assign to the message when the number of messages reaches the first value.
The printed messages will be assigned an error level of 1 less than the second value for all messages except the last one. For example: MAXMSG=50,2 indicates that the first 50 improper crossings are to be printed at error level 1, but the program will terminate with error level 2, at the 50th message. TOLLFACTOR |N| Expression that specifies a factor for converting tolls to COST units. Generally paths are built on TIME and TIME is in the units of minutes. If a generalized COST function is used for path building, all components of this function are typically appropriately factored to be in generalized minutes. Units must be (path cost units)/(toll cost units). For example, if tolls are coded in $US and path costs in minutes, then the TOLLFACTOR expression must specify a value in minutes/$US. An assumed traveler value of time of US$15/Hour would be implemented by setting TOLLFACTOR to 4 (60/VOT).

Keyword TOLLMATI Subkeyword |IP| Description Indicates that gate-to-gate tolls are to be included in the COST used for path building and specifies the FILEI TOLLMATI[#]= file number and toll set on the file to be used. Specifying TOLLMATI=1,2 indicates to use toll set 2 on TOLLMATI file 1. See Path-based tolls on page 146. THRUNODE |I| Sets the minimum node number allowed to be included in the path building process. The value has to be a positive integer. The default value is ZONES+1. The default value excludes centroids as intermediate points of a path. Specifies if any paths from I to the selected destinations are to be formatted and reported for this path. The select expression must be enclosed within parenthesis. Most likely, the variables used in the expression would be I, J, and Iteration, but any valid variable can be used. The TRACE expression is evaluated for J=1,Zones. Example:
PATHLOAD PATH=TIME TRACE=(I=1-10 & J=100150)
TRACE
|S|
The selected path traces will be listed in the run print file. The TRACE keyword can now use the PRINT statement keywords as subkeywords to format and direct the print of the path trace(s) to an external PRINTO file. The following additional subkeywords can be used: PRINTO (REWIND PRINT) CSV CFORM FORM LIST See PRINT on page 238 for details on these subkeywords. The LIST subkeyword may be any valid input (li.) or work (lw.) array or it can be set to _pathcost to list the accumulated value of the COST function along the path trace. See TRACE example on page 236.

Keyword VOL[] Subkeyword |N| Description Specifies an expression to be solved for J, and that the result of the expression is to be assigned to the links in the path generated by the PATH keyword. VOL should be indexed [], but if it is not, the index is implied to be 1. The index range is 1-20; there may be up to 20 volume sets in a single application of Highway. The values are added to the volumes. In most cases, there will be a single VOL for a PATHLOAD statement, but there are many cases, where it will be advantageous to have more than one VOL. For example, if a standard assignment is to be performed, and it is desired to have another assignment made of just the trips that meet select link criteria, that is easily accomplished. Or, perhaps it is desired to assign all vehicles, and to determine what types of trips make up the volumes on each link. The examples below illustrate these capabilities. It should be noted that when specifying multiple VOL keywords, you must specify the FUNCTION V so the program knows which VOL combinations are to be used for capacity analysis. Specifies the name of a link value that should be used in restricting the links that should be included in the VOL assignment. The primary use of this keyword is for air quality analysis. An example would be to obtain what portion of the volume on a link is in cold start mode. In that case, VOL[2]=MI.1.TRIPS, TIME=0-7.5 would mean to assign only to the links that are within 7.5 minutes from the origin zone. A single range of numbers is required for this keyword. In the example, if a 3 minute links A node were 6 minutes from I, only 50% of the trip value would be added to the link volume (7.5 is 50% of the way from 6 minutes to 9 minutes). Normally, the range would be 0-some number, but if the range were say, 7.5-99999, only the hot running portion of the trip would be assigned.
VOL[]
Valuename
|S|
TRACE example
RUN PGM=HIGHWAY FILEO PRINTO[1] = PATH.CSV FILEO PRINTO[2] = PATH_TRACE_RPT.DAT FILEI NETI = TEST.NET PHASE = LINKREAD FromNode=1500 ToNode=1875 lw.fac_dist=10*li.DISTANCE lw.flag1=1 ENDPHASE PROCESS PHASE=ILOOP if (I < FromNode) _skiptoI=FromNode ; speeds up process IF (I=FromNode) ; build paths for select I PATHLOAD PATH=li.TIME mw[1]=PATHTRACE(li.TIME), mw[2]=PATHTRACE(li.DISTANCE), TRACE=(I=FromNode & J=ToNode) PRINTO=2 PRINT=T F=6.0, LIST=I,J,A,B,li.TIME(8.3),_pathcost(8.3), li.DISTANCE(8.4),lw.flag1(3.0), lw.fac_dist(10.2) ;Print results to formatted file to check against TRACE JLOOP IF (J=ToNode) ; FROM, TO, TIME, DISTANCE PRINT CSV=T, PRINTO=1, LIST='FromNode','ToNode','TIME','DISTANCE' PRINT CSV=T, PRINTO=1, LIST=FromNode(5.0),ToNode(5.0),mw[1](10.2),mw[2](10.2) ENDIF ENDJLOOP EXIT ENDIF ENDPROCESS ENDRUN
An example of getting toll costs would entail having a LOOKUP function where the lookup value is the gate-gate combination traversed on the path and the result of the function is the toll value associated with gate-gate movement.
LINKIDMW=1-2 Cost = tolllook(MW[1]*1000+MW[2])
See Highway example 7 on page 258 for an example of using the LINKIDARRAY keyword and its subkeywords in a script.
PATHLOAD example
PATHLOAD PATH=COST, VOL[1]=MI.1.ODTRIPS PATHLOAD PATH=COST, MW[6]=MW[3], SELECTLINK=(L=2001-2004), VOL[1]=MW[3], VOL[2]=MW[6],VOL[3]=MW[3],TIME=0-7.5
This first PATHLOAD statement causes the COST paths to be built, and then the values from MI.1.ODTRIPS are assigned and added to VOL[1]. The second PATHLOAD statement causes the following sequence of events:
1. COST paths are built. 2. MW[6] is set equal to the values in MW[3] for the Js whose path
from I crosses link 2001-2004. Note that MW[6] was cleared at the beginning of the ILOOP for I, but if the user caused any values to be set into MW[6] prior to this statement, the MW[6] values could be incorrect.
3. The values from MW[3] are assigned to the COST paths and
added into VOL[1] volumes.

4. The values from MW[6] (the selected link trips) are assigned to
the COST paths and added into VOL[2].

5. The values from MW[3] are assigned to only the links that are
within 7.5 minutes from I and added into VOL[3] (these are the cold start volumes).
Example
/* The first PATHLOAD statement below (PATH is a trigger keyword PATHLOAD is not required) builds the DISTANCE paths and illustrates two different ways to extract a LOS matrix for the path. The second PATHLOAD statement builds the COST path using penalties and shows that the two extracted matrices are not necessarily the same because of the penalties. The comments illustrate how to properly skim a path when penalties should be incorporated. */ PATH=LI.DISTANCE,MW[1]=PATHTRACE(LI.DISTANCE),MW[2]=PATHCOST ; MW[1] and MW[2] are the same in this case PATH=TIME, PENI=1,3 MW[1]=PATHTRACE(COST),MW[2]=PATHCOST
; MW[1]and MW[2] could be different because penalties are used ; in the path. If MW[1]=PATHTRACE(TIME,1,3),they would be the same. /* Following is an example of trip splitting based upon the relative difference of time if a link (say, a bridge) is added to the network. In this example the link is already in the network, and it can be unavailable to the path builder by excluding links with group code 1. The steps are: 1. Compute the time path with the bridge included and extract the times along the path into MW[1]. 2. Compute another path with the bridge excluded (group=1)and extract the times along the path into MW[2] 3. Compute a path split based upon the total times for the two sets of paths. The portion of trips that would use the bridge path is computed based upon the values in the two time LOS matrices [1] and [2]. If the time saved exceeds 10 minutes and the relative saving (time saved / total trip time) is greater than 15 percent, the portion of trips that will use the bridge path is set equal to the relative saving. (This is to illustrate a method of application, and is not meant to imply any type of realistic diversion.) 4. Assign a portion of the trips to the one path set, and the remaining trips to the other path set. The two assignments are made to the same volume set, but, they could have just as easily be kept separate. */ PHASE=LINKREAD If ((A=1001 & B=1002) | (A=1002 & B=1001)) ADDTOGROUP=1 PHASE=ILOOP PATHLOAD PATH=TIME, MW[1]=PATHTRACE(TIME) ;w bridge PATHLOAD PATH=TIME, EXCLUDEGROUP=1 MW[2]=PATHTRACE(TIME) ;wo bridge JLOOP; MW[3] = the fraction of trips diverted to the bridge path TimeSaved = MW[2] - MW[1]; 2 is always >= 1. Divert = 0 RelativeSaving = TimeSaved / MW[2] IF (TimeSaved > 10 && RelativeSaving >.15)Divert = RelativeSaving MW[3] = Divert ENDJLOOP ;assign bridge trips PATHLOAD PATH=TIME, VOL[1]=MI.1.TRIPS*MW[3] PATHLOAD PATH=TIME, EXCLUDEGROUP=1, VOL[1]=MI.1.TRIPS*(1-MW[3])
PRINT
Formats and prints a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT)
See PRINT on page 62 for details.

Example
IF (ITERATION = 0) ; LIST INPUT LINKS LIST= A(5), B(5), NI.DIST(6), T0(6.2) ENDIF IF (ADJUST=1 && ITERATION >5 && VC >2.0) LIST='BIGVC for: ',A,B,VC(5.2)
PRINTROW
Formats and prints row(s) of matrices. MW J TITLE FORM MAXPERLINE BASE1 See PRINTROW on page 69 for details.
Example
PRINTROW mw=1-2,1 form=LRD title='form=LRD' PRINTROW mw=1-21 form=6D base1=y maxperline=10 form=6D, base1=y maxperline=10
PROCESS ... ENDPROCESS

Establishes phase blocks. PHASE ENDPHASE A user process phase stack is defined by a PROCESS statement that names it and an ENDPROCESS statement that ends it. To simplify coding, the PROCESS control word is not necessary; PHASE=name may be used directly. And, to further simplify coding, the ENDPROCESS statement is not necessary; the occurrence of another
PROCESS statement acts as the ENDPROCESS statement. If ENDPROCESS is used, it may be coded as either ENDPROCESS or ENDPHASE. PROCESS keywords
Keyword PHASE |KS| Description Names the phase stack. The control statements that follow it, until an ENDPROCESS statement or another PROCESS statement is encountered, will be executed when the phase is internally executed. Exception: Static statements, such as PARAMETERS, FILEI, FILEO, and LOOKUP, are not processed within the stack, even if that is where they are coded. The following names may be specified: ENDPHASE |K| SETUP LINKREAD ILOOP ADJUST
Defines the end of the user control statements for a stack.
Example
PHASE=LINKREAD T0 = LI.DISTANCE*60 / SPEED ENDPHASE PHASE=ILOOP PATH=TIME, VOL[1]=MI.1.ODTRIPS ENDPHASE PHASE=ADJUST LW.TIME = TIME * LW.FLAGCODE ENDPHASE
REPORT
Requests reports and establishes tracing. CAPACITY PENI
SPEED TRACE VDTSPD (VOL I J RANGE FILE) ZDAT (DEC)

REPORT keywords
Keyword CAPACITY PENI Subkeyword |?| |?| Description Switch that indicates if the capacity portion on the SPDCAP tables is to be reported. Switch to turn off dynamic printing of the turn delays calculated by the junction model and reported every iteration. If there are a larger number of junctions coded in the network then PENI=T could result in voluminous print file. Switch that indicates if the speed portion on the SPDCAP tables is to be reported. Controls the listing of the stack statements as they are processed (can be quite voluminous, so be careful). Trace can be turned on and off at any time, thus controlling the amount of output as desired. If a COMP is traced, only the first five J values will be reported. Switch that indicates if the vehicle distance traveled stratified by average trip speed is reported. Note that this report requires considerably more computer resources (both process time and disk space). If no subkeywords are appended to this keyword, the program will simulate: RANGE=0100-1. There may be any number of VDTSPD keywords. Specifies which origin zones are to be included in this report. If this keyword is not specified, all origin zones will be included. Specifies which destination zones are to be included in this report. If this keyword is not specified, all destination zones will be included.
SPEED TRACE
|?| |K?|
VDTSPD
|?|
VDTSPD
|IV|
VDTSPD
|IV|
REPORT keywords (continued)

Keyword VDTSPD Subkeyword FILE |F| Description Specifies a file where the VDTSPD reports are to be written (exported) in a format that can be easily read by most spreadsheet software. Specifying FILE will not preclude the reports from being printed. If the same file is specified following different VDTSPD keywords, the output will be stacked onto the file. Specifies the speed stratification for this report. The values can have at most one decimal place. There must be at least two values, and possibly three for each sub report. For example:
RANGE=0-100 specifies that the report is to
VDTSPD
RANGE
|IP|
have only one number reported.

RANGE=0-100-1 specifies that the report is
to have 100 values reported.

RANGE=0-7.5, 7.5-100-5 specifies that two different schemes are to be obtained.
With multiple RANGE sets, an I-J value can be placed into more than one RANGE set. Each subreport will not only contain values for the RANGE specified, it will also include any values less than the low value and any values greater than the highest value. If RANGE=2-5-1 is specified, the printed report will appear as: x - 2 Interval includes speeds >= x and < 2, x is the lowest speed found 2 - 3 Interval includes speeds >= 2 and < 3 3 - 4 Interval includes speeds >= 3 and < 4 4 - 5 Interval includes speeds >= 4 and < 5 5 - y Interval includes speeds >= 5, y is the highest speed found

Keyword VDTSPD Subkeyword VOL |IP| Description Specifies which volume sets are to be included in this report. If this keyword is not specified, the program will report all volume sets. Switch that indicates if all the internal arrays obtained from FILEI ZDATI files are to be reported. Sets the maximum number of decimal places to be printed for any variable. This one value applies to all variables on all ZDATI statements.
ZDAT ZDAT DEC
|?| |I|
Example
TRACE=y ; turn stack tracing on REPORT CAPACITY=yes ; report the capacities by lane by CAPCLASS REPORT VDTSPD=T, VOL=1, I=1-933, J=1-933, RANGES=0-7.5, 7.5-100-5, FILE=VDTSPD.TXT
SET
Sets multiple variables or arrays to the same value. VAL VARS Use SET to set any number of variables to some value. All variables are set to zero when they are first allocated. COMP statements produce most changes. A COMP statement is not as efficient as a SET statement.
SET keywords
Keyword VAL |R| Description Value that the VARS that follow will be set to. It must be a numeric constant. VAL is initialized to zero when the statement is encountered. List of variables that are to be set to the more recent value of VAL obtained from this statement. If a VARS is the name of an array established on an ARRAY statement, the entire array will be set to VAL.
VARS
|S|
Example
SET VAL=0, VARS=TOT1,TOT2,COUNTER TOT1=0 TOT2=0 COUNTER=0 ; is a COMP statement to do the same thing SET VARS=TOT1 TOT2 COUNTER ; is also the same (VAL is 0) SET VAL=123 VARS=C123, VARS=TOT1, TOT2, TOT3 ; sets all to 123 SET VAL=0, VARS=VA1,VA2,VA3, VAL=100, VARS=VX, VY
SETGROUP
Sets group codes for a link. ADDTOGROUP REMOVEFROMGROUP Use SETGROUP to set group codes for a link; it is applicable during only the LINKREAD phase. Group codes are used primarily for designating links that are to be excluded in path-building, and for inclusion in select link analysis. Each link can have up to 32 different group codes assigned to it. The codes are numbered 1-32. There are no preconceived definitions for the codes; that is the users responsibility. Group codes can be quite helpful in project analysis or for determining specific interchange to interchange movements.
SETGROUP keywords
Keyword ADDTOGROUP |KIP| Description Specifies that the current link is to be assigned the codes that are in the value list. Specifies that the current link is to have the designated values removed from its codes. This keyword normally should not be used.
REMOVEFROMGROUP
|KIP|
Example
PHASE=LINKREAD IF (LI.SPDCLASS==1-3,6,9,55) ADDTOGROUP=1
SORT
Sorts user-defined arrays. ARRAY NUMRECS See SORT on page 72 for details.
SPDCAP
Revises speed and capacity tables. CAPACITY LANES SPEED The SPDCAP statement is the same as that used in the Network program to revise the SPEED and CAPACITY tables attached to the network. If this statement is used in the control file for the Highway program, the values from the NETI are updated when NETI is opened. This capability allows you to test various scenarios without having to modify the network. The revised tables will be written to the NETO file.
SPDCAP keywords
Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. All values must be 09999, inclusive. The capacity array is initialized to 20 times the index number, for all lane stratification (CAPACITY[1]=20, CAPACITY[2]=40...). Lane stratification that any following CAPACITY and/or SPEED values are to apply to. LANES may be interspersed with other keywords and values on the statement. All values must be 1-9, inclusive. Speed to be applied to the link. All values must be 03276.7, inclusive. The speed array is initialized to the index number, for all lane stratification (SPEED[1...99]=1,2,...99). Speed is maintained with one decimal place.
LANES
|IV|
SPEED
|RV*99|
A network contains an array of capacity and speed data. Each array is dimensioned with ninety-nine values for each of nine lane stratification, and contains 891 values. When an array is accessed, the program uses the number of lanes (LANES) as the row index, and the capacity and/or speed classification (CAPCLASS, SPDCLASS) as the column index to obtain a value for a link. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement, LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector data, and may be indexed to set a specific loading place, and may have null fields to skip the revision of certain columns. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables.
Example
;Set entire table to 50, ; then revise the values for 20,21, and 24 for lanes 1,3,8 SPDCAP CAPACITY=99*50, LANES=1,3,8, CAPACITY[20]=300,400,,,700 SPDCAP LANES=2,4-9, SPEED=20.5,30.3,50.6,,,88.2, LANES=5,SPEED[15]=15 SPDCAP SPEED=30, LANES=2-8; Inappropriate; the LANES will not be used.
TURNS
Requests turning movement volumes. NT Use TURNS to request that the volumes at specific interchanges (nodes) be accumulated. If there is at least one TURNS statement, the program will accumulate turns for every PATHLOAD VOL[]= statement that is present. At the end of each iteration (in the Adjust phase), a single total turn volume will be computed for each movement at the nodes where turns are requested. By default, the single volume is computed by adding all the individual turn volume sets together (T = TURN[1] + TURN [2] + TURN [..] ...). This default accumulation process can be overridden by using the T= capabilities on this statement. Usually, the T= expression should be parallel to the V= expression that is specified on a FUNCTION statement. The value of T for each movement will be computed in the Adjust phase, and then combined with other iteration values to form the combined volume.
To accumulate turn volumes, you must specify a FILEO TURNVOLO statement. The turn volumes will be written to the file(s) specified on that statement.
TURNS keywords
Keyword N T |IP| |N| Description List of nodes at which turning volumes are to be accumulated. Expression used to compute the total volume at each of the nodes.
Example
FILEO TURNVOLO=myfile.trn, FORMAT=BIN TURNS N=1000-2000,3000,5000-6000,19000-32000, T=TURN[1] + TURN[3]
Highway Program Theory
Theory
This section discusses the theory used in the Highway program. Topics include: Process overview User stacks
Process overview
It is important to have a basic understanding of the logic of the program, so that when certain special operations are to be performed, they can be placed properly. Although you can place phases in the script in any order, Citilabs suggests that you use a basic template for all applications. If you use a basic template, then only the actual operations of each segment need be completed.
Example of suggested basic application template
RUN PGM=HIGHWAY FILEI FILEO FUNCTION ; include V, TC, and COST functions here PHASE=SETUP ; normally this phase is not used ... PHASE=LINKREAD ; insert any statements required to: ; extract custom information from the input network. ... PHASE=ILOOP ; build paths, skim paths, load trips to paths ... PHASE=ADJUST ; revise special LW.values for next iteration ... PHASE=CONVERGE ; optional for user specified convergence tests ... ENDRUN
The internal logic of the program is as follows: PHASE = SETUP Establish user SET arrays, etc. This phase is not specified by most users. If there is a PHASE=SETUP block, perform the statements of the block. ENDPHASE PHASE = LINKREAD Loop LINKNO=1,NUMLINKS Read each link record. If there is a user supplied LINKREAD block, process it, then set the required values that LINKREAD did not set properly Set the Time and Cost values
EndLoop ENDPHASE LOOP ITERATION=1,MAXITERS PHASE = ILOOP Loop I=1,ZONES Read required MATIs. Process the ILOOP stack. Write requested MATOs.
EndLoop ENDPHASE PHASE = ADJUST Loop LINKNO=1,NUMLINKS Read each link record. Obtain link values using most of the LINKREAD process Apply the appropriate Functions (V, TC, COST) for the link.
Process the users ADJUST stack to either list the results of the assignment, or to revise LW.values, or Time for the next iteration. Apply Function Cost.
EndLoop. Depending upon the values for COMBINE and ITERATION: Combine link volumes. Combine MATO matrices.
Process the CONVERGE stack (user or default) If Convergence met, exit ITERATION Loop. ENDPHASE ENDLOOP ; Iteration loop
User stacks
These are stacks of control statements that you provide to perform certain operations at various times in the process. The term stack, as used here, means all the user supplied statements for the phase. Stack and phase are sometimes used interchangeably. Phase refers to a phase the program automatically processes, and stack refers to the user supplied statement for that phase. The ILOOP stack is required, but all the others are optional. Most times, the other stacks will not be necessary, but it does provide a mechanism for altering program variable values at crucial times. Each stack begins with a PROCESS PHASE = StackName statement. (PHASE is a trigger key, so most users will just code PHASE= without the leading control word.) The operational statements that are to be preformed in this stack follow the PHASE statement. The stack is terminated by the presence of another PHASE = stackname statement, an ENDPHASE statement, or the end of input. Non-operational statements (FILEI, FILEO, PARAMETERS, FUNCTION and others) can be within a stack, but they are ignored during stack processing. It is suggested that all non-operational statements be placed at the beginning of the input for reader clarification. Each of the phases, may be specified one time only. IF and LOOP blocks must be
complete within a stack, and GOTO and associated label statements must be within the same stack. EXIT and ABORT will cause termination of a stack, but will have impact on the actual program process only from ILOOP.
LINKREAD stack
This stack is in the LINKREAD phase, and is used as explained above in that section. Primarily, it is used to obtain required link values (if they are not directly available from the input network), and to set link LW.values and GROUP codes.
ILOOP stack
This stack is the entire ILOOP phase, and is described previously. It MUST be present.
ADJUST stack
This stack is processed as the last operation in the ADJUST phase link loop. It provides a place for computing and accumulating special values such as objective functions (currently undocumented). It also provides the capability to print certain link values during the process. If LW.values are dependent upon Time and/or Cost, and it is necessary to reflect the changes in those values to the LW.values for the next iteration, the adjustment can be made here. Alternatively, the LW.values can be adjusted with ILOOP statements.
CONVERGE stack
This stack is processed during convergence testing in the ADJUST phase. Its primary purpose is to set BALANCE to 1 if certain conditions are met. Most users will not have any need for this stack.
Highway Program Examples
Examples
This section contains examples for using the Highway program: Highway example 1 Highway example 2 Highway example 3 Highway example 4 Highway example 5 Highway example 6 Highway example 7 Highway example 8
Highway example 1
/* EXAMPLE 1 This example shows a simple equilibrium assignment procedure assuming a typical input highway network providing CAPACITY, DISTANCE AND SPEED on the link attributes. */ RUN PGM=HIGHWAY FILEI NETI = Network.net FILEI MATI[1] = TRIPS.mat FILEO NETO = LOADED.NET PARAMETERS COMBINE=EQUI MAXITERS = 99 GAP=.0001 PROCESS PHASE = LINKREAD C = LI.CAPACITY ; set capacity equal to a link field ; assumes DISTANCE and SPEED are available on the input network ; no LINKCLASS defined, therefore defaults to 1 for all links ENDPROCESS PROCESS PHASE=ILOOP ; main loop for program PATHLOAD PATH=TIME, ; build path based on time VOL[1]=MI.1.CAR, ; load trips from input matrix to volume set 1 ENDPROCESS ; No TC functions defined therefore congested travel times computed using ; the standard BPR formula for all links. ; No COST function defined therefore COST defaults to TIME ENDRUN
Highway example 2
/* EXAMPLE 2 Simple example of using HIGHWAY to SKIM level of service information from the loaded highway network from Example 1. This example builds paths on the congested travel time variable in the loaded network and Skims or extracts the zone-to-zone times and distances for those paths to an external matrix file. */ RUN PGM=HIGHWAY FILEI NETI = LOADED.NET FILEO MATO[1] = HWY_SKIMS.MAT, MO=1-2,NAME= 'HWY Time', HWY Distance PROCESS PHASE=LINKREAD T0=li.TIME_1 ; Final congested travel times on the input network ENDPROCESS PROCESS PHASE=ILOOP ; Loop across all origin zones and build path using congested time. ; skim TIME and DISTANCE for the min TIME paths into work matrices 1 and 2 PATHLOAD PATH=TIME, MW[1]=PATHTRACE(TIME), MW[2]=PATHTRACE(LI.DISTANCE) ; For intrazonals, make the intrazonal time equal to half the time to the nearest zone COMP MW[1][I] = rowmin(1) * 0.5 ; Intrazonal time ; Set the intrazonal distance equal to 0 COMP MW[2][I] = 0 ENDPROCESS ENDRUN
Highway example 3
/* EXAMPLE 3 This example shows a multi user class equilibrium assignment, building paths on a generalized cost function with the cost functions differentiated by the facility type (LINKCLASS). Turn penalties are included in the path building process and the PATH file is saved for graphical analysis */ RUN PGM=HIGHWAY FILEI NETI = NETWORK.NET FILEI MATI[1] = TRIPS.MAT FILEI TURNPENI = TURNPEN.PEN FILEO NETO = LOADED.NET
FILEO PATHO[1] = HWY_PATHS.PTH ; set parameters and values for time and distance costs PARAMETERS COMBINE = EQUI GAP = 0.005 time_cost1 = 0.5 time_cost2 = 0.7 distance_cost1 = 0.2 distance_cost2 = 0.4 ; ----- SET CAPACITY and LINKCLASS PROCESS PHASE=LINKREAD CAPACITY = LI.CAPACITY * 1.0 ; set link classes for major roads IF (li.CLASS = 1-4) LINKCLASS = 1 ; set link classes for minor roads IF (li.CLASS = 5-10) LINKCLASS = 2 ; group railway links for exclusion from assignment IF (li.CLASS = 11 | li.CLASS = 12) ADDTOGROUP=1 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH=COST, PENI=1-2, ; include turn penalties, VOL[1]=MI.1.CAR, ; load car trips, VOL[2]=MI.1.TRUCKS, ; load truck trips, EXCLUDEGROUP=1, ; exclude rail links PATHO=1 NAME=COST_PATH INCLUDECOSTS=T ALLJ=T ; save path file ENDPROCESS PROCESS PHASE=ADJUST ; Define cost and delay functions function { tc[1]=t0*(1.0+0.15*((v/c)^8)) ; congested time function for major roads tc[2]=t0*(1.0+0.15*((v/c)^4)) ; congested time function for minor roads cost[1]=time*time_cost1+li.distance*distance_cost1 ; cost function for major roads cost[2]=time*time_cost2+li.distance*distance_cost2} ; cost function for minor roads ENDPROCESS ENDRUN
Highway example 4
/* EXAMPLE 4 This example script runs a junction constrained equilibrium assignment dumping the path file, final turn delays and the binary junction data file */ RUN PGM=HIGHWAY
FILEI NETI = NETWORK.NET FILEI MATI[1] = VEHICLETRIPS.MAT FILEI JUNCTIONI = JUNC_BASE.IND, period=60,set=1 FILEO NETO = LOADED.NET FILEO PATHO[1] = ROADPATHS.PTH FILEO TURNPENO = TURNDELAYS.DAT FILEO JUNCTIONO = TURNS.INT ; set convergence method and criteria PARAMETERS COMBINE = EQUI, GAP = 0.005, maxiters=99 PARAMETERS EQUITURNCOSTFAC=1 ; ----- SET CAPACITY and group links PROCESS PHASE=LINKREAD C = LI.CAP IF (LI.FUNC_CLASS = 1-2) LINKCLASS=1 IF (LI.FUNC_CLASS = 3-10) LINKCLASS=2 ENDPROCESS PROCESS PHASE=ILOOP PATHLOAD PATH = TIME, VOL[1]=MI.1.1, PATHO=1, NAME='assignment',ALLJ=T, INCLUDECOSTS=T,PENI=1 ENDPROCESS PROCESS PHASE=ADJUST function { tc[1]=t0*(1.0+0.15*((v/c)^8)) ; congested time function for major roads tc[2]=t0*(1.0+0.15*((v/c)^4)) ; congested time function for minor roads ENDPROCESS ENDRUN
Highway example 5
/* EXAMPLE 5 This script shows an example of both subarea assignment and subarea matrix extraction for multiple trip purposes. The subarea network is created with CUBE/VIPER POLYGON tools with the default renumbering of the network. */ RUN PGM=HIGHWAY NETI=DEMO.NET ; subarea network created with POLYGON tools in CUBE/VIPER FILEI SUBAREANETI=subarea1.net MATI=TRIPSBYPURPOSE.MAT FILEO NETO=Loaded_DEMO.NET FILEO SUBAREAMATO=submat1.mat NAME=HTW,WTH,HTO,OTH,NHB,TOTAL
PARAMETERS COMBINE=EQUI GAP=.0001 PHASE=LINKREAD LINKCLASS=LI.CLASS C=LI.CAPACITY ENDPHASE PHASE=ILOOP ; this PATHLOAD statement builds paths on TIME, assigns each trip purpose ; and the total trips to separate volume sets, ; extracts a subarea matrix for each trip purpose and the total trips PATHLOAD PATH=TIME,VOL[1]=mi.1.1,,VOL[2]=mi.1.2,VOL[3]=mi.1.3,VOL[4]=mi.1.4, VOL[5]=mi.1.5,VOL[6]=mi.1.6, SUBAREAMAT[1]=mi.1.1,SUBAREAMAT[2]=mi.1.2, SUBAREAMAT[3]=mi.1.3,SUBAREAMAT[4]=mi.1.4, SUBAREAMAT[5]=mi.1.5,SUBAREAMAT[6]=mi.1.6 ENDPHASE PHASE=ADJUST ; volume function V sets the volume to use for V/C in the delay function ; No delay functions (TC[#]=) are specified here so the default BPR ; formula is used for all link classes FUNCTION V=VOL[6] ; set volume to use in congested travel time functions ENDPHASE ENDRUN
Highway example 6
/* EXAMPLE 6 This script has two steps. In step 1 several examples of select link assignment are shown. In step two a MATRIX job is run to build trip end reports for the select link trip matrices created in step 1 */ ; Step 1 Select Link Assignment RUN PGM=HIGHWAY MATI=TRIPS.MAT NETI=DEMO.NET NETO=DEMOSelectLink.NET MATO = MATVOUT.MAT,mo=1-2,4 dec=2, combine=Y ; this is an example of an incremental assignment procedure ; the number of fractions defines the number of iterations ; at each iteration the listed fraction of the trip table is assigned COMBINE=SUM,FRACTIONS=0.1,0.1,0.1,0.1,0.1,0.1,0.1,0.05,0.05,0.05,0.05,0.0 5,0.05 ; Equilibrium assignment could be performed specifying COMBINE=EQUI ; or volume averaging by specifying COMBINE=AVE if desired PHASE=LINKREAD
LINKCLASS=LI.CLASS C=LI.CAPACITY ENDPHASE PHASE=ILOOP PATH=TIME,VOL[1]=mi.1.6, mw[1] = mi.1.6, selectlink = (L=1449-1495), vol[2] = mw[1] mw[2]=mi.1.6 /* this step says build paths based on time, assign trips from mi.1.6 to these paths and put them in Volume set 1 (V1_1 on the output network), put trips from mi.1.6 into working matrix 1 if they are on paths that use the selected links (L=), assign the trips in working matrix 1 (the select link trips) back to the time based paths and put them into Volume set 2 (V2_1 on the output network), and lastly put the total trips assigned from mi.1.6 into working matrix 2. Note that on the MATO line mo=1-2 will output the selected trip matrix (1) and the total trip matrix assigned (2) */ PATH=TIME,VOL[3]=mi.1.6, mw[4] = mi.1.6, selectlink = (L=1494-1423), vol[4]=mw[4] /* this step says build paths based on time, assign trips from mi.1.6 to these paths and put them in Volume set 3 (V3_1 on the output network), put trips from mi.1.6 into working matrix 4 if they are on paths that use the selected links (L=), assign the trips in working matrix 4 (the select link trips) back to the time based paths and put them into Volume set 4 (V4_1 on the output network). Note that on the MATO line mo=4 will output the selected trip matrix (4) for the links L=. Now you have 4 volume sets, but only want to calculate congested travel times based on the true total volumes on each link. This is why you need the function V=vol[1]. Note that V=vol[3] would give the same result as these two sets are the same. The V function is automatically executed during the adjust phase. */ ENDPHASE PHASE=ADJUST function { V=vol[1] } /* this function sets the volume for the capacity restraint to be the total volume. Without this statement, V is set to the sum of all volume sets which double counts volume when you have a select link volume set */ ENDPHASE ENDRUN ; Step 2 Extract and report select link trip ends RUN PGM=MATRIX ; note this example was for a 25 zone network
FILEI MATI=matvout.mat mw[1]=mi.1.1 array sum_mat = 25 array row_tot = 25 row_TOT[I] = rowsum(1) Jloop sum_mat[J] = sum_mat[J] + mw[1][J] endjloop IF (I=25) LOOP INDEX=1,25 PRINT FORM=10.0, LIST=INDEX,ROW_TOT[INDEX],SUM_MAT[INDEX], file =SelectTripEnds.txt ENDLOOP ENDIF ENDRUN
Highway example 7
/* EXAMPLE 7 This script is an example of using LINKIDARRAY to accumulate information about toll gate use from the paths into working matrices. In this example, the LINKIDARRAY uses li.TOLL. This network data field contains a value of 1-8 corresponding to one of the 8 toll bridges in the San Francisco Bay Area network. The output work matrices include: #1 is the travel time on the I-J path, #2 is the number of toll gates traversed on the path, #3 is the number of the last toll gate traversed on the path and #4-#8, include the 1st, 2nd, 3rd and 4th gate number traversed on the path if used. */ RUN PGM=HIGHWAY FILEI NETI = SF_BAY_AREA.NET FILEO MATO[1] = test.mat, mo=1-8 PHASE=LINKREAD LW.TIM=LI.DISTANCE/LI.FFS * 60 If (li.USE=2,3) ADDTOGROUP=1 ; don't use HOV facilities, ; they by pass tolls ENDPHASE PHASE=ILOOP PATHLOAD PATH = LW.TIM, EXCLUDEGROUP=1, MW[1] = PATHTRACE(LW.TIM), LINKIDARRAY=li.TOLL, LINKIDCNTMW=2 LINKIDLASTUSE=3 LINKIDMW=4-8 ENDPHASE ENDRUN
Highway example 8
/* Example 8 Example of using TOLLMATI to incorporate closed system tolls into the pathbuilding process. In this example, the paths are built on COST and the COST function will include any gate to gate tolls traversed on a path. */ RUN PGM=HIGHWAY FILEI TOLLMATI[1] = "TOLL.DBF", ENTRYGATE=ON_RAMP, EXITGATE=OFF_RAMP, TOLLS=COST_CAR,COST_TRUCK, NETIENTRY=ONRAMP, NETIEXIT=OFFRAMP, NETITOLLROAD=TOLLROAD FILEI NETI = "BASE.NET" FILEI TURNPENI = "PROHIBIT1.PEN" FILEI MATI[1] = "PKHOURTRIPS.MAT" FILEO TURNVOLO[1] = "TURNS.DBF", FORMAT=DBF FILEO NETO = "TOLLLOAD.NET" FILEO PATHO[1] = "TOLLPATH.PTH" FILEO JUNCTIONO = "JUNCTION1.DAT" FILEO MATO[1] = "TOLLSKIM.MAT", MO=1-5,99 NAME=PATHCOST,COST,PATHTOLL,TIME,VEHTOLLS,LOADS PAR MAXITERS=20 TURNS N=1-9999 PROCESS PHASE=LINKREAD C = LI.CAP IF (LI.FUNC_CLASS = 1-2) LW.COEF=0.15 LW.EXPO=8.00 ELSE LW.COEF=0.15 LW.EXPO=4.00 ENDIF ENDPROCESS PROCESS PHASE=ILOOP ; ----------------------------------------------------------; trips to load MW[99]=MI.1.1+MI.1.2 ; ----------------------------------------------------------; Assign WITH TOLL COST CONSIDERED PATHLOAD PATH=COST, VOL[1]=MW[99],
PENI=1 TOLLMATI=1,1, TOLLFACTOR=2.0, ; toll factor is in min/toll units, ; here 2min/$ (implies VOT=$30/hr) MW[1]=PATHCOST, NOACCESS=0, MW[2]=PATHTRACE(COST,1), NOACCESS=0, MW[3]=PATHTOLL, MW[4]=PATHTRACE(TIME,1),NOACCESS=0, MW[5]=mw[3]*mw[99] ; cross trips with tolls ENDPROCESS PROCESS PHASE=ADJUST function { tc=t0*(1.0+LW.COEF*((v/c)^LW.EXPO)) ; congested time function for major roads } ENDPHASE ENDRUN
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
Intersection Modeling Introduction to intersection modeling
Introduction to intersection modeling

This section provides an overview to intersection modeling. Topics include: Why use intersection modeling? How the intersection models work Limitations of intersection modeling Cube Voyager intersection modelling and other programs
Why use intersection modeling?

In a traditional capacity restrained transport planning model, the effects of congestion are represented by link cost functions that assign costs to each link as a monotonic non-decreasing function of the flow on that link. This form of model has a unique Wardrop equilibrium solution. Furthermore, the Frank-Wolff algorithm (invoked by default in Cube Voyager) gives us a reasonably good solution algorithm. Thus later in the planning process, when we wish to compare schemes, we can be sure that, provided both models have been run to an adequate level of convergence, we have stable comparable results. Furthermore we can achieve good convergence in reasonable time. Models with separable costs and monotonic nondecreasing cost functions have been very successful in modelling interurban travel. They have been applied to most kinds of geographic region and most kinds of planning decision. However, in congested urban environments, it can easily be observed that most of the delay arises from the conflicts between streams at intersections. In such a situation, it may be necessary to use nonseparable cost functions to achieve adequate verisimilitude in the sensitivities of the costs to the flows. Furthermore, if the policy responses being evaluated include traffic management
measures (for example, changing the form of control at key intersections) it must be possible to represent the proposals in the model.
How the intersection models work

Cube Voyager intersection modelling occurs during the ADJUST phase of a capacity restrained assignment. Data from a file of Junction Descriptions is read to determine the exact model form for each modelled node. When the costs arising from a flow pattern are required, the flow pattern is passed to the intersection model. The model will allocate the turning movements into lane groups, with each lane group having a capacity. Note that the capacity of a lane group will be reduced by any conflicting flows through the intersection. A delay function is applied to calculate the average delay per vehicle for vehicles in the lane group. These calculated delays are then applied as turn penalties in the next path build.
Limitations of intersection modeling

As noted above, intersection modelling tends to make the overall network model less stable. Consequently the assignment may take many more iterations to converge. Indeed, using the default method of combination, the model may never reach adequate levels of convergence. If necessary, you can change to using COMBINE=AVE to guarantee eventual convergence.
NOTE: A global minimum capacity of 1 vehicle (or PCU) per hour is
now enforced. A PCU is similar to a vehicle but it is adjusted for vehicle length, so a car counts 1, a bus counts 2. Trucks vary between 1.5 (light van) and 2.5 (tractor-trailer).
Cube Voyager intersection modelling and other programs

This chapter describes only those junction description keywords that are directly relevant to Cube Voyager intersection modelling. However there are several other keywords permitted in an intersection description. Some of these extra keywords are used by
Cube graphics to assist in editing and display of intersections. Some of these extra keywords are used to preserve data that is required or used by Cube Dynasim.
Intersection Modeling Control statements
Control statements
A junction file contains a sequence of statements, of which at most one is a UNITS statement, and the remainder are JUNCTION statements. This section describes: JUNCTION UNITS
JUNCTION
Each JUNCTION statement describes the control of some particular intersection in the network. It follows the usual syntax for Cube Voyager script statements. Comments, also following the usual Cube Voyager script syntax, are also allowed in the file.
JUNCTION statement keyword overview
Priority Saturation v v v v Roundabout Gap acceptance v v Roundabout Empirical 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 v v
Priority Geometric v v
Twoway Stop v v
JUNCTION statement keyword overview (continued)

Priority Saturation Roundabout Gap acceptance Roundabout Empirical v v Signals Geometric v Signals Saturation
Keyword CAPACITYINTERCEPT CAPACITYSLOPE CENTRALBUSINESSDISTRICT CENTRALRESERVATIONWIDTH CRITICALGAP CYCLETIME ENTRYANGLE ENTRYRADIUS ENTRYWIDTH ESTIMATEDDELAY EXCLUSIVELANES EXITONLY FLARELENGTH FOLLOWUPTIME FOURLANEMAJOR FREEFLOWCAP GRADE INITIALQUEUE INSCRIBEDDIAMETER LANEADJUST |R| |R| |K?|
Allway Stop
Priority Geometric
Twoway Stop
|KR|
|R| |KR| |R| |R| |R| |R| |I| |?| |R| |R| |K?| |R| |R| |R| |R| |K?|
v v x v
v v v v
v v v x v
v v v v x v
v v v v v v x v v
v v v v x v v v
v v v v x v
v v v v v v v
JUNCTION statement keyword overview (continued)

Priority Saturation v v v v v v v Roundabout Gap acceptance v v v v v Roundabout Empirical v v v v v Signals Geometric v v v v v v v v v Signals Saturation v v v v v v v v v
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 v v v v v v
Priority Geometric v v v v v minor only v v v
Twoway Stop v v v v minor only v v v
See the individual topics for descriptions of each keyword.
UNITS
Defines units of measurement for junction geometry. UNITS LENGTH
This statement defines whether the lengths used to define junction geometry are measured in feet or meters. The value of the Length may be either feet or meters (case insensitive). At most one UNITS statement may appear in a junction file. If no UNITS statement is found, measurements will be taken to be in meters. The keywords, in the Junction statement, that have units of length are: AverageLaneWidth, ApproachWidth, EntryWidth, EntryRadius, FlareLength, InscribedDiameter, Width, Visibility, MajorRoadWidth and CentralReservationWidth.
Example
UNITS LENGTH=FEET UNITS LENGTH=METERS
Intersection Modeling Common keywords
Common keywords
This section describes common keywords, applicable to multiple intersection types: APPROACH APPROACH1 ENABLE ESTIMATEDDELAY EXITONLY INITIALQUEUE MINIMUMCAPACITY MOVEMENT NODE RANDOMNESS TYPE
APPROACH
The APPROACH keyword takes a list of integers as its value. It has two functions within the junction description:
1. It begins a sequence of keywords which describe the specified
approach. This sequence continues until the next occurrence of Node, Type, LaneAdjust, CentralBusinessDistrict, CycleTime, Phase, MajorRoadWidth, CentralReservationWidth, StorageSpace, FourLaneMajor, Approach1, Approach, or the end of the JUNCTION statement.
2. It describes how neighbors of the modeled node are grouped
into approaches. The value of the keyword is a list of node numbers of nodes adjacent to the node being modeled. The grouping of neighboring nodes into a single approach may be necessary, for example, because Cube Voyager can only model
three- or four-legged intersections (although, at roundabouts, this restriction may be overcome by modeling the circulating section explicitly); because some of the neighbors are fictional (for example, zone centroid connectors); or because the two lanes of a road are represented by individual links. Every node, which is a neighbor of the modeled node, must appear in exactly one Approach clause. Cube Voyager requires that the legs of a junction can be assigned a clockwise ordering by using the coordinates of the nodes involved. Any grouping of links into legs must not invalidate the ordering. For example, in the diagram below, a is a modeled node. Any valid approach which includes both nodes b and d must also include node c.
APPROACH1
Every junction description must contain exactly one occurrence of the integer-valued keyword APPROACH1. Its value is the node number of a node adjacent to the modeled node, Node. The approach containing the specified node, is taken to be the first approach and the other approaches are numbered in relation to it. By default, the approaches are numbered in anti-clockwise order, but if LEFTDRIVE = y is in force, the approaches are numbered in clockwise order. At two-way stop-controlled and priority (two-way yield-controlled) intersections, the first and third approaches are major and the second and fourth (if any) approach are minor. At three-legged intersections, the value of APPROACH1 determines which movements are available from each approach:
LeftDrive = n First Approach Second Approach Third Approach Through Right Right Left Left Through LeftDrive = y Through Left Left Right Right Through
At other modeled intersections, the choice of APPROACH1 is arbitrary with no modeling consequences.
ENABLE
Every junction description may contain at most one occurrence of the logical-valued keyword ENABLE. If it has the value false, Cube Voyager will ignore the entire junction description (that is, no intersection modeling will occur at the node).
ENABLE is a quick way of turning modeling on and off at a
particular node from within the junction file during model development. Modeling can also be turned on and off in the Cube Voyager Highway script file using the N clause of the FILEI JUNCTIONI command.
ESTIMATEDDELAY
NOTE: Keywords are case insensitive. Capitalizing as EstimatedDelay might improve readability.
This real valued keyword specifies the delays, in minutes per vehicle, to be used during the first PATHLOAD command to be executed. This occurs prior to the first Adjust phase, so no calculated values will be available yet. Once an Adjust phase has been executed, calculated values will replace these initial estimates. By default, a value of 0.0 minutes is used. However, in urban areas, this is a very poor estimate and it is very desirable that better values be supplied. An approachs ESTIMATEDDELAY value is analogous to a links initial travel time. On the assignments first iteration, no volumes exist yet to use for junction-delay calculations. During the first iteration, this user-specified value provides an initial estimate of the movement delay during path building.
EXITONLY
NOTE: Keywords are case-insensitive. Capitalizing as ExitOnly might
improve readability. For any approach, EXITONLY=y indicates that the leg is not an approach; it is an exit only. No other keywords, except EXITLANES, may be coded for the approach.
The coding of EXITONLY must agree with the network (that is, the exit only approach must correspond to a set of one-way links leading away from the modeled intersection).
INITIALQUEUE
NOTE: Keywords are case insensitive. Capitalizing as InitialQueue might improve readability.
This is the number of vehicles (pcu) that are waiting to make the specified movement from the specified approach at the beginning of the model period. It defaults to zero.
INITIALQUEUE is the queue at the start of the modeled period. INITIALQUEUE generates additional delay after Cube Voyager
assigns flows and calculates delay because the vehicles arriving during the assignment must wait for the queue in front of them to discharge before they reach the stop line (or give-way line). Consequently, if there is no assignment (that is, just path building for skimming), INITIALQUEUE has no effect. Note that the initial queues discharge rate is not a constant; the discharge rate depends on the junctions conflicting flows. Rather than being additional time added to the delay at the end of the process, INITIALQUEUE is more like additional demand added to the assigned demand prior to junction calculations. However, the delay to the vehicles in the initial queue is not part of the results. The results only include the delay that these initially queueing vehicles cause to the vehicles that arrive during the modeled period.
MINIMUMCAPACITY
The MINIMUMCAPACITY keyword takes a positive value in vehicles per hour as its argument. It is coded by approach. If no value is coded, a default value of one vehicle per hour is applied. If the calculated capacity for any stream from an approach is less than the minimum capacity value for that approach, the minimum capacity will be used instead of the calculated value. This substitution occurs before any delay calculations are started.
The minimum capacity is most likely to apply when a movement is very lightly trafficked but is very heavily opposed. In this circumstance, the delay for the lightly trafficked movement will be close to 60/MinimumCapacity (that is, the default value leads to delays being estimated as an hour). The default minimum capacity of one vehicle per hour is sufficient to prevent division by zero errors from crashing program execution but there are two arguments in favor of applying a higher value:
1. Modeling expediency: If a minimum capacity of one vehicle per
hour results in a predicted delay of the order of an hour, trips will be diverted away from that turn during subsequent iterations. So long as the turn has low traffic there is little reason for the turn model to allocate capacity to that movement (especially at adaptive signal models where the signal optimizer will be trying to allocate the available green time where the flow is heaviest). Thus a positive feedback may occur between having low traffic on the turn and having high delay on the turn.
2. Driver behavior: If conditions are very congested, drivers will no
longer wait for an appropriate gap in the opposing stream. Eventually, they will just force their way into a smaller gap. This is especially true when the opposing stream is a slow moving queue.
MOVEMENT
The MOVEMENT keyword takes one of three case-insensitive values: Left Right Through
Each occurrence begins a sequence of keywords which describe the specified movement from the current approach. The sequence continues until the next occurrence of APPROACHWIDTH, AVERAGELANEWIDTH, BUSBLOCKAGE, CAPACITYINTERCEPT,
CAPACITYSLOPE, ENTRYANGLE, ENTRYRADIUS, ENTRYWIDTH, EXITONLY, FLARELENGTH, GRADE, INSCRIBEDDIAMETER, MINIMUMCAPACITY, MOVEMENT, NUMBEROFLANES, PARKINGMANEUVERS, RANDOMNESS, SINGLELANE, TURNCHANNELIZED, FREEFLOWCAP, or the end of the approach.
Care should be taken when coding CRITICALGAP and FOLLOWUPTIME which can occur as keywords at both the approach and movement levels. When coding gap-acceptance roundabouts, these two keywords should appear within each approach, before any movements for that approach are described. When coding two-way stop-controlled intersections, it will not usually be necessary to code CRITICALGAP or FOLLOWUPTIME, but if they are coded they must be coded by movement.
NODE
Every junction description must contain exactly one occurrence of the integer-valued keyword NODE. Its value is the node number of the junction to be modeled.
RANDOMNESS
RANDOMNESS is a real-valued keyword which specifies how random the service times are with respect to the arrival times. Its value must satisfy the inequality 0.0 < RANDOMNESS <= 1.0. At geometrically modeled signals, the platoon ratio is estimated as 2(1.0 - RANDOMNESS)
By default, RANDOMNESS is 0.55 for signalized intersections and 1.0 for unsignalized intersections. These values are appropriate for isolated junctions (that is, arrivals are random). The lower value for signals reflects that even if arrivals at a signal are random, the service times depend on whether the arrival was at a green signal aspect or a red one. However, in urban areas where there are signal linkage effects, the appropriate RANDOMNESS values are reduced. RANDOMNESS values of 0.1 or 0.2 are appropriate for signals in advanced traffic
management systems (for example, SCOOT, SCATS, OPAC) or in offline signal plans at the time that they are installed. Unsignalized intersections in this region should have RANDOMNESS values of the order 0.3 or 0.4. Offline signal plans are generally not completely up to date so they are usually more random than ATMS. Consequently, in areas where offline signal plans operate RANDOMNESS values for signals should be 0.3 or 0.4; values of 0.6 to 0.8 are appropriate for unsignalized intersections in these areas. When using dummy links to model internal parts of a signal (such as modelling a five-armed signal as two nodes) synchronization across the dummy link is perfect. Therefore, code very low values of randomness, such as 0.01, for the relevant approaches.
TYPE
Every junction description must contain exactly one occurrence of the keyword TYPE. It determines the type of junction to be modeled. Its value should be taken from the following list: Roundabout Priority FixedTimeSignal Adaptive Signal TwoWayStop AllWayStop
The keywords are case insensitive; the capitalization in the list above is merely to improve readability. Note that the type field only distinguishes between different types of intersection on the ground. When Cube Voyager offers more than one methodology for modeling a particular kind of junction control, other keywords will be used to distinguish between them:
The presence or absence of CRITICALGAP and FOLLOWUPTIME (by approach) distinguishes between gap-acceptance and empirical roundabout modeling The presence or absence of MAJORROADWIDTH distinguishes whether a priority junction uses geometric modeling or measured saturation flows The value of LANEADJUST distinguishes whether a fixed time signal uses geometric modeling or measured saturation flows
The exception to the above rule is signals when there are several layers of choice of modeling methodology. When observed baseyear signal settings are available, use TYPE=FixedTimeSignal to perform delay calculations for those settings. However, given a feasible signal setting and a set of constraints, Cube Voyager can optimize the settings for the forecast flows. This facility is invoked using TYPE=AdaptiveSignal. (Note that when forecasting future years, adaptive modeling is always recommended; even if the signal controller is fixed time, some traffic engineer will reset the signals every few years.) The next level of modeling methodology chooses between calculating capacities using supplied saturation flows or calculating them using the methodology described in HCM 2000, Chapter 16. The HCM methodology is invoked using the keyword LANEADJUST. Both methodologies may be invoked either using supplied settings or adaptive green time calculations. Note that the HCM methodology can model semi-actuated signal controllers. Giving the keyword UnitExtension to a positive value for some approach invokes this model. The issues of adaptive settings (that is, future or base year) and actuated controllers (that is, hardware in the field) are independent of each other. When HCM capacity calculations are executed, by default Cube Voyager also applies the HCM delay calculations. However, for all other models, a delay equation formulated by Ian Catling is used. If you code DELAYEQUATION=Catling you can force the use of Catlings delay formulation at an HCM signals.
Note that the type of control called a priority junction in the U.K. (where they are very common) would be called a two-way yieldcontrolled intersection in the U.S. (where stop-controlled intersections are the norm).
Intersection Modeling Signal-controlled intersections
Signal-controlled intersections
This section describes signal controls. Topics include: Overview of signals Generic keywords Geometric keywords Geometric signals example Saturation flow signals example
Overview of signals
Signalized intersections are controlled by sets of traffic lights. At any given time, vehicles making a particular movement through the intersection will see a particular signal aspect: In the U.K., red, green, amber, red amber, flashing amber. In the U.S., green, yellow, red, green.
Modelers reclassify the aspect into effective green (when the traffic can go) and effective red (when the traffic stops). Note that effective green begins and ends later than actual green (due to reaction times). A set of signal aspects for all movements through an intersection is called a phase. Note that the total duration of all the phases should be significantly less than the duration of the signal cycle. The difference is primarily due to two factors: lost time while the signals are changing phase and pedestrian phases. Cube Voyager offers two ways of modeling the capacity of signals. There is a detailed model of junction geometry, which has been calibrated to traffic conditions in the U.S., and there is a model which requires saturation flows to be estimated or measured externally, which has been calibrated to traffic conditions in the U.K. The detailed model also imposes more constraints on the allowed signal phasing than the saturation flow only model.
A left turn (right turn when LEFTDRIVE=T) which sees a green phase will either be protected (that is, no opposing flow is running) or permitted (that is, the vehicles must give way to some oncoming traffic). Both methodologies can model both permitted and protected phases. Cube Voyager does not offer any model of right turn on red although this is allowed in many areas of the U.S. (The LEFTDRIVE=T equivalent, left turn on red, is not permitted in the U.K.) This is best handled by introducing a dummy link into the network, allowing the right-turners to bypass the signal control, and omitting some lane(s) from the definition of the approach.
Generic keywords
This section describes generic keywords used for signals: CANSHARELEFT CANSHARERIGHT CYCLETIME EXCLUSIVELANES LANEADJUST PHASE and ACTUALGREEN PHASES SATFLOWPERLANE SINGLELANE
CANSHARELEFT
NOTE: Keywords are case insensitive. Capitalizing as CanShareLeft
might improve readability. This keyword specifies that there is a shared lane to the left of the exclusive lanes for this movement (that is, the movement can share with the movement to its left). Note that this keyword does not
mean can share with left turners unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. If a movement has CANSHARELEFT = T coded, then there must be a movement to this movements left and the movement to this movements left must have CANSHARERIGHT = T coded. If SINGLELANE = T then CANSHARELEFT should not be coded.
CANSHARERIGHT
NOTE: Keywords are case insensitive. Capitalizing as CanShareRight
might improve readability. This keyword specifies that there is a shared lane to the right of the exclusive lanes for this movement (that is, the movement can share with the movement to its right). Note that this keyword does not mean can share with right turners unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. If a movement has CANSHARERIGHT = T coded, then there must be a movement to this movements right, and the movement to this movements right must have CANSHARELEFT = T coded. If SINGLELANE = T then CANSHARERIGHT should not be coded.
CYCLETIME
NOTE: Keywords are case insensitive. Capitalizing as CycleTime
might improve readability. This real-valued keyword is required for all signals. Its value is the length of the signal cycle in seconds. The cycle time must be strictly greater than the sum of all the coded green times.
At actuated signals, the CYCLETIME value is taken to be part of the example feasible solution and the subkeywords MAXIMUM and MINIMUM may be used to supply constraints. For example: Actual Cycle = 120, Minimum = 60, Maximimum=180, If no constraints are placed on the cycle time at an adaptively modeled signal, the constraints will be deduced from the constraints on the individual green times.
EXCLUSIVELANES
NOTE: Keywords are case insensitive. Capitalizing as ExclusiveLanes
might improve readability. This integer-valued keyword gives the number of lanes, on the specified approach, which are reserved for the exclusive use of vehicles making the specified movement. If SINGLELANE = T, then EXCLUSIVELANES should not be coded.
LANEADJUST
NOTE: Keywords are case insensitive. Capitalizing as LaneAdjust might improve readability.
Set LANEADJUST to Y at a signal to invoke the HCM2000 capacity calculations. Set LANEADJUST to N at a signal if you are supplying saturation flows.
PHASE and ACTUALGREEN

These keywords occur in pairs; every occurrence of the integervalued keyword, PHASE must be followed by a single occurrence of the real-valued keyword ACTUALGREEN. There should be one such pair for each phase of the signals during which vehicles move (that is, all-red and/or pedestrian phases should not be coded).
The values of the PHASE keyword should form a continuous sequence, starting at one and increasing, without gaps, until the number of phases is reached. Every phase must be mentioned in a PHASE keyword for some movement at the intersection. The value of the ACTUALGREEN keyword is the duration, in seconds, of the effective green-time associated with the phase. The effective green time is the period during which vehicles move across the stop line. It starts shortly after the signals change to green (because the vehicle drivers must react to the change in signal aspect) and continues through the following red/yellow. If the signal is being modeled adaptively, then the keywords maximum (required) and minimum (optional) may be used to specify constraints, and the coded value of ACTUALGREEN is taken to be part of the example feasible solution. If no minimum is applied, Cube Voyager may remove the phase altogether (that is, set green-time to zero).
PHASES
The keyword PHASES is integer-valued but, conceptually, it consist of either one phase number (that is, digit) or of two phase numbers (that is, two digits). The vehicles making the movement see a green signal aspect when the specified phase(s) is/are running and red otherwise. Note that the (node-level) keyword PHASE is used to define phases and the (movement-level) keyword PHASES associates movements with the defined phases. At geometrically specified signals, then any two-digit phase specifications must specify contiguous phases. No such restriction is required when saturation flows are coded.
SATFLOWPERLANE
NOTE: Keywords are case insensitive. Capitalizing as SatFlowPerLane might improve readability.
This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. Saturation flows at signals are the flows that would be observed if the movement had a continuous green all other movements had no flow and no green. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly, except that no signal aspects are involved.
SINGLELANE
NOTE: Keywords are case-insensitive. Capitalizing as SingleLane might improve readability.
The logical-valued keyword is used to indicate that an approach consists of a single lane. It is applicable to many junction types:
Junction type Signal-controlled intersection All-way stop-controlled intersection Two-way stop-controlled intersection Geometric Data Saturation Flows Use SINGLELANE may be coded SINGLELANE may be coded SINGLELANE may not be coded; code NUMBEROFLANES = 1 SINGLELANE may be coded for minor road Use FOURLANEMAJOR to describe major road Geometric Data SINGLELANE may be coded for minor arms Major road width in meters, not lanes SINGLELANE may be coded SINGLELANE may not be coded SINGLELANE may not be coded
Priority intersection (two-way yieldcontrolled intersection)
Saturation Flows Roundabout Empirical Gap Acceptance
Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES, CANSHARERIGHT, or CANSHARELEFT on that approach.
At two-way stop-controlled intersections and priority junctions, a minor arm that does not have SINGLELANE = Y explicitly coded, has two lanes.
Geometric keywords
This section describes geometric keywords: AVERAGELANEWIDTH CONFLICTINGBIKE BUSBLOCKAGE CENTRALBUSINESSDISTRICT DELAYEQUATION EXITLANES GRADE PARKINGMANEUVERS PEDESTRIANFLOW PEDESTRIANPHASE PHASES UNITEXTENSION
AVERAGELANEWIDTH
NOTE: Keywords are case insensitive. Capitalizing as AverageLaneWidth might improve readability.
This real-valued keyword describes the mean lane width, in meters or feet, of an approach to a geometrically modeled signalized junction. If no value is provided, a default of 3.6m is used. The average lane width must be in the range from 2.4m to 4.8m. If the value falls outside this range, the approach should be recoded to have more or fewer lanes, as appropriate.
CONFLICTINGBIKE
NOTE: Keywords are case insensitive. Capitalizing as ConflictingBike might improve readability.
The flow of bicycles in from the curb-side lane in units of bicycles per hour. Bicycle traffic which weaves with turning traffic in advance of the stop line should be excluded from this value, because these bicycles do not interact with the other vehicles while they are still within the intersection. The diagram below illustrates the relevant bicycle flow for right hand rule of the road. In the diagram, the crossed box is the bicycle conflict zone where right turning traffic may be impeded by any bicycles crossing the intersection. The CONFLICTINGBIKE is the flow of bicycles through this region.
BUSBLOCKAGE
NOTE: Keywords are case insensitive. Capitalizing as BusBlockage
might improve readability. The real values supplied to this keyword are number of buses stopping per hour. The first element refers to the normal curb side of the road; the second refers to the other side of the road (for example, if there is a tram line in the center of the road or there is a
bus stop on the offside of a one-way street). Only buses stopping within 75 meters (246 feet) of the stop line (either upstream or downstream) should be included. This keyword is only applicable at geometrically modeled signals.
CENTRALBUSINESSDISTRICT
NOTE: Keywords are case insensitive. Capitalizing as CentralBusinessDistrict might improve readability. You can also use
the abbreviation, CBD.

CENTRALBUSINESSDISTRICT is a logical-valued keyword which may
be applied at geometrically-modeled fixed-time signals. Coding

CENTRALBUSINESSDISTRICT=Y causes all calculated capacities to be
90% of the value that would be obtained otherwise.
DELAYEQUATION
Selects the delay modeling methodology applied to the capacities calculated by the HCM2000 signal capacity modeling methodology. The keyword accepts the values HCM or Catling (case-insensitive). By default, The HCM delay equations are invoked.
EXITLANES
The number of lanes traveling away from the modeled intersection. This key may occur on the same arm as the EXITONLY keyword but is invalid for a one-way link that travels towards the intersection. Cube Voyager only uses this value for pedestrian and bicycle modeling.
NOTE: If exit lanes are omitted from an arm that pedestrians cross,
the capacity of movements entering the arm may be reduced significantly.
GRADE
The real-valued keyword GRADE describes the grade, expressed as a percentage, of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. It is a signed value; negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. By default the approach is assumed to be flat (GRADE = 0). The models have been calibrated for grades the range -6% to +11%, but more extreme grades do occur. For example the maximum grade in San Francisco is about 31%.
PARKINGMANEUVERS
NOTE: Keywords are case insensitive. Capitalizing as ParkingManeuvers might improve readability.
The real values supplied to this keyword are number of maneuvers per hour. The first element refers to the normal curb side of the road; the second refers to the other side of the road (that is, if there is parking in a central reservation or on the offside of a one way street). Only parking within 80 meters of the stop line should be included By default, parking is not allowed. Coding PARKINGMANUEVERS = 0 means that parking is allowed, but it is extremely rare. This keyword is only applicable at geometrically modeled signals.
PEDESTRIANFLOW
The number of pedestrians crossing the approach per hour. Note that this is a two-way flow.
PEDESTRIANPHASE
The keyword PEDESTRIANPHASE is integer-valued but, conceptually, it consist of either one phase number (that is, digit) or of two phase numbers (that is, two digits). In this respect, it is like
the keyword PHASES. The phases mentioned are the phases when pedestrians crossing the approach are given permission to use the crosswalk. The symbols displayed to the pedestrians vary by country, for example in the U.S. the word WALK or an icon of a man walking is displayed in white whereas in the U.K. an icon of a man walking is displayed in green. If using a two-digit number, the two phases must be adjacent.
PHASES
The keyword PHASES is integer-valued but, conceptually, it consist of either one phase number (that is, one digit) or of two phase numbers (that is, two digits). The vehicles making the movement see a green signal aspect when the specified phase(s) is/are running and red otherwise. Note that the (node-level) keyword PHASE is used to define phases and the (movement-level) keyword PHASES associates movements with the defined phases. At geometrically specified signals, any two-digit phase specifications must specify contiguous phases. No such restriction is required when coding saturation flows.
UNITEXTENSION
The minimum gap, in seconds, between successive vehicles moving on a traffic-actuated approach to a signalized intersection that will cause the signal controller to terminate the green display.
Geometric signals example

Cube Voyager does not contain a model for right turn on red. The right filter phase coded below might be used as a proxy for RTOR when the right turns are heavy.
Junction, Node = 276, laneadjust=t, Type = FixedTimeSignal,
Approach1 = 291, CycleTime = 90, Phase = 1, ActualGreen = 59, Phase = 2, ActualGreen = 5, Phase = 3, ActualGreen = 11, Approach = 291, AverageLaneWidth = 3.6, minimumcapacity=50, Movement = Left, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 1, Movement = Through, EstimatedDelay = 0.1, ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 12, Approach = 264, AverageLaneWidth = 3.6, minimumcapacity=50, Movement = Left, EstimatedDelay = 0.3, ExclusiveLanes = 1, Phases = 3, Movement = Through, EstimatedDelay = 0.3, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.3, ExclusiveLanes = 1, Phases = 32, Approach = 267, AverageLaneWidth = 3.6, minimumcapacity=50, Movement = Left, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 1, Movement = Through,
EstimatedDelay = 0.1, ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.2, Phases = 12, Approach = 306, AverageLaneWidth = 3.6, Movement = Left, EstimatedDelay = 0.2, ExclusiveLanes = 1, Phases = 3, Movement = Through, EstimatedDelay = 0.2, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.2, ExclusiveLanes = 1, Phases = 32
Saturation flow signals example

This example illustrates the coding of fixed-time signals:
Junction, Node = 276, Type = FixedTimeSignal, Approach1 = 291, CycleTime = 90, Phase = 1, ActualGreen = 59, Phase = 2, ActualGreen = 5, Phase = 3, ActualGreen = 11, Approach = 291, Movement = Left, CanShareRight=y, EstimatedDelay = 0.1, Phases = 1, Movement = Through, CanShareLeft=y, EstimatedDelay = 0.1,
ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.1, Phases = 2, Approach = 264, Movement = Left, EstimatedDelay = 0.3, CanShareRight=y, Phases = 3, Movement = Through, EstimatedDelay = 0.3, CanShareLeft=y, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.3, ExclusiveLanes = 1, Phases = 23, Approach = 267, Movement = Left, CanShareRight=y, EstimatedDelay = 0.1, Phases = 1, Movement = Through, CanShareLeft=y, EstimatedDelay = 0.1, ExclusiveLanes = 1, Phases = 1, Movement = Right, ExclusiveLanes = 1, EstimatedDelay = 0.2, Phases = 2, Approach = 306, Movement = Left, EstimatedDelay = 0.2, CanShareRight=y, Phases = 3, Movement = Through, EstimatedDelay = 0.2, CanShareLeft=y, Phases = 3, ExclusiveLanes = 1, Movement = Right, EstimatedDelay = 0.2,
ExclusiveLanes = 1, Phases = 23
Intersection Modeling Two-way stop-controlled intersections
Two-way stop-controlled intersections

This section describes two-way stop-controlled intersections. Topics include: Overview Keywords Example
Overview
This control is an unsignalized intersection between a major road and a minor road. The minor road approach (at a T), or approaches (at a crossroads) have stop signs. Traffic on the minor road must stop, before entering the intersection, even if there is no major road traffic visible. There is a hierarchy of flows, illustrated below, in which lower rank flows must give way to all higher rank streams.
The capacity model, which has been implemented in Cube Voyager, is a gap-acceptance model that has been calibrated against traffic conditions in the USA. Users in other countries may need to adjust the base critical gap and base follow up time to reflect local conditions. If there is a central reservation, or there are islands, between the lanes of the major road, minor road traffic, which crosses the major road, may do so in two stages. First the vehicle crosses to the central reservation; then it completes its movement through the intersection. This situation is enabled when a non-zero value of storage space is coded. The value is the number of vehicles which can wait in the center of the major road without obstructing major road flows.
Keywords
This section describes the keywords for two-way stop-controlled intersections: CRITICALGAP FLARESTORAGE FOLLOWUPTIME FOURLANEMAJOR FREEFLOWCAP GRADE PEDESTRIANFLOW PEDESTRIANSPEED SINGLELANE STORAGESPACE TURNCHANNELIZED
CRITICALGAP
NOTE: Keywords are case insensitive. Capitalizing as CriticalGap
might improve readability. The critical gap, in seconds, is one of the parameters of any gapacceptance capacity model. At two-way stop-controlled intersections, it is applicable by movement. It is defined as the minimum time interval in a higher priority stream that allows intersection entry for one vehicle. Note that the coded value is the base critical gap. It is modified to allow for junction geometry. The default value depends on the movement:
Base critical gap (seconds)
Vehicle Movement Left turn from major Right turn from minor Through traffic on minor Left turn from minor Two-Lane Major Street 4.1 6.2 6.5 7.1 Four-Lane Major Street 4.1 6.9 6.5 7.5
Normally this value is allowed to default; only code when there are observations indicating site-specific driver behavior at the intersection
FLARESTORAGE
The number of vehicles that may queue in the flared region of a minor approach without disrupting the flowing or queueing of traffic in the main lane. By default this value is zero, that is, no or negligible flare.
FOLLOWUPTIME
NOTE: Keywords are case insensitive. Capitalizing as FollowUpTime might improve readability.
The follow-up time, in seconds, is one of the parameters of any gapacceptance capacity model. At two-way stop-controlled intersections, it is applicable by movement. It is defined as the time between the departure of one vehicle the next using the same gap in a higher priority stream, under a condition of continuous queuing on the entry. The default value depends on the movement:
Vehicle Movement Left turn from major Right turn from minor Through traffic on minor Left turn from minor Base Follow-Up Time (seconds) 2.2 3.3 4.0 3.5
Normally this value is allowed to default; only code when there are observations indicating site-specific driver behavior at the intersection
FOURLANEMAJOR
NOTE: Keywords are case insensitive. Capitalizing as FourLaneMajor might improve readability.
This logical-valued keyword determines the number of lanes on the major road of a two-way stop-controlled intersection. If FourLaneMajor = y is coded, then the major road has two lanes in each direction (total four); otherwise the major road has one lane in each direction (total 2).
FREEFLOWCAP
NOTE: Keywords are case insensitive. Capitalizing as FreeFlowCap
might improve readability. This value is only relevant for major approaches where FOURLANEMAJOR is false. It is the capacity for the unmodelled movements from the arm. By default, these movements have
infinite capacity, which, when combined with the capacity of the modelled turn, gives strange large capacities in the results. If you code a sensible value (such as 1800 vph), the resulting capacity will be reduced, but there will be a corresponding increase in delays.
GRADE
The real-valued keyword GRADE describes the grade, expressed as a percentage, of an approach to a geometrically modeled signals or a two-way stop-controlled intersection. It is a signed value; negative values indicate that the approach is downhill and positive values indicate that the approach is uphill. By default the approach is assumed to be flat (GRADE = 0). The models have been calibrated for grades the range -6% to +11%, but more extreme grades do occur. For example the maximum grade in San Francisco is about 31%.
PEDESTRIANFLOW
The number of pedestrian platoons crossing the approach per hour. Pedestrians may cross the road singly, or they may cross in groups, two or three abreast. Each such group counts as one pedestrian platoon. For more details of pedestrian platoons refer to Chapter 18 of HCM 2000, especially to Equation 18-18 and the surrounding text.
PEDESTRIANSPEED
The average speed at which pedestrians cross the approach in feet or meters per second. By default this value is 1.2 meters or, equivalently, 4 feet per second.
SINGLELANE
NOTE: Keywords are case insensitive. Capitalizing as SingleLane
might improve readability.
The logical-valued keyword is used to indicate that an approach consists of a single lane. It is applicable to many junction types:
Junction type Signals All-way stop-controlled intersection Two-way stop-controlled intersection Geometric Data Saturation Flows Use SINGLELANE may be coded SINGLELANE may be coded SINGLELANE may not be coded; code NUMBEROFLANES = 1 SINGLELANE may be coded for minor road Use FOURLANEMAJOR to describe major road Geometric Data SINGLELANE may be coded for minor arms Major road width in meters, not lanes SINGLELANE may be coded SINGLELANE may not be coded SINGLELANE may not be coded
Priority intersection (two-way yield-controlled intersection)
Saturation Flows Roundabout Empirical Gap Acceptance
Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES, CANSHARERIGHT, or CANSHARELEFT on that approach. At two-way stop-controlled intersections and priority junctions, a minor arm, which does not have SINGLELANE = Y explicitly coded, has two lanes.
STORAGESPACE
NOTE: Keywords are case insensitive. Capitalizing as StorageSpace
might improve readability.
This integer-valued keyword applies to two-way stop-controlled intersections. It is the number of vehicles (PCU) that can wait in the central reservation without impeding major road traffic. It does not matter whether the central reservation is curbed or striped (ghost islands).
TURNCHANNELIZED
NOTE: Keywords are case insensitive. Capitalizing as TurnChannelized might improve readability.
The turn referred to is the turn which follows the curb (by default, the right turn; when LEFTDRIVE = T, the left turn). The turn is said to be channelized if there is a triangular, curbed island separating the turners from the other movements on the approach. The effect of turn channelization is ensure that the turning flows do not act as conflicting flows during the calculation of capacities on other legs. Setting TURNCHANNELIZED to T for an approach indicates that the unopposed turn from that approach is channelized. By default, no turns are channelized.
Example
The example describes a two-way-stop-controlled intersection with two-lane majors, two-lane minors and a central reservation.
Junction Node = 9 Type = TwoWayStop Approach1 = 8, FourLaneMajor = y, StorageSpace = 3, Approach = 6, TurnChannelized = y, Approach = 7, Approach = 8, Approach = 5,
Intersection Modeling All-way-stop-controlled intersections
All-way-stop-controlled intersections
All-way-stop-controlled intersections are unsignalized intersections with stop signs at every approach. Cube Voyager offers a capacity model of all-way-stop-controlled intersections which has been calibrated against traffic conditions in the US. The models only variable is the number of lanes for each arm. The capacities reported by models of undersaturated all-way-stopcontrolled intersections can appear very large. However, the model is very nonlinear and, as the flows are increased, the capacities will decrease.
All-way-stop-controlled intersection keyword
Keyword NUMBEROFLANES |I| Description Number of lanes at an approach to an all-waystop-controlled intersection. Valid values are 1, 2, or 3.
NOTE: Keywords are case insensitive. Capitalizing as NumberOfLanes might improve readability. Example
The following example describes an all-way-stop-controlled intersection between a one-lane road and a two-lane road.
Junction Node Approach = 6 Approach = 7 Approach = 8 Approach = 5 = 9 Type = AllWayStop Approach1 = 8, NumberOfLanes = 1, NumberOfLanes = 2, NumberOfLanes = 1, NumberOfLanes = 2
Intersection Modeling Roundabouts
Roundabouts
This section describes roundabouts. Topics include: Overview of roundabouts Empirical roundabouts: Keywords Empirical roundabouts: Example Gap acceptance roundabouts: Keywords Gap-acceptance roundabouts: Example
Overview of roundabouts
Roundabouts are a form of unsignalized intersection in which traffic circulates around a one-way closed lane to travel from an approach to an exit. Traffic on an approach must give way to traffic which is already on the circulating section. There are no constraints on traffic leaving the roundabout. The circulating flow past an entry is the only flow which influences the capacity of that entry. The model builder, therefore, can always represent the circulating lane explicitly in the network, without compromising the modeling of the intersection. Individual roundabout models are placed at each entry. The approach characteristics of the actual roundabout entries remain unchanged. One of the circulating legs is exit only and the other circulating leg should be coded so that vehicles entering the roundabout from
that approach are not significantly constrained. This technique is particularly useful for modeling roundabouts with five or more legs.
Cube Voyager offers two ways to model roundabouts: Gap-acceptance model Each entry is characterized by a critical gap and a follow-up time. Empirical model Each entry is characterized by a capacity slope and a capacity intercept. You can calculate the slope and intercept outside of Cube Voyager, or you can supply geometric data and let Cube Voyager calculate the slope and intercept using formulas calibrated in the UK. Worldwide experience with roundabouts and roundabout models leads to the following conclusions: When a well calibrated empirical model exists, it should be used in preference to a gap acceptance model However, the calibration of relationships between geometry, on one hand, and slope and intercept, on the other, requires very large amounts of data The number of roundabouts in the US is not yet sufficiently great to allow calibration of a US empirical model Even when general countrywide empirical relationships exist, it may be necessary to fine tune the slope and intercept for local conditions
When no general countrywide empirical relationships exist, it is better to use a gap acceptance model
The Highway Capacity Manual (HCM 2000) indicates appropriate parameter ranges for a single-lane roundabout entry in the US.
Empirical roundabouts: Keywords

This section describes keywords to model empirical roundabouts: APPROACHWIDTH CAPACITYINTERCEPT CAPACITYSLOPE CROSSING2ENTRY CROSSING2EXIT CROSSINGLENGTH ENTRYANGLE ENTRYRADIUS ENTRYWIDTH FLARELENGTH INSCRIBEDDIAMETER
APPROACHWIDTH
NOTE: Keywords are case-insensitive. Capitalizing as ApproachWidth might improve readability.
This real-valued keyword allows the specification of the approach half width (in meters or feet), one of the geometric parameters for the U.K.-calibrated empirical roundabout model.
To measure the approach half width, measure from the road center line to the curb at a point sufficiently far from the roundabout that the curb and center line are parallel. In the diagram below, the double arrow marked v (below the arrow) and AWID (to the left of the arrow) illustrates the measurement.
CAPACITYINTERCEPT
NOTE: Keywords are case insensitive. Capitalizing as CapacityIntercept might improve readability.
At an empirically modeled roundabout, each approach is characterized by two real numbers, the capacity slope and the capacity intercept. The capacity intercept is the entry capacity when the circulating flow is zero. The CAPACITYINTERCEPT keyword may be used to supply the capacity intercept directly.
If CAPACITYINTERCEPT is coded for a roundabout entry, CAPACITYSLOPE must also be coded for that entry and none of the roundabout geometric parameters may be coded for that entry.
CAPACITYSLOPE
NOTE: Keywords are case insensitive. Capitalizing as CapacitySlope
might improve readability. At an empirically modeled roundabout, each approach is characterized by two real numbers, the capacity slope and the capacity intercept. The capacity slope is the marginal decrease in
entry capacity when the circulating flow is increased by one PCU per hour. The CAPACITYSLOPE keyword may be used to supply the capacity slope directly.
If CAPACITYSLOPE is coded for a roundabout entry, CAPACITYINTERCEPT must also be coded for that entry and none of the roundabout geometric parameters may be coded for that entry.
CROSSING2ENTRY
This keyword specifies the position of a zebra crossing on an approach to a roundabout or a minor approach priority junction. Its value is the number of vehicles that may queue at the junction without impeding pedestrians who wish to cross. At roundabouts and single lane minor approaches to priority junctions, a single integer value should be supplied. However, on two-lane minor approaches to priority junctions, separate values should be supplied for each of the two lanes.
CROSSING2EXIT
This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction.
CROSSINGLENGTH
This real-valued keyword allows the specification of the length of a zebra crossing that crosses an approach to a roundabout or priority junction. If it is absent then no crossing will be modeled.
ENTRYANGLE
NOTE: Keywords are case insensitive. Capitalizing as EntryAngle
might improve readability. This real-valued keyword allows the entry angle, theta, of a roundabout to be coded. There are three cases for the measurement of phi.
Case 1: A roundabout with straight weaving sections
Let A be the point where the entry line meets the inside edge of the lane
Let D be the point on the median island (or line) of the following entry which is nearest to A EF is curve which is in the middle of the area of road for vehicles entering the junction BC is a tangent to EF at the point where EF intersects the stop line phi is the angle between BC and AD
Case 2: A roundabout with long curved weaving sections
The construction for case 2 is nearly identical to that for case 1. However, the line AD is replaced by a curve AD which is always parallel to the weaving section.
Case 3: A roundabout with short weaving sections
EF and BC are constructed as in case 1
JK is constructed in the same way as EF, but for the following exit GH is the tangent to JK where JK meets the edge of the circulating section L is the intersection of BC and GH phi is zero or (90 - (angle GLB)), whichever is greater
ENTRYRADIUS
NOTE: Keywords are case insensitive. Capitalizing as EntryRadius
might improve readability. This real-valued keyword allows the specification of the entry radius (in meters or feet), one of the geometric parameters for the U.K.-calibrated empirical roundabout model. The entry radius is defined as the minimum radius of curvature of the curb line at the entry.
ENTRYWIDTH
NOTE: Keywords are case insensitive. Capitalizing as EntryWidth might improve readability.
This real-valued keyword allows the specification of the entry width (in meters or feet), one of the geometric parameters for the U.K.calibrated empirical roundabout mode. To measure the entry width: Let A be the point where the stop-line meets the inside edge of the lane Let B be a point on the curb-line such that the line A-B is normal to the curb at B The entry width is the length of the line A-B
In the diagram below, the double arrow marked C and EWID illustrates the measurement.
FLARELENGTH
NOTE: Keywords are case insensitive. Capitalizing as FlareLength might improve readability.
This real-valued keyword allows the specification of the modified flare length (in meters or feet) for the entry to an empirically modelled roundabout. This is measured using the following procedure:
Let A be the point where the stop line meets the inside edge of the lane. Let B be the point on the curb line such that the line A-B is normal to the curb line at B (A-B is the entry width, e). Let v be the approach width. Let D be a point on A-b such that the length of A-D is v. Let D-G be a curve through D and parallel to the inside edge of the lane. (G is the point where the curve meets the curb). Let C be the mid point of D-B.
Let C-F be a curve parallel to the curb which intersects the curve D-G at F. The modified flare length is the length of the curve C-F.
INSCRIBEDDIAMETER
NOTE: Keywords are case insensitive. Capitalizing as InscribedDiameter might improve readability.
This real-valued keyword allows the specification of the inscribed circle diameter of the roundabout (in meters or feet). Usually this is the largest circle that can be inscribed wholly within the outline of the junction (see figure below). However, when the intersection is very asymmetrical, a local value in the region of the entry should be taken.
Empirical roundabouts: Example

The following example uses geometrical data to calculate slopes and intercepts:
Junction,
Node = 213, Type = Roundabout, Approach1 = 223, Approach = 223, EntryWidth = 12.5, ApproachWidth = 7.3, FlareLength = 25.0, InscribedDiameter = 25.0, Approach = 224, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0, Approach = 321, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0,
After comparing the model results to the performance of the intersection on the ground, it was decided to recode approach 224 to give the slope and intercept directly:
Junction, Node = 213, Type = Roundabout, Approach1 = 223, Approach = 223, CapacitySlope = 0.2, CapacityIntercept = 3600, Approach = 224, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0, Approach = 321, EntryWidth = 10.0, ApproachWidth = 6.0, FlareLength = 15.0, InscribedDiameter = 25.0,
Gap acceptance roundabouts: Keywords

This section describes the keywords to model gap-acceptance roundabouts: CRITICALGAP FOLLOWUPTIME
CRITICALGAP
Keywords are case-insensitive but the recommended capitalization CriticalGap may improve readability. The critical gap, in seconds, is one of the parameters of any gapacceptance capacity model. At roundabouts, it is applicable by arm. It is defined as the minimum time interval in the circulating stream that allows intersection entry for one vehicle. The U.S. Highway Capacity Manual 2000 suggests that, for a singlelane roundabout entry in the US, the critical gap should be in the range 4.1 to 4.6 seconds.
FOLLOWUPTIME
NOTE: Keywords are case insensitive. Capitalizing as FollowUpTime might improve readability.
The follow-up time, in seconds, is one of the parameters of any gapacceptance capacity model. At roundabouts, it is applicable by arm. It is defined as the time between the departure of one vehicle from the entry and the departure of the next vehicle using the same circulating flow gap, under a condition of continuous queuing on the entry. The U.S. Highway Capacity Manual 2000 suggests that, for a singlelane roundabout entry in the America, the follow-up time should be in the range 2.6 to 3.1 seconds.
Gap-acceptance roundabouts: Example

The following illustrates a gap-acceptance roundabout model:
Junction, Node = 253, Type = Roundabout, Approach1 = 32, Approach = 32, 208, CriticalGap = 4.6, FollowUpTime = 3.1, Approach = 256, CriticalGap = 4.35, FollowUpTime = 2.85, Approach = 486, CriticalGap = 4.1, FollowUpTime = 2.6
Intersection Modeling Priority junctions
Priority junctions
This section describes priority junctions (two-way yield-controlled intersections). Topics include: Overview of priority junctions Keywords Geometric priority junctions: Keywords Geometric priority junctions: Example Saturation-flow priority junctions: Keywords Saturation-flow priority junctions: Example
Overview of priority junctions

A priority-junction control is an unsignalized intersection between a major road and a minor road. It has different names in the U.K. (where priority junctions are common) and the U.S. (where twoway yield-controlled intersections are rare). In the U.S., the minor road approach (at a T), or approaches (at a crossroads) have yield signs. In the U.K., the yield signs are optional. Traffic on the minor need not stop before entering the intersection, but must give way to any major road traffic. Cube Voyager offers two model variants, both of which are calibrated to U.K. traffic conditions: a full empirical model based on junction geometry and a simplified models in which the user provides saturation flows which have been estimated or measured externally to Cube Voyager. When a single-lane major road is being modeled, very large capacities may be reported. This occurs when a movement, which is unconstrained, shares a lane. The capacity is chosen to give the correct ratio of volume to capacity (as calculated for the constrained movement).
Keywords
This section describes keywords for priority junctions: GEOMETRIC SINGLELANE
GEOMETRIC
The keyword Geometric=y, invokes modeling of layout geometry at a priority junction. The default, GapAcceptance=n, at a priority junction is for the user to supply saturation flows directly.
SINGLELANE
NOTE: Keywords are case insensitive. Capitalizing as SingleLane
might improve readability. The logical-valued keyword is used to indicate that an approach consists of a single lane. It is applicable to many junction types:
Junction type Signals All-way stop-controlled intersection Two-way stop-controlled intersection Priority intersection (two-way yield-controlled intersection) Roundabout Geometric Data Geometric Data Saturation Flows Use SINGLELANE may be coded SINGLELANE may be coded SINGLELANE may not be coded; code NUMBEROFLANES = 1 SINGLELANE may be coded for minor road Use FOURLANEMAJOR to describe major road SINGLELANE may be coded
Saturation Flows Empirical Gap Acceptance
SINGLELANE may be coded SINGLELANE may not be coded SINGLELANE may not be coded
Coding SINGLELANE = Y for an approach precludes the use of EXCLUSIVELANES, CANSHARERIGHT, or CANSHARELEFT on that approach. At two-way stop-controlled intersections and priority junctions, a minor arm, which does not have SINGLELANE = Y explicitly coded, has two lanes.
Geometric priority junctions: Keywords

This section describes the keywords for geometric priority junctions: CENTRALRESERVATIONWIDTH CROSSING2ENTRY CROSSING2EXIT CROSSINGLENGTH FREEFLOWCAP MAJORROADWIDTH VISIBILITY WIDTH
CENTRALRESERVATIONWIDTH
NOTE: Keywords are case insensitive. Capitalizing as CentralReservationWidth might improve readability. CENTRALRESERVATIONWIDTH is a real-valued keyword (only)
applicable to geometrically modeled priority junctions. Its value is the width, in meters or feet, of the curbed central reservation in the major road. If there is no central reservation, or the central reservation is composed of ghost islands (that is, road markings), then CENTRALRESERVATIONWIDTH should be zero (the default). Otherwise its value should be in the range from 2.2 to 5.
In the diagram below, the CENTRALRESERVATIONWIDTH is given by (W5 + W6).
CROSSING2ENTRY
This keyword specifies the position of a zebra crossing on an approach to a roundabout or a minor approach priority junction. Its value is the number of vehicles that may queue at the junction without impeding pedestrians who wish to cross. At roundabouts and single lane minor approaches to priority junctions, a single integer value should be supplied. However, on two-lane minor approaches to priority junctions, separate values should be supplied for each of the two lanes.
CROSSING2EXIT
This integer-valued keyword specifies the position of a zebra crossing on an exit from a roundabout or priority junction. Its value is the number of vehicles that may queue at the crossing without impeding vehicles using other exits from the junction.
CROSSINGLENGTH
This real-valued keyword allows the specification of the length of a zebra crossing that crosses an approach to a roundabout or priority junction. If it is absent then no crossing will be modeled.
FREEFLOWCAP
NOTE: Keywords are case insensitive. Capitalizing as FreeFlowCap might improve readability.
By default, the unmodelled movements from the major approaches of a priority junction have infinite capacity. However, this may result in too large a capacity for the approach as a whole when it must share a lane with a modelled turn. You can supply a capacity for these movements by coding FreeFlowCap=value and SingleLane=t.
MAJORROADWIDTH
NOTE: Keywords are case insensitive. Capitalizing as MajorRoadWidth might improve readability. MAJORROADWIDTH is only applicable to geometrically modeled
priority junctions, where it is required. The presence or absence of this keyword allows the two methodologies for priority junction modeling to be distinguished.
MAJORROADWIDTH is a real valued keyword whose value is the
width, in meters or feet, of the major road lane (excluding any central reservation or ghost islands) near the intersection. It is illustrated in the four diagrams below. In each case the major road width is given by the expression (W1 + W2 + W3 + W4).
VISIBILITY
This real-valued keyword allows the visibilities, in meters or feet, at a geometrically coded priority junction (two-way yield-controlled intersection) to be entered. Visibilities may be coded for the minor road left and right movements and for the opposed movement from the major road. Minor road visibilities should be measured from a point ten meters before the give-way line and 1.05 meters above the road surface. The major road visibility is measured from the mid-point of the turning lane (again at height 1.05m), along the major road, towards the road center line.
WIDTH
This real-valued keyword is used to specify the lane widths (in meters or feet) for a minor road at a priority junction (two-way yield-controlled intersection). Code widths for left and right movements on minor roads and for the opposed movement from the major road. The width for the major roads opposed movement is the width of the lane from which vehicles on the major road turn. Coding techniques for minor roads vary with the number of lanes. To describe a two-lane minor road: Do not code SINGLELANE = T. Code the width of the left-hand lane in the left movement. Code the width of the right-hand lane in the right movement.
To describe a one-lane minor road: Code SINGLELANE

= T.
Code the width of the single lane in the left movement, or the right movement, but not both.
The coded widths should be the lanes average width during the final 25 meters of the approach before the give-way line.
Geometric priority junctions: Example

This example illustrates the coding of a three-arm priority junction, with input geometric data.
Junction, Node = 250, Type = Priority, Approach1 = 455, MajorRoadWidth = 10.9, CentralReservation = 1.2, Approach = 455, Movement = Right, Width = 2.5,
Visibility = 170.0, Approach = 249, Movement = Left, Width = 2.05, Visibility = 130.0, Movement = Right, Width = 2.05, Visibility = 125.0, Approach = 251, Movement = Right, Width = 2.9, Visibility = 150.0, Approach = 255, SingleLane = y, Movement = Left, Visibility = 100.0, Movement = Right, Width = 3.1, Visibility = 127.0
Saturation-flow priority junctions: Keywords

This section describes the keywords for saturation-flow priority junctions: CANSHARELEFT CANSHARERIGHT EXCLUSIVELANES SATFLOWPERLANE
CANSHARELEFT
NOTE: Keywords are case insensitive. Capitalizing as CanShareLeft
might improve readability. This keyword specifies that there is a shared lane to the left of the exclusive lanes for this movement (that is, the movement can share with the movement to its left). Note that this keyword does not
mean can share with left turners unless either the movement is THROUGH or the movement is on the minor leg of a three-arm junction. If a movement has CANSHARELEFT = T coded then there must be a movement to this movements left and the movement to this movements left must have CANSHARERIGHT = T coded. If SINGLELANE = T then CANSHARELEFT should not be coded.
CANSHARERIGHT
NOTE: Keywords are case insensitive. Capitalizing as CanShareRight
might improve readability. This keyword specifies that there is a shared lane to the right of the exclusive lanes for this movement (that is, the movement can share with the movement to its right). Note that this keyword does not mean can share with right turners unless either the movement is THROUGH or the movement is on the minor leg of a three arm junction. If a movement has CANSHARERIGHT = T coded, then there must be a movement to this movements right, and the movement to this movements right must have CANSHARELEFT = T coded. If SINGLELANE = T then CANSHARERIGHT should not be coded.
EXCLUSIVELANES
NOTE: Keywords are case insensitive. Capitalizing as ExclusiveLanes might improve readability.
This integer-valued keyword gives the number of lanes, on the specified approach, which are reserved for the exclusive use of vehicles making the specified movement. If SingleLane = t then ExclusiveLanes should not be coded.
SATFLOWPERLANE
NOTE: Keywords are case insensitive. Capitalizing as SatFlowPerLane might improve readability.
This real-valued keyword allows the specification of saturation flows in pcu (vehicles) per hour per lane. Saturation flows at signals are the flows that would be observed if the movement had a continuous green all other movements had no flow and no green. Saturation flow at a priority junction (two-way yield-controlled intersection) is defined similarly, except that no signal aspects are involved.
Saturation-flow priority junctions: Example

The example describes a priority junction using with a three-lane major and two-lane minor using default saturation flows per lane.
Junction, Node = 229, Approach1 = 396, Type = Priority, Approach = 228, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, ExclusiveLanes = 1, CanShareLeft = y, CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y, Approach = 396, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, ExclusiveLanes = 1, CanShareLeft = y,
CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y, Approach = 315, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, CanShareLeft = y, CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y, Approach = 409, Movement = Left, ExclusiveLanes = 1, CanShareRight = y, Movement = Through, CanShareLeft = y, CanShareRight = y, Movement = Right, ExclusiveLanes = 1, CanShareLeft = y
Network Program
This chapter discusses the Network program. Topics include: Introduction to the Network program Control statements Theory Examples
Network Program Introduction to the Network program
Introduction to the Network program

Network is a utility program for processing highway networks. Up to ten input networks can be processed simultaneously, and one output network can be generated. The input network files can be of various formats: ASCII records, standard database in dBASE style (DBF), or any Cube Voyager, TP+, MINUTP, Tranplan, or TRIPS binary network format. Beginning with version 5.0, input highway networks may be a Cube geodatabase network. A data record is generated for each unique node and each link that is found in all the input files. The minimum requirement for a valid node record is a node variable and the Network program expects this variable to have the variable name N. The minimum requirement for a valid link record is an A node and a B node variable (each of which must exist on a node record) and the Network program expects these variables to be named A and B respectively. If the network is to be opened in Cube Graphics for viewing and/or editing then the node records must also have two additional variables to represent the X and Y coordinates of each node. Cube expects these coordinate variables to be named X and Y. Each of these records can be processed through user controlled logic, and its data can be summarized and reported in various manners. In v3.2.x and earlier, node and link records in a given data file had to be unique. This limitation has been lifted starting with v4.0. In v4.0, the COMBINE keyword has been added to both the LINKI and NODEI keywords under the FILEI statement so that users can specify how they would like to treat the values on the fields of redundant data records. If a Tranplan network is detected as input, the program will immediately write it in a Cube Voyager format onto a temporary file, and then use that file in place of the original file for subsequent processing. (Note: Cube Voyager treats a FSUTMS network as a standard Tranplan network. No auxiliary files will be open. Only Cube deals with FSUTMS networks differently.)
If an output network is specified, a file is written in a proprietary (Cube Voyager or MINUTP) binary format. It is a network database that contains speed/capacity information, node records, and link records. In MINUTP networks, the node information consists solely of coordinates for each node. In a Cube Voyager or TP+ network, there may be any number of items for nodes. Optionally, a file of link records and/or a file of node records may be written in either ASCII or DBF format. Beginning with version 5.0, output networks may be a Cube Voyager custom network feature class, stored in an ESRI custom geodatabase. See the description for the FORMAT subkeywords under NETO keyword for the FILEO statement on page 354 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
Built-in variables
Variable A B GEOMETRYSOURCE Description Node number of a links A node Node number of a links B node Defines the input file index number that controls the source of the geometry to be applied to the output NETO file when multiple input networks are specified. The Network program may take up to ten input networks. These ten networks can be any of the supported binary formats, Cube geodatabase networks, or combinations of link and node files in ASCII, DBF, or MDB formats. When specifying an output network to a Cube geodatabase network, GEOMETRYSOURCE specifies which # from the FILEI LINKI[#]= specifications provides the geometry to be applied to the output geodatabase network. Each input network coming from a geodatabase network will have a field called GEOMETRYSOURCE. This fields value is the index of the input file (3 for LINKI[3], for example). Other input formats could also have a field called GEOMETRYSOURCE defined by the user. The value of the GEOMETRYSOURCE field in the output network dictates the source of the link geometry. By default, the value is taken from the first available value from all the input networks. So if LINKI[1] is a binary network without a GEOMETRYSOURCE field and LINKI[2] is a geodatabase network, the output GEOMETRYSOURCE field will have a value of 2 (unless there is no record in LINKI[2] for a certain link). If Merge Record=T, records that are merged from other LINKIs retain their GEOMETRYSOURCE value. Therefore, the output network could have a mix of GEOMETRYSOURCE values. In addition, you can specifically set the value in a script based on other attributes in the various input networks (for example, downtown use LINKI[3], and other areas use LINKI[2]). N X Y _COMPARE _ZONES Node number of the node X-coordinate value of a node Y-coordinate value of a node Stores a return code value resulting from the COMPARE statement Holds the number of zones read from the input network as set by the ZONES parameter
Built-in functions
Function SPEEDFOR(lanes,spdclass) CAPACITYFOR(lanes,capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass. Returns the capacity times the lanes for the designated number of lanes and capclass.
Network Program Control statements
Control statements
This section describes the control words available in the Network program.
Control word ABORT ARRAY BREAK COMP COMPARE CONTINUE CROSSTAB DELETE EXIT FILEI FILEO IF ... ELSEIF ... ELSE ... ENDIF LOOKUP LOOP ... ENDLOOP MERGE PARAMETERS PLOT PLOTTER PRINT PROCESS ... ENDPROCESS REPORT SORT SPDCAP Description Abort current program and Cube Voyager Declare user arrays Break out of stack processing for current data record Compute variables from expressions Compare network records Continue at end of loop statement Tabulate / cross tabulate variable values Delete this record Terminate current phase Input files Output files Define IF ENDIF block Define lookup tables (see Chapter 3, General Syntax) Define user controlled loop Set record and variable merging specifications Set static parameters Draw and post values on links and nodes Set plotter driver specifications Print variable values Set process (phase) blocks Select standard reports Sort user arrays Set / revise network speed and capacity table values
ABORT
Aborts the Network program and Cube Voyager. MSG Use ABORT to quit the Network program at with a fatal return code. Use this statement if you can determine from the data that you desire no further processing.
ABORT keyword
Keyword MSG |S| Description Optional message to be printed along with the ABORT message.
Example
IF (a > 1000) ABORT MSG='Must be the wrong Network'
ARRAY
Declares user single dimension arrays. VAR=size, VAR=size Use ARRAY to allocate user arrays that are to be used in the process. An array is different than a variable in that it represents vectored data. Values stored in arrays must be numeric. Arrays cannot store string values. When an array is referenced, it should include an index [], and if the index exceeds the size, the program may fatally terminate. Arrays can be useful for different processes; the most
common use may be to store information for specific zones. ARRAY statements are not dynamic (stack oriented); they are allocated prior to any stack operations.
ARRAY variable
Variable VAR |I| Description VAR is the name of the variable that is to be allocated according to the specified size. VAR must be a unique name. The size following the keyword is the highest index possible for VAR. Size may be either a numeric constant, or a special name. Special names are: ZONES, NODES, and LINKS if there is a binary input network. NODES and LINKS should not be used if links are to be added to the network. Arrays are cleared when they are allocated.
Example
ARRAY abc=100, xyz=100 ARRAY AN=LINKS, BN=LINKS, VMT=LINKS ; NETI must be a binary network
BREAK
Breaks out of stack processing for current data record. When a data record is being subjected to the operations in a phase block, and the operation is BREAK, the remainder of the block operations are bypassed and the next data record is processed. Most likely, BREAK would be used in conjunction with an IF statement. However, if BREAK is encountered within a LOOP, stack processing jumps to the statement after the associated ENDLOOP statement.
Example 1
if (a=1-500 || b=1-500) BREAK ; do not process centroid links. if (a.x > b.x) ; bypass the links that go from right to left BREAK endif
Example 2
/* this example finds the index where subtotal of ARRAY1 exceeds 1000 */ loop index=1,_zones _total = _total + array1[index] if (_total>1000) BREAK endloop list=INDEX =,index ; BREAK jumps to here
COMP
Computes a value for a variable.
Variable = Expression
COMP statements specify that new variables are to be created or that existing variables are to have new values computed for them. During any phase other than the SUMMARY, any name that appears on the left side of the equals sign will be placed into the output network record, unless it is a working variable (begins with an underscore). There may be more than one variable computed on a statement, but there must be comma between an expression and the next variable=expression. The statement need not begin with COMP.
The expression will be solved and the results stored in the named variable. The phase for which this COMP statement is coded will establish which variables may be included within the expression, and where the results can be stored. The maximum length of the name is 15 characters. This limit includes the _ prefix of temporary variables. A normal numerical expression is required. If the expression results in a string, the mode of the target (named) variable will be set to string instead of numeric. A variables mode should be consistent throughout the application. The program tries to detect any possible changes, or misuse of variable modes, but it might not detect all inconsistencies. If a variable is misused as to mode,
unpredictable results could occur. It might be prudent to have a standard naming convention for string variables, such as always beginning with the same letter. The expression may contain function names with their arguments. To obtain speed and/or capacity values from the SPDCAP tables, the SPEEDFOR and CAPACITYFOR functions are utilized. They are coded as:
Function SPEEDFOR(lanes,spdclass) CAPACITYFOR(lanes,capclass) Description Returns the speed from the SPEED table for the designated number of lanes and spdclass. Returns the capacity times the lanes for the designated number of lanes and capclass.
In the SPEEDFOR and CAPACITYFOR functions, the first argument is the number of lanes and the second argument is the class. If the lanes value is less than 1, or greater than 9, the function value of lanes will be reset accordingly. Thus, if CAPACITYFOR (88...) were specified, lanes would be reset to 9, and the capacity extracted for that value would be multiplied by 9. Similarly, if the second argument is less than 1, or greater than 99, the internal value will be reset to the appropriate limit.
Example
i = 0 j = a / i, k=j*2+3*i newb = nodecode(b) sumab = newb+newa cdist = sqrt((a.x-b.x)^2 + (a.y-b.y)^2) _LinkSpeed = SPEEDFOR(Lanes,Facility*10+Area)
COMPARE
Compares network records. RECORD (LIST TITLE)
COMPARE statements are dynamic and are used to compare the
records of either the link or node portion of two networks. At the end of the phase (NODEMERGE or LINKMERGE), a summary of the comparison is reported. The LIST parameter controls the listing of individual differences. To make this statement function properly, the MERGE RECORD=T statement should be coded. In addition to a summary report, COMPARE also returns a value indicating the result after the comparison of each record. The value is stored in a temporary variable: _COMPARE. The meaning of the returned value is as follows:
Value of _COMPARE n 0 -1 -2 Meaning n attributes are different between two records. No differences between two records. Record not in file one. Record not in file two.
There may be multiple COMPARE statements in a single application.

COMPARE keywords
Keyword RECORD |IP| Description Indicates which LINKI or NODEI set of records is to be compared. Two numbers, separated by a dash, must be coded. This keyword may occur only one time on a COMPARE statement. Indicates how many of the links with differences are to be listed to the print file. The default is 0. If LIST=100, then only the first 100 links with differences will be listed. If a link exists in one file but not in the other, a single line is generated. But, if the record keys match, each variable for which there is a difference will be listed on a separate line with the values from both files and the difference. TITLE |S| Optional title to print with the summary report. It is suggested that the value be embedded within quotes.
LIST
|I|
Example 1
LINKI[1] = current.net LINKI[2] = future.net COMPARE RECORD=1-2
The following is a sample output in the print file:

COMPARE 1 vs. 2: 1=2 ------- 1 < 2 ------Variable Cnt Cnt Min Max Ave -------- --- --------A 321 ----B 321 ----LANES -- 321 1 1 -1 DISTANCE -- 321 1 1 -1 SPDCLASS -- 321 2 2 -2 CAPCLASS -- 321 1.23 1.23 -1.23 NAME -- 321 ------- 1 > 2 ---Cnt Min Max Ave --- --- --- --7 -- -- -7 -- -- --- -- -- --- -- -- --- -- -- --- -- -- --- -- -- --
Ave -----1 -1 -2 -1.23 --
The 1=2 column lists the number of records where the records are the same. The 1<2 set of columns lists the number of records where the values for the listed variables are lower in file 1 than in file 2, and the 1 > 2 set lists the summary where file 1 values are greater than file 2, The final AVE column lists the average difference for the variable, using only records where there is a difference. The Min and Max differences show the range of differences for the variable.
Example 2
RUN PGM=NETWORK NETI=NET1.NET, NET2.NET NETO=NET3.NET MERGE RECORD=T PHASE=LINKMERGE COMPARE RECORD=1-2, LIST=20 ; compare link record 1 with 2 IF (_COMPARE=-2) CMPFLAG=1 ; link in NET1, not in NET2 IF (_COMPARE=-1) CMPFLAG=2 ; link in NET2, not in NET1 IF (_COMPARE>0) CMPFLAG=3 ; link in both but different ENDRUN
Example 2 illustrates how to use _COMPARE to flag the links in the merged network. The CMPFLAG attribute can be used in selection expressions in Viper to post the comparison results.
CONTINUE
Immediately jumps to the end of a loop, bypassing all stack statements until the associated end of loop. If it is within a loop, control passes to the appropriate ENDLOOP statement. Otherwise (not in a loop), stack processing for the record is terminated.
Example
LOOP _L1=1,3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ; no more processing for this data record LOOP _L2=_K1,_K2,_KINC LOOP _L3=_L2,_L2+5 IF (condition) CONTINUE ; jump to ENDLOOP for _L3 ENDLOOP ENDLOOP
CROSSTAB
Cross tabulates variables. VAR (FORM) ROW (RANGE) COL (RANGE) COMP (FORM) Use the CROSSTAB control statement to accumulate a tabular summary from the network. Use the VAR keyword to specify the variables you want tabulated. Use the ROW keyword along with the RANGE subkeyword and the COL keyword along with the RANGE subkeyword to specify the tables dimensions. If you omit either ROW or COL, the report collapses into only one column or one row. Although the CROSSTAB statement can include several instances of the VAR keyword, the statement tabulates all the variables to the same specifications. Use the COMP keyword to generate additional reports after network generation using the values from the
tabulated variables. For example; if the statement includes VAR = VehDist, VehTime, then including COMP = VehDist / VehTime would produce a table of average speeds.
NOTE: The program does not automatically produce totals because
your ranges may overlap. You can produce totals and subtotals with appropriate use of RANGE values. See below for a description of the process used in placing values in the appropriate range slots.
CROSSTAB keywords
Keyword COL COL RANGE Subkeyword |S| |RV50| Description Name of the variable that will be used for the column definition of the report. Same as for ROW (RANGE), but applies to the COL variable. Care should be taken to not cause the reported line to be too long (limit the number of column ranges). Expression that can be used to generate a report that is some combination of the reports generated by the VAR variables on this statement. The only variable names that may appear in the COMP expressions are the VAR variables that are on this statement. There may be up to ten COMP expressions on a statement. Specifies the format for the COMP reports. The standard Cube Voyager FORM syntax is used. If FORM is not coded for any COMP, the program will supply 7cs. The format applies to the COMP that it is coded with, and to all subsequent COMP variables until a new value is encountered. The first format will be backfilled to apply to any prior COMP variables Name of the variable that will be used for the row definition of the report.
COMP
|NV|
COMP
FORM
|S|
ROW
|S|
CROSSTAB keywords (continued)

Keyword ROW Subkeyword RANGE |RV50| Description Series of ranges (and increments) for stratifying the row variable for use in the report. A range as either one, two, or three numbers. If more than one number, the values are separated by dashes. The three values are low, high, and increment. The program establishes ranges for stratifying the ROW variable values. Each range has a lower limit, an upper limit, and an increment. If there is no upper limit, the program makes the upper limit equal to the lower limit. If there is no increment, the program assumes one row. If there is an increment, the program generates a row for each increment, starting at the lower limit, and progressing until the upper limit is reached. There are certain problems associated with stratifying non-integer data; they are discussed below. Name(s) of the variable(s) that are to be tabulated. The value of each variable will be accumulated into the cells of the generated table(s). A separate report will be generated for each variable named. There may be up to ten VAR keywords on a statement. Format to use when printing the accumulated values in the table. The standard Cube Voyager FORM syntax is used. If FORM is not coded for any VAR, the program will supply 7cs. The format applies to the VAR that it is coded with, and to all subsequent VAR variables until a new value is encountered. The first format will be backfilled to apply to any prior VAR variables.
VAR
|SV10|
VAR
FORM
|S|
Range classification strategy
The ROW RANGE and COL RANGE values are stored as singleprecision numbers, and the actual variable values are computed and stored as double-precision floating-point numbers. Single precision provides accuracy to about six, or seven, significant digits, whereas double precision provides accuracy to up to fifteen, or sixteen, digits. Because computers do arithmetic on a binary basis, numbers which seem to be easily described in base 10 cannot always be represented exactly in the computer. For example: the number 0.01 is a definite number in base 10, but it can only be approximated in base 2. If the program compares a variable to a
range limit, it might fail due to this limitation of the computer. The comparison result may differ, depending upon the floating point capabilities of the computer. Another concern is the definition of limits. If RANGE is 1-10, should a value of 0.9999999999 be included in it? If RANGE is 1-10-1, should a value of 10.001 be included, and which range should the value of 2.0001 fall into? To address all these concerns, the program is designed to check for RANGE satisfaction based upon an integer representation of both the RANGE limits and the data. You can control the level of precision when specifying the RANGE values. The level of precision is set by the maximum number of decimal places in any of the RANGE values (low-high-increment). The RANGE values and the ROW and COL variable values are factored and integerized (rounded) according to the decimal digits. If a single RANGE (no increment) is used, the program checks the value against the limits as: if the value is greater than, or equal to, the lower RANGE, and less than, or equal to, the higher value, the value satisfies the range. If a RANGE with an increment is used, a similar initial check is made to determine if the value fits within the outer RANGE limits. If the value fits with the range, the increment index is computed (in integer) as: ((value-lo) / inc) + 1. Examples may best illustrate this process.
RANGE 1-10 1-10-1 1-10-1 1-10-1.0 1-10-0.5 1-3-0.5 1-3-0.3 1-3-0.3 1-3-0.3 Internal Range 1-10 1-10-1 1-10-1 10-100-10 10-100-5 10-30-5 10-30-3 10-30-3 10-30-3 Integer Value 0.99 1.50 1.45 1.45 1.45 3.00 1.29 3.01 3.001 Value 1 2 1 15 15 30 13 30 30 Index -2 1 1 2 5 2 7 7
There is a caveat with this process. The maximum integer revised value for either RANGE or ROW is 2,147,483,647. For this reason, the program may adjust the number of decimal digits if either RANGE limit would exceed the maximum after revising.
Example
CrossTab VAR=DIST, _CNT, ROW=VC, RANGE=0.5-1.2-0.1, 0.5-1.2, 1.2-2.5-0.5, 2.5-9999, COL=LANES, RANGE=1-7-1, 1-3, 4-7, 1-7, 1-100-5, VAR=VMT FORM=6.1c, VAR=VHT, FORM = 6.2c, ROW=CLASS, RANGE=1-50-1, COL=LANE, RANGE=1-10, COMP=sqrt(VMT)+10*(min(1000,VHT)), COMP=VMT / VHT, FORM=8.3 ; weird example & ave trip length
CrossTab
DELETE
Deletes data record. When a data record is being subjected to the operations in a phase block, and the operation is DELETE, the remainder of the block operations are bypassed, and the record is removed from the network. Most likely, DELETE would be used in conjunction with an IF statement.
Example
If (a=2150-2199 || b=2150-2199) DELETE ;remove all links connected to nodes 2150-2199
EXIT
Exits current phase. Use EXIT to exit the current phase. The remaining input records to the phase will not be read.
Example
IF (a > 1000) EXIT; no reason to process beyond this link.
FILEI
and for important limitations when using Application Manager. Inputs data files. LINKI (EXCLUDE VAR (BEG LEN TYP MIN MAX) RENAME START STOP SELECT REV TRIPSXY DETAILS COMBINE (FIRST LAST AVE SUM MAX MIN CNT AVEX0)) NODEI (EXCLUDE VAR (BEG LEN TYP MIN MAX) RENAME START STOP SELECT COMBINE (FIRST LAST AVE SUM MAX MIN CNT AVEX0)) LOOKUPI The FILEI statement specifies the files that contain the network data. There may be up to ten NODEI and ten LINKI files designated. The index appended to the NODEI/LINKI control is used primarily for identification purposes and to try to assist in editing for possible user mistakes. If a LINKI file is a recognized binary file, an automatic corresponding NODEI file is assumed. However, the user can preclude the use of the node data from the automatic NODEI by providing a NODEI with the same index as the LINKI. This is not normally recommended, but it is at the users discretion. If a NODEI has the same index as a LINKI, and the LINKI file is a binary network, the NODEI must precede the LINKI. If the LINKI and NODEI files are not binary, the records need not be in any sorted order. Cube geodatabase networks have associated link and node stand-alone feature classes. If a LINKI file is a Cube geodatabase network, the automatic corresponding NODEI file is the networks node standalone feature class. If the user codes value limits for a variable (MIN=, MAX=), those limits are checked during the INPUT phase only. If the limits are exceeded, the record is rejected as an error and is not available for processing. Input record keys are not edited before being subjected to stack processing. This allows the user to decide what to do with records that have invalid record keys. Upon return from
stack processing, the key is checked to see that is in the range of 1nodes. If it is not, the record is then listed as an error. If the input file contains many bogus records (not valid data recordspossible if coming from a GIS DBF with extraneous records), you can check the key (N, A, or B) and DELETE the record, or recode the key.
FILEI keywords
Keyword LINKI Subkeyword |KFV10| Description Name of a file that contains link based records. The file format can be: ASCII DBF MDB data table Cube geodatabase network Link stand-alone feature class in a geodatabase network Recognized binary network.
The program will try to detect what type of file it is. If it cannot identify the file as a DBF, MDB, Cube geodatabase network, or a binary network, it will assume ASCII. If it detects that the file is a MINUTP binary network, the variables DIST, SPDC, CAPC, and LANE will automatically be renamed to DISTANCE, SPDCLASS,CAPCLASS, and LANES, respectively. Since most applications will input binary networks or Cube geodatabase networks, you can use the keyword NETI as an alias for LINKI. If the LINKI file and the NODEI file are DBF or MDB format then at a minimum, the LINKI file must have a field named A and a field named B and the NODEI file must have a field named N. If these fields in the DBF or MDB do not use this naming convention, then the RENAME keyword below can be used to rename the variables on input. NOTE: A valid network in Cube Voyager/TP+ need not have coordinate variables on the node records. If the network is to be viewed/edited in Cube then it must have variables named X and Y on the node records to hold the coordinate data.

Keyword LINKI Subkeyword COMBINE |?| Description Switch to indicate whether multiple link or node records exist on the input data file. The following subkeywords can be used to specify how to combine attributes values across multiple link or node records. FIRST, LAST, AVE, SUM, MAX, MIN, CNT, AVEX0 The descriptions of these keywords are identical to those described for the MERGE statement. The default for any variables not combined will be consistent with the value of PARAMETERS REPL_DUPL. If REPL_DUPL is true, the unlisted vars will be set to LAST, otherwise to FIRST. Example of usage:
FILEI LINKI=linki.dat, vars= v1,v2,v3,v4,v5,v6,v7,v8 combine=t, ave=v1,v3,v4 ave=v6,v8 FILEI NODEI=node.dat, vars=n,x,y, combine=t, first=x, last=y
LINKI
DETAILS
|?|
Switch to indicate if you would like to keep the full iteration results from an input loaded Tranplan network on the output file and have the iteration specific attributes available as li. variables during the run. Specifies name(s) of variable(s) to be excluded from the file. It is relevant only if the file is a DBF or binary network file and certain variables from it are not wanted, or if the input is defined as a series of variables (in delimited format -- not with BEG/LEN), and certain variables are not to be extracted from the input records. May be used to rename a variable from the input file. The format is RENAME=oldname-newname; both names must be specified. Names can be swapped on one statement; to swap names for V1 and V2: RENAME=V1-temp1,V2-V1,temp1-V2
LINKI
EXCLUDE
|SV|
LINKI
RENAME
|SP|

Keyword LINKI Subkeyword REV [I| Description Parameter that can be used in conjunction with files that are ASCII or DBF to specify if an input record is to represent a single directional link or if it is to be considered as two links (A-B and BA, with the B-A values being the same as the A-B values). Under normal conditions, an input record represents a single directional link from A to B. The REV parameter is used only if: There is no REV variable on the record. There is a REV variable on the record, but its value is neither 1 nor 2.
If there is a VAR=REV defined for the link data records, the value of the REV should be a 1 or a 2. If the value is not a 1 or a 2, the reversibility of the link is determined by the value assigned to this keyword. The only valid values for this keyword are 1 and 2; the default is 1. The record variable defined as REV will be treated as any other link variable, but it will not be written to the output network (the NETO will not contain a variable named REV). LINKI SELECT [s] Used only with ASCII input when it is desired to select only certain records from the file. The syntax is the same as for START. SELECT is processed after any STOP statement, and before any editing. Used only with ASCII input where the first valid data record follows some identifying header record. The expression value must be enclosed within parenthesis (), and the only valid variable is RECORD, which is the actual data record. The primary purpose is to allow the user to specify that there is a header, and how to identify it. The expression should contain a SUBSTR function to extract the header. START is used to position the file before actual data records are read. Used in a manner similar to the START keyword, but is associated with a trailer record. STOP is processed immediately after a record is read, and before any field editing. Name of a file that contains TRIPS X-Y data. This keyword is only required for TRIPS networks.
LINKI
START
[s]
LINKI
STOP
[s]
LINKI
TRIPSXY
[F]

Keyword LINKI Subkeyword VAR |SV| Description Name of a variable to be extracted from the file. Name lengths may not exceed 15 characters; case is ignored. To read variables from fixed-format text files, use the BEG and LEN subkeywords. To read character-string variables from free-format text files, use the subkeywords TYP and LEN, or append (C) or (Cn) to the variable name, where n specifies the number of characters. To read character-string variables from fixed-format text files, use the TYP, BEG, and LEN subkeywords. If the file is ASCII, and the variable is to be extracted from specific positions on each file record, BEG and LEN will have to be specified. The program assumes that ASCII files are free format and all fields are separated by white space, a comma, or some combination of both. Examples of free-form records:
1 2 3 1,2,3 1 , 2 3 1 ,2,3
All four of the above illustrated records contain three fields: 1, 2, and 3. Subkeywords of VAR include: BEG |I| Designates the beginning of the field in the input records. The first column of the record is designated as 1. Designates the length of the field that begins at position BEG. May be used to specify that the format of the variable is not numeric. An A means that the variable is alphanumeric. If TYP=A is specified for free format input, the LEN must also be specified, or it will default to 1. TYP A variable values on free format input must be enclosed within quote or literal marks ('...' or "..."), if they contain special characters (other than alphanumeric characters: a-z, 0-9). May be used to specify a minimum allowable value for the field. If the input value of the variable is less than this value, the variable will be rejected as an error.
LEN |I| TYP |S|
MIN |R|

Keyword LINKI Subkeyword VAR (continued) Description VAR may also be specified with parameters directly (without the above subkeywords). If the field following the variable name is a number, this format is automatically triggered. The total format is name,beg,len,min,max,typ. All these fields must be numeric, or null. A null field is specified by coding two commas with nothing between them. The parameter list is considered as exhausted when a non-numeric field is encountered. Typ must be coded as 1 to indicate that the variable is to be an alphanumeric field. Example: VAR=A,1,5,B,6,5 (A is in columns 1-5 and B is in 610). If the first two numbers that follow the name are separated by a dash, the numbers indicate the actual columns of the data record where the field is located. For example: VAR=A,1-5,B,6-10 (A is in columns 1-5, and B is in columns 6-10). If both forms may be used to specify variable (numeric format, followed by any of the sub-keywords); the keyword values will override the positional numbers LOOKUPI |FKV999| Name of file containing records for a lookup function implemented with the LOOKUP control statement. Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI. NODEI |KFV10| Name of a file or an MDB and element that contains node-based records. See LINKI on page 347 for comments regarding file detection. NODEI uses the same keywords as LINKI except REV and TRIPSXY.
Example
This section contains some examples of FILEI LINKI and FILEI NODEI usage.
LINKI[1]=\demo\demo20.dat exclude=dist,tsin ; file is binary network NODEI[1]=C:\DEMO\DEMOXY.DAT VAR=N,X,Y ; file is ASCII NODEI[2]=\demo\demo21.dat, LINKI[2]=\demo\?07.dat, var=a,beg=1,len=5, var=b,beg=6,len=5, var=dist,beg=14,len=4, var=rev,beg=35,len=1 LINKI[3]=freeform.fil, VAR=a,b,name,21,5,,,1,section,0,5 ;section follows name in free form nodei[4]=c:\citya\nets\linka.dbf, linki[4] = c:\citya\nets\nodea.dbf
LINKI[8]=Mixed_Node_and_Link.lxy, var=a,b,distance, start=(substr(record,1,2)=='LD'), stop=(substr(record,1,2)=='XY') NODEI[8]=Mixed_Node_and_Link.lxy, var=n,x,y, start=(substr(record,1,2)=='XY'), stop=(substr(record,1,2)=='LD')
FILEO
Outputs network file. LINKO (FORM FORMAT DELIMITER INCLUDE EXCLUDE VARFORM) NETO (FORMAT (TRIPSXY) EXCLUDE INCLUDE LEFTDRIVE) NODEO (FORMAT DELIMITER INCLUDE EXCLUDE FORM VARFORM) PRINTO (APPEND)
FILEO keywords
Keyword LINKO Subkeyword |KF| Description Name of a non-Cube Voyager output file onto which link records are to be written. May be any of the formats described by the FORMAT subkeyword or may be an MDB/element name. LINKO DELIMITER |S| Specifies a character that is to be used as the delimiter in SDF and TXT files. If the value is a special character (, - / + * = ;), it must be enclosed within quote marks, or it can be specified by using its decimal equivalent (for example, tab is code 9). The default value is a comma; but there is no default value for TXT files. Similar to EXCLUDE under NETO. Used to set the format of all variables to be written to the file. FORM is usually specified as w.d to indicate the maximum field width and number of decimal places to preserve. The optional FORM characters (CTDLR) are usually not appropriate for use on this statement. See the PRINT FORM definition in PRINT on page 62 for details of this parameter.
LINKO LINKO
EXCLUDE FORM
|SV| |S|

Keyword LINKO Subkeyword FORMAT |S| Description Specifies the format of the LINKO file. Possible values are: TXT File of ASCII records in which all the data fields are written in a fixed format SDF File of ASCII records in which the data fields are written in variable length, and separated by a delimiter DBF Industry-standard database file If there is a ? in the name, and there is no filename extension to the LINKO value, an extension of this value will be appended to the filename. If a DBF is written, and a designated FORM does not provide adequate width and decimal space for a field value, the program will try to adjust the field form within typical database rules to fit the value into the field space. LINKO INCLUDE |SV| Similar to INCLUDE under NETO. INCLUDE variables may have a form appended to their names in a manner similar to VARFORM. The same variable may be included multiple times. Specifies the form for specific variables. Each value is a variable name with its desired form in parenthesis appended to it. VARFORM=A(4.0), B(4.0) would cause A and B to be formatted as 4 characters wide with no decimal places. If the file format is SDF, the leading spaces will be deleted. This keyword need only be specified for those variables for which specific forms are required. To obtain the form for each variable, the program first tries to determine an appropriate format. Then the forms are applied in the order they appear on the statement. If the same variable appears on both a VARFORM list and an INCLUDE list, the latest appearance will prevail. The latest FORM will prevail for any variables not explicitly named in a VARFORM and/or INCLUDE list. NETO |KF| Name of the standard output network that is to be written.
LINKO
VARFORM
|SV|

Keyword NETO Subkeyword EXCLUDE |S| Description Designates that certain variables that would normally be included in the output network are to be excluded. If an excluded variables exists in both node and link records, only the link variable will be excluded. If the specified variable does not exist in any of the input files, Cube Voyager will ignore it and no warnings will be given. EXCLUDE and INCLUDE are mutually exclusive. Specifies the format for writing the output network. Normally, this is not specified; the program will write the file as a standard Cube Voyager binary network. If the value specified on the NETO keyword is an MDB/element name, the output will be written as a Cube geodatabase network in the MDB file, and will be given the element name. Two stand-alone feature classes will also be created in the MDB file, element_Node and element_Link. A table, element_SPDCAP will also be created and will contain the indices and values from the internal speed and capacity table. The output Cube geodatabase network will contain the additional link and node attribute, GEOMETRYSOURCE, which contains the input file number from which the geometry will be applied (for more information on GEOMETRYSOURCE see Built-in variables on page 332). Specify FORMAT=MINUTP to write a MINUTP network. MINUTP string variables are truncated to 80 characters. Specify FORMAT=TRIPS TRIPSXY=fname to write a TRIPS network and its associated XY file. NETO INCLUDE |S| Designates the variables that are to be included in the output network. Normally, this keyword is not used, but, if it is, only the listed variables will be included. It cannot be used with EXCLUDE.
NETO
FORMAT
|S|

Keyword NETO Subkeyword LEFTDRIVE |?| Description Switch that can be used to specify that a flag is to be placed in the output network file to indicate whether the network is left-side-drive oriented. This is primarily for use in JUNCTION modeling in the Network program; it does not have any affect on any PLOT statements in Network. This keyword is not necessary if the lowest numbered LINKI file had the LEFTDRIVE parameter set, or if PARAMETERS LEFTDRIVE was specified. The setting of the NETO value follows the rules: NODEO |KF| If PARAMETERS LEFTDRIVE is specified, use that value Else if NETO LEFTDRIVE is specified, use that value Else if lowest LINKI contains a LEFTDRIVE value, use that value Else do not set this value
Name of a non-Cube Voyager output file onto which node records are to be written. Its subkeywords are the same as those for LINKO. May be any of the formats described by the FORMAT subkeyword under the LINKO keyword, or may be an MDB/element name.
PRINTO
|KF|
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 62.
PRINTO
APPEND
|?|
When writing output files, an output network will be generated first even if NETO is not specified. Both LINKO and NODEO are derived from this output network, hence, subsets of it. Consequently, if NETO is specified and a link variable is excluded from it then that link variable will not be available for LINKO.
Example
FILEO NETO=MY.NET NETO=DEMOMINU.DAT, FORMAT=MINUTP, EXCLUDE=TEMP1, TEMP2 NODEO=TEXTNODE FORMAT=TXT, FORM=8.0 INCLUDE=A,B,DIST,SPEED,SPDCAP(2) LINKO=LINK FORMAT=DBF VARFORM=VC(6.3)

Performs certain operations based on conditions. Code IF condition blocks like standard Cube Voyager specifications. Enclose the IF and ELSEIF selections within parenthesis; the selections can reference any variables that are valid for the current phase. See IF ... ELSEIF ... ELSE ... ENDIF on page 48 for more details.
Example
PHASE=INPUT, FILE=NI.1 IF (N==5) . ELSEIF (N=1,3, 8-42 && X<3000 || Y=1-500,800-900) . ELSE . ENDIF ENDPROCESS IF (I < (K*3/6 +J) ) DELETE
LOOP ... ENDLOOP

Controls a general variable loop.
LOOP LVAR=Lbeg,Lend,Linc ; ... ENDLOOP
where: LVAR is the name of the loop control variable. LVAR is not protected during the loop; computational, program, and other LOOP statements can alter its value. LVAR must be followed by Lbeg, and optionally, by Lend and Linc. Lbeg is a numeric expression that initializes LVAR.
Lend is a numeric expression that is computed and stored when the LOOP statement is first processed. LVAR is incremented by Linc, and compared with Lend when the ENDLOOP statement is processed. If Lend is not specified, it is assumed no comparison is to be made (rather meaningless loop). Linc is a numeric expression that is computed and stored when the LOOP statement is first processed. The value is added to LVAR before the ENDLOOP comparison is made. If Linc is not specified, it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend; a backwards loop).
NOTE: All variables in a LOOP statement expression (Lbeg, Lend, Linc) must begin with the underscore character _ to prevent confusion with record variables.
Use LOOPENDLOOP blocks to repeat of a series of statements. LOOP initializes a variable(LVAR); ENDLOOP compares the contents of the variable to another value (Lend), and branches back to the statement following the LOOP statement if the comparison fails. LOOP blocks may be nested; they may not overlap IF blocks. The logic is as follows: At LOOP: Initialize LVAR to Lbeg. Compute the value for Lend. Compute the value for Linc (default to 1 if missing). Proceed to next statement. At ENDLOOP: If Lend not specified, jump to next statement. Add Linc to LVAR. Compare LVAR to Lend. Either jump back to statement following associated LOOP, or drop through.
The Lend and Linc variables are processed somewhat differently than in the other programs; they are computed at the LOOP statement and can not be modified by other statements. This helps to protect against possible endless loops. The loop will be processed at least one time regardless of Lend and Linc values. Most uses will involve constants. Because LVAR values can be expressions, Lbeg, Lend, and Linc must be separated by commas (standard white-space delimiting cannot be interpreted properly). If an expression is used, it is suggested that it be enclosed in either parentheses or quote marks.
Example
LOOP _pass=1,10 ; perform 10 passes ... ENDLOOP LOOP _xyz=_abc*_def,_ghi+_jkl,_mno/_pqr LOOP _abc=_xyz,_xyz+2,2 ; nested LOOP ... ENDLOOP ENDLOOP LOOP _jj=10,3,-2.5 ; perform 3 passes -- 10, 7.5, 5.0 ... ENDLOOP
MERGE
Specifies record and variable merging. RECORD AVE AVEX0 CNT FIRST LAST MAX MIN SUM Use MERGE to specify how records from different files are to be merged, and how variables of the merged record are to be combined. It is important to note that merging records and combining variables are independent processes. Use the RECORD keyword to specify which records are to have their data merged when records with identical keys are encountered during the NODEMERGE or LINKMERGE phases.
Use the other keywords to specify how individual variable values are to be obtained for the resulting merged record when there are duplicate records from different input files. (Duplicate records from the same file may not occur in the MERGE phase.) Each resulting record will have a cell for every variable that is specified in any input file or any COMP statement.
MERGE keyword selecting records
Keyword RECORD |?| Description Specifies if duplicate records are to be merged. If the value is false, only the records that exist in the FILEI with the lowest index [] will be included. If the value is true, any unique record is included. The default is true. If two networks (NETI[1] and NETI[2]) are input, and RECORD=FALSE, only the links that are in NETI[1] will be processed.
The following keywords indicate a process to use in obtaining the value for the variables that are listed following the keyword. The values for the variables will be obtained only from file records that contain the variable. A variable may appear in only one keyword list; any variables that are not in any list will be set to FIRST.
MERGE keywords technique
Keyword AVE AVEX0 CNT FIRST LAST MAX MIN SUM |SV| |SV| |SV| |SV| |SV| |SV| |SV| |SV| Description Average of all records. Average of all records, where the value from the file records is not 0. Count of the records that contain the variable. Directly from the record from the FILEI with the lowest index[]. Directly from the record from the FILEI with the highest index []. Maximum value of all the records. Minimum value from all the records. Sum of all the records.
Example
MERGE RECORD=TRUE FIRST=CAPCLASS,SPDCLASS, LAST=LANES, AVE=DISTANCE, SUM=COUNT
Illustration for sample input files (-- indicates variable not defined for file):
FILEI LINKI[1]=FILE1,VAR=A,B,DISTANCE,SPDCLASS,CAPCLASS,LANES FILEI LINKI[2]=FILE2,VAR=A,B,COUNT FILEI LINKI[3]=FILE3,VAR=A,B,DISTANCE,LANES
LINKI[] A 1 1 2 2 3 3 3 101 105 101 102 101 102 104 B DISTANCE SPDCLASS CAPCLASS 11 12 -----11 12 -----LANES 1 3 --2 2 3 COUNT --1000 1000 ----
102 10.1 106 12.5 102 -103 -102 11.5 103 12.6 105 1.0
Order as seen in LINKMERGE, after being processed in the INPUT phase.

LINKI[] A 1 2 3 2 3 3 2 B DISTANCE SPDCLASS CAPCLASS LANES 11 -----12 11 -----12 1 -2 -2 3 3 COUNT -1000 -2000 ----
101 102 10.1 101 102 -101 103 11.5 102 103 -102 103 12.6 104 105 1.0 105 106 12.5
MERGE RECORD=FALSE ; Resulting file:

A 101 105 B 102 106 DISTANCE 10.1 12.5 SPDCLASS 11 12 CAPCLASS 11 12 LANES 1 3 COUNT 1000 0
MERGE RECORD=TRUE FIRST=COUNT, AVEX0=DISTANCE ; Resulting file:

A 101 102 104 105 B 102 103 105 106 DISTANCE 10.8 12.6 1.0 12.5 SPDCLASS 11 0 0 12 CAPCLASS 11 0 0 12 LANES 1 2 3 3 COUNT 1000 2000 0 0
PARAMETERS
Specifies basic parameter values. LEFTDRIVE LIST_ERRS MAX_IP_ERRS NODES REPL_DUP ZONES
PARAMETERS keywords
Keyword LEFTDRIVE |?| Description Used to force a LeftDrive switch into the NETO. By default, this value is not set. See FILEO NETO LEFTDRIVE in FILEO on page 352 for more details. Specifies how many records with data errors will be listed before turning off the error listing. Default value is 20. Specifies how many records with data errors are allowed. If this value is exceeded, the program will terminate with a fatal condition. Default value is 20. Records with errors are not skipped, unless the error is in the key (for example, node number). The bad fields will be set to 0, unless the error is a limits error.
LIST_ERRS
|KI|
MAX_IP_ERRS
|KI|

Keyword NODES |KI| Description Specifies the highest node number to be allowed in the network. This need not be specified (by default, the program detects the highest number); but if it is specified, any node numbers that exceed this value are considered errors. The value must be a greater than 0 and less than 999,999. Switch that indicates how to process records from an input file with matching node numbers. If this switch is true, the later record will replace any previously read records. Default value is false. This keyword applies to each NODEI or LINKI file as it is read within any PHASE=INPUT. (Any nonbinary file will automatically be processed within an input phase; binary files should not have duplicate records.) The MERGE control statement is used to determine how duplicate links from different inputs are to be processed during the MERGE phases. To obtain a listing of duplicate links, specify REPORT DUPLICATES=T. ZONES |KI| Specifies the number of zones in the network. This is required only if the number of zones cannot be determined from the LINKI and NODEI files, or it is desired to alter the number of zones. By default, the program detects the value. The value must be greater than 0 and less than 20000. A temporary variable _ZONES is initially set equal to this value, and can be used in COMP and IF expressions. If ZONES is used in a COMP statement, it will become a variable in the output network. If this parameter value is not supplied (or is not available from an input binary network), the program will set it to the highest node number in a monotonic string beginning at 1.
REPL_DUP
|K?|
All the values on this statement are trigger keys; the PARAMETERS control word need not be specified. Each keyword could begin a new statement.
Example
PARAMETERS repl_dup=n MAX_IP_ERRS=10 nodes=35000 zones=2203
PLOT
Selects links/nodes for plotting. DRAWA DRAWLINK LINKPOST NODEPOST
PLOT statements in the LINKMERGE phase control plotting. After
the program completes the LINKMERGE stack for a link, it processes the final values for the PLOT keywords that may have been applied to the link. If there are no DRAWLINK values present, the link is not processed for plotting. If there are DRAWA and/or NODEPOST values, they are saved until all the links from the current A-node are completed. When the A-node is completed, the node values are saved for post processing, so that node symbols will be prominent on the display. If there is a LINKPOST value, but there is no DRAWLINK value, the LINKPOST value is ignored. The situation for nodes is different; a node can be posted without a symbol.
A PLOT statement may be specified on a short IF statement, but it must begin with one of the keywords.
PLOT keywords
Keyword DRAWA |S4| Description Specifies the characteristics for drawing a symbol for the A-node of the link. Possible values are: DRAWLINK |KS4| Color A value as described in PLOTTER on page 364. Size Size of the symbol. Symbol Centered on the node, can be Circle, Rectangle, or Triangle. Fill
Specifies the characteristics for drawing this link: color, size, and style. Color is a value as shown in the PLOTTER description, below. Size is the width of the line; current Windows drivers do not allow both size and style at the same time (style is changed to solid if a width is specified). Possible styles are: Solid, Dash, Dot, DashDot, DashDotDot. If PLOTTER BANDWIDTH is specified and the bandwidth variable has a value, Size and Style are ignored. It is recommended that Size usually be left null. Specifies the color that this link is to be posted with. Specifies the color and size of the variables that are to be posted for this Anode. (See NODEPOSTVARS under PLOTTER on page 364 for information about which variables are to be posted.)
LINKPOST NODEPOST
|S| |S2|
Example
See Examples on page 387.
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)
The PLOTTER statement specifies the configuration for plotting link and/or node information. See Plotting on page 384 for some information about getting your printer device installed and its basic configuration established. The printer driver properties are established by left-clicking the desired printer and then modifying the properties as desired. The orientation (portrait or landscape) determines how the plot will be generated, and the size determines the plate size of the drawing.
PLOTTER keywords
Keyword BANDWIDTH Subkeyword |S| Description Specifies the variable that is to be used to control the drawing of bandwidths along drawn links. Usually, a temporary variable should be designated. The variable must be scaled appropriately, or the plot will be unreadable. Specifies if the band is to be filled in or left empty. On raster plotters, this value should be specified as solid, but on pen plotters, solid could require excessive time for generating and actually drawing the plot. The possible values are: Solid and None. The default is None. Specifies that the ends of the bands are to be tapered towards the nodes rather than being perpendicular to the link. In grid plots where Fill is not used, a taper of 45 might be more presentable. Any integer value from 0 to 45 (degrees) may be specified. Name of the printer driver that is to be selected and written to. The name must match the name of the printer as it appears in the Printers dialog box. Case is not essential. If the name has spaces in it, the value must be enclosed within quotes so that the spaces can be considered as part of the name. There must be a DEVICE specified; otherwise the program will not know anything about the printer
BANDWIDTH
FILL
|S|
BANDWIDTH
TAPER
|I|
DEVICE
|S|
PLOTTER keywords (continued)

Keyword FILE Subkeyword |F| Description Used if it is desired to write the printer information to a file, rather than directly to the printer. This is recommended for devices that are normally not connected directly to the processing computer. If FILE is not specified, the output will be written directly to the printer device. If FILE is specified, actual printing (or plotting) is performed by copying the file directly to the port that is connected to the device. Specifies lines of text that are to be printed at the bottom of the plot page. There may be up to 16 footers. The program will add one additional footer to identify the software and the licensee after the user footers are printed. If none of the footers has specified a date, the date and time will be added included in the identification line. Tokens may be specified in the footers; when they are present the token is replaced by a value. The tokens and their replacements are: Token [date] [idate] [time] [times] [window] [scale] FOOTER ALIGN Replacement MM/DD/YY MMM DD YYYY HH.MM HH.MM.SS X=xxxxx-xxxxx Y=yyyyy-yyyyy Scale=xxxxx
FOOTER
|S16|
Specifies how the footers should be aligned on the plot. The value can be: Left, Right, or Center. ALIGN must be placed after a FOOTER or FONT value; if more headers are to be specified after ALIGN, the FOOTER[]= must be specified. Specifies the font characteristics of the footers. There may be up to nine values following FONT, but currently, only the first three are used. The values are (position), name, size, color.
FOOTER
FONT

Keyword HEADER Subkeyword |S16| Description Specifies lines of text that are to be printed at the top of the plot page. There may be up to 16 headers. Since headers most likely have special characters in them, it is recommended that each header be enclosed within quote marks ("..."). The highest index for a header sets the number of header lines that will be printed. Example: if only one header is specified, say HEADER[6]="...", 6 lines will be printed, with the first 5 being blank. Specifies how the headers should be aligned on the plot. The value can be: Left, Right, or Center. ALIGN must be placed after a HEADER or FONT value; if more headers are to be specified after ALIGN, the HEADER[]= must be specified. Specifies the font characteristics of the headers. There may be up to nine values following FONT, but currently, only the first three are used. The values are (position), name, size, color. Specifies the position for additional user text is to be printed on the plot page. There are four possible legend positions: TopLeft TopRight BottomLeft BottomRight
HEADER
ALIGN
|S|
HEADER
FONT
|S4|
LEGEND
|S|
NOTE: The four positions can also be designated as TL, TR, BL, and BR, or 1, 2, 3, and 4. See Examples on page 387. The legends are placed within the plot window area, and their areas are not written into by network drawing. The coding rules are similar to those for HEADER and FOOTER, but you can also enter symbols on each line. Legends are primarily for identifying the characteristics of the network drawing. Each LEGEND may have its own font characteristics; they will be used for the text for all lines in the legend. Each LINE can have its own symbol.

Keyword LEGEND Subkeyword FONT |S9| Description Specifies the font characteristics for the text in this legend. See HEADER FONT on page 367 for details. Text to be printed at the specified line of the legend. Specifies the symbol that is to precede the LINE text. There should be four values specified for the symbol: name, size, color, and fill color. Name See DRAWA under PLOT on page 363 for valid symbol names. If a sample line style is to be drawn, see DRAWLINK under PLOT on page 363 for valid names. The size of the symbol, or the length of the line. Standard color designation. Standard color designation if the symbol is to be filled with a color.
LEGEND LEGEND
LINE SYMBOL
|S16| |S4|
Size Color Fill LINKOFFSET |R|
Specifies the distance (in inches) that the links are to be drawn from the normal centerline. This allows two-way links to be more visually presented. If this keyword is not used, or the value is 0, the high-to-low node link will overwrite the low-tohigh link. Specifies a scale factor to be used to convert coordinate units to inches. The value is expressed as coordinate units/inch. If the value is not specified, a scale factor will be computed from known information. Note that when a factor is specified, the MAPWINDOW will be used mainly to orient the center of the plot.
MAPSCALE
|R|

Keyword MAPWINDOW Subkeyword |R4| Description Specifies two opposite corners of the map window to be selected. The map window is specified in map coordinate units. If no window is specified, the program uses the minimum and maximum coordinates from the network. The plot will be scaled to fit within the map window. The 4 required values are specified as X1,Y1, X2,Y2. Any part of the network that exceeds the limits of the window will not be drawn. If MAPSCALE is not specified, the scale factor will be calculated to fit the window within the page. The center of the map window will be placed in the center of the plotting window. MAPWINDOW will most likely not directly correlate with the plotting window; the program may adjust one of the dimensions if it is necessary. Specifies the margins that surround the plot window on the printed page. If the selected device is a printer that is selected with Letter size (8.5 x 11 inches), a normal margins would be 0.25 inches. If it were desired to leave more space around the plotted window (say 1 inch on the left and 1.5 inches on the right), MARGINS=0.75,1.25 would be used. To make the top margin 1.5 inches and the bottom margin 2 inches, MARGINS[3]=1.25, 1.75 would be used. You can do this with one keyword: MARGINS = 0.75,1.25,1.25,1.75. By judicial use, the plot window can be placed anywhere on the page that is desired.
MARGINS
|R4|

Keyword PLATESIZE Subkeyword |R2| Description Specifies the maximum plot plate (page) size. It should not be greater than the dimensions specified in the device properties; if it is, the output might be cropped. This keyword is used primarily to make a plate that is smaller than the basic dimensions of the device. The plate will be oriented at the upper left corner of the printed page. Nothing will be printed outside the rectangle defined by this The MARGINS values can be used to position the printed window within the plate. In general, this need not be specified; the MARGINS values can be used to establish the dimensions of the plot window. Two values must be entered: the width (x dimension), and the height (y dimension). They are expressed in inches. PLATESIZE is not normally used. Specifies the variables that are to be posted along links that are drawn and designated for posting by a PLOT LINKPOST value. Up to four variables can be selected. The same variables will be posted for all links; it is not possible to vary the variables. It is not recommended that different variables be posted on different links, but it is possible for the user to cause this to happen by specifying variables that are modified as desired in the stack statements. The number of desired decimal places for the posting of the variable can be appended to the variable name in parentheses, for example, POSTLINKVAR=VC(3) to post VC ratio with 3 decimal places. Specifies the font characteristics for link posting. The standard font designations are specified, but the color is ignored; the PLOT DRAWLINK statements set color.
POSTLINKVAR
|S4|
POSTLINKVAR
FONT
|S4|

Keyword POSTLINKVAR Subkeyword POST |S| Description Specifies how link post text is to be printed when it is too long for the link. The possible selections are: Fit All AutoSize AutoSize(ss) Omit the text; it doesnt fit. Print it, regardless if it overruns the link. Decrease the font size until it fits, or is too small. Same as AutoSize, but the optional (ss) indicates the minimum size to allow.
POSTNODEVAR
|S4|
Specifies the variables that are to printed to the upper left of a node that is designated for posting by a PLOT NODEPOST value. Specifies the font characteristics for node posting. The standard font designations are specified, but the color is ignored; the PLOT NODEPOST statements set color. The font size can be overwritten on a node-by-node basis.
POSTNODEVAR
FONT
|S4|
Font specifications
You can control all text that is to be printed on the plot. In general, you can specify the name of the font, the size, and the color. The font name must be recognized (and available), or the printer driver will substitute a font of its choosing. If no font is specified, the program will supply the name ARIAL. The size is always specified as absolute, in inches; changing to a different size printer will not alter the size the text. If no size is specified, the program will supply a value of 0.01. The color can be specified in various ways: by a standard name, or a numeric value to index color mix. Colors are processed in Windows by using a number that is a combination of the three colors (red green and blue). You can create the internal number by specifying an integer number (not too likely), a hexadecimal value (very common process), or by a string of digits preceded by a color indicator. Three bytes are used to store the intensity of each of the colors; the values can range from 0 to 255. To use the mixing string, the string must begin with one of the letters (RGB) followed by a number in the range of 0-255, and more
color strings, if desired. The order of the strings is irrelevant. To enter the hexadecimal value, the string must begin with 0x and be followed by a string of hexadecimal values (0-f ). The table below indicates the standard colors and their various representations. If there is no color for the font, a color will be chosen by the printer driver. For pen plotters, the driver will translate the color number to a pen number. The pen color correlation is determined by the properties of the driver. You may have to experiment to obtain which pen is selected for each color used.
Color black red green blue yellow purple aqua gray silver lime white none Decimal 0 255 49152 16711680 65535 8388736 16776960 8421504 12632256 65280 16777215 -1 HexValue 0x000000 0x0000ff 0x008000 0xff0000 0x00ffff 0x800080 0xffff00 0x808080 0xc0c0c0 0x00ff00 0xffffff -R#G#B# -r255 g128 b255 r255g255 r128b128 g255b255 r128g128b128 r192g192b192 g255 r255g255b255 --
Example
See Examples on page 387.
PRINT
Formats and prints a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See PRINT on page 62 for more details.
Example
PRINT LIST=A(4),B(5),DISTANCE(6.2) ABCDE(6.3), FORM=LRCD, LIST=SPEED, TIME1 ;Note: this line is a continuation
LIST= N(5), X, Y PRINT FORM=6.0CDLR LIST=A,B,DISTANCE, T0, SPDCLASS FILE=PRINTFIL.002

Specifies a PROCESS and ENDPROCESS block. PHASE (FILEI (comp))
PROCESS keywords
Keyword PHASE Subkeyword |KS| Description Indicates the phase to which the statements which follow it are to be applied. The end of the phase block is established when an ENDPROCESS or another PROCESS statement is encountered. The value for PHASE must be either INPUT, NODEMERGE, LINKMERGE, or SUMMARY. Used only with PHASE=INPUT, and indicates that the block statements are to be applied only when the specified FILEI file is being processed. Normally, only DBF and ASCII files are processed in the INPUT phase, but if a FILEI with a different mode is specified, the file will be processed in the INPUT phase. The value must be NI.# or LI.#, to indicate a file from NODEI[#], or LINKI[#] that was previously specified on a FILEI statement.
PHASE
FILEI
|F|
Normally, a PROCESS statement contains only the above keywords and values, and the operations to be performed on the designated file during the phase follow on additional control statements. The ENDPROCESS statement can alternatively be specified as ENDPHASE; that is more consistent if the PROCESS control is triggered by PHASE=. Citilabs recommends using PROCESS/ENDPROCESS blocks be used to contain all operational (stack) statements. That way there is no confusion about what is intended. If there is no specific PHASE=LINKMERGE statement, any stack statements that are not explicitly within a PROCESS block, will be executed in the LINKMERGE phase. Even if there are PROCESS blocks surrounded by stack statements, all the stack statements will be executed during the LINKMERGE phase. The program will skip over the PROCESS block.
There are some rules about PROCESS blocks: There may be only one PHASE=NODEMERGE There may be only one PHASE=LINKMERGE If there is a PHASE=LINKMERGE statement, there may not be stack statements that are not explicitly within a PROCESS block. In other words, once a LINKMERGE phase has been designated, all stack statements must be with an explicitly stated PHASE.
Example 1
; ; ; ; Re-code node numbers for LINKI[1] and NODEI[1] using a lookup function. The 2nd PROCESS statement also acts as an ENDPROCESS statement, but an ENDPROCESS is required after the 2nd PROCESS.
PHASE=INPUT FILEI=NI.1 N = NODECODE(N); PHASE=INPUT FILEI=LI.1; A = NODECODE(A), B = NODECODE(B) ENDPROCESS
Example 2
PHASE=LINKMERGE IF (LI.1.DIST != LI.2.DIST) LIST='Distances Differ for link:', LIST=A(5) B(6), FORM=6.2, LI.1.DIST, LI.2.DIST ENDPHASE
REPORT
Defines report specifications. ALL CAPACITY DEADLINKS DUPLICATES FILEI FILEO INPUT MERGE SPEED UNCONNECTED
REP
REPORT keywords
Keyword ALL CAPACITY DEADLINKS |?| |?| |?| Description Set all the following reports to this value (not usually recommended). Default value is F. Capacity tables. Default value is F. Links that are missing either an entry or exit link. Such links cannot be used by any path processing. Additional file processing may be required. Default value is F. Duplicate links that are detected during PHASE=INPUT. Default value is F. Internal specifications for the input files (use for debugging only). Default value is F. Internal specifications for the allocation of output variables use for debugging only). Default value is F. Summary statistics following input phases. Default value is F. Summary statistics following every phase. Default value is T. Speed tables. Default value is F. List of zones that do not have links into and out of them. Default value is T.
DUPLICATES FILEI FILEO INPUT MERGE SPEED UNCONNECTED
|?| |?| |?| |?| |?| |?| |?|
All reports must be specified with a logical value of true or false. The default value is true.
Example
REPORT FILEI=Y, FILEO=Y; normally not specified. REPORT SPEED=Y, UNCONNECTED=N REPORT ALL=true, fileo=false, filei=false
SORT
Sorts user-defined arrays. ARRAY NUMRECS See SORT on page 72 for more information about this standard Cube Voyager statement.
Example
ARRAY AN=LINKS, BN=LINKS, VMT=LINKS ; NETI must be a binary network PHASE=LINKMERGE _L = _L + 1 AN[_L] = A BN[_L] = B VMT[_L] = V_1 * DISTANCE ENDPHASE /* note: The User has to keep count of the records entered into the arrays If links are deleted, the number of entries will be less than the original number number of links. */ PHASE=SUMMARY SORT ARRAY=-VMT, AN,BN, NUMRECS=_L LOOP _K=1,30 ; only want to see the highest 30 LIST=AN[_K](6),BN[_K](6),VMT[_K](10.2c) ENDLOOP ENDPHASE
SPDCAP
Revises speed and capacity tables. CAPACITY LANES SPEED
SPDCAP keywords
Keyword CAPACITY |RV*99| Description Capacity in vehicles per lane per hour. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. All values must be 0-9999, inclusive. The capacity array is initialized to 20 times the index number, for all lane stratification (CAPACITY[1]=20, CAPACITY[2]=40...). Lane stratification that any following CAPACITY and/or SPEED values are to apply to. LANES may be interspersed with other keywords and values on the statement. All values must be 1-9, inclusive. Speed to be applied to the link. All values must be 0-3276.7, inclusive. The speed array is initialized to the index number, for all lane stratification (SPEED[1...99]=1,2,...99). Speed is maintained with one decimal place.
LANES
|IV|
SPEED
|RV*99|
A network contains an array of capacity and speed data. Each array is dimensioned with ninety-nine values for each of nine lane stratification, and contains 891 values. When an array is accessed, the program uses the number of lanes (LANES) as the row index, and the capacity and/or speed classification (CAPCLASS, SPDCLASS) as the column index to obtain a value for a link. If CAPACITY or SPEED is encountered prior to a LANES keyword on the statement, LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector data, and may be indexed to set a specific loading place, and may have null fields to skip the revision of certain columns. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables.
Example
;Set entire table to 50, ; then revise the values for 20,21, and 24 for lanes 1,3,8 SPDCAP CAPACITY=99*50, LANES=1,3,8, CAPACITY[20]=300,400,,,700 SPDCAP LANES=2,4-9, SPEED=20.5,30.3,50.6,,,88.2, LANES=5,SPEED[15]=15 SPDCAP SPEED=30, LANES=2-8; Inappropriate; the LANES will not be used.
Network Program Theory
Theory
This section describes the theory used by the Network program. Topics include: Phase descriptions Variable referencing Output variables Plotting
Phase descriptions
The program processes the input files in separate phases, which are listed below. For most applications, the user need not be concerned with process phases; they are used only when special processing is to be undertaken. In general, the user must code operational statements within a PROCESS PHASE block defined for each phase. There may be only one block for each phase, and the order of the blocks in the input is not crucial. It is suggested that for readability and ease of editing, the phase blocks be defined in the normal process order. Only statements that specifically apply to the phase should be coded within the block. However, statements that are not dynamic operations, but that appear within a phase block will be recognized as such and will be processed properly. A block should be terminated with an ENDPROCESS statement. If another PROCESS PHASE statement is encountered before an ENDPROCESS statement, the previous block is terminated, and the new block is begun. The basic phases are: INPUT phase Read ASCII and DBF files, re-code values from any input files specifically designated. NODEMERGE phase Read all node data and organize it LINKMERGE phase Read all link data and process it (main phase)
SUMMARY phase Report results of LINKMERGE phase
There need not be a specific PROCESS PHASE for LINKMERGE, because it is anticipated that most applications will be functioning in only this phase. If an operational statement is encountered, and it is not within a PROCESS block, it is tagged as being in the LINKMERGE phase. A PROCESS PHASE=LINKMERGE statement may be coded, but it is not mandatory. Internally, the program processes the phases in the order in which they are described below. As it processes each phase, it determines the files that must be processed in that phase, and processes them. If there are no relevant files for an INPUT phase, the phase is bypassed. As the program processes each file record, it applies any phase operations that the user has designated for the phase.
INPUT phase
All ASCII and DBF files must pass through this phase. The records are processed and edited for errors and duplication. The user may specify selections and computations to be applied to each record as it is processed. It is possible to re-code node numbers in this phase. Binary input files are processed in this phase only if the user has specifically designated the file through the use of a PROCESS PHASE=INPUT block. Any file (or file segment) that passes through this phase, is no longer used in its original format after this phase is completed; but its data are used in subsequent phases in a revised internal format. The file segment records are sorted in appropriate order (node or link) before being stored in the revised format.
NODEMERGE phase
The node based records from all the NODEI files must pass this phase. As in the INPUT phase, the user may specify computations and/or selections to be applied to each node record as it is processed. It is not permissible to re-code node numbers in this phase. The resulting record for each unique node is written to the output network, and saved for subsequent referencing in the LINKMERGE phase.
LINKMERGE phase
The link based records from all the LINKI files must pass through this phase. As in the above phases. the user may specify selections and computations to each link record as it is processed. This is the phase that most users are mostly interested in. Records can be deleted, summarized, tabulated, and extracted to an external device or file. Node based data can be accessed during the link processing. Tabulated and summarized data is reported at the end of the phase, and, in most cases, passed onto the final phase.
SUMMARY phase
In this phase, certain post-processing operations can be performed. This is generally restricted to computations on working variables, usually to obtain averages, etc. Every record is processed according to the purpose of the current phase. If there are operations to be performed in the phase, the record is processed against the operation statements designated by the user. Operation statements are generally expressed in the standard IF/ELSEIF/ELSE block and COMP statements. These and other operations available to the user are described in Control statements on page 334. In the NODEMERGE phase, a node record is processed for each unique node from the NODEI files. If a node is re-coded in the INPUT phase, the re-coded node number is included. In the LINKMERGE phase, a link record is processed for each unique link found from the LINKI files. If a link is recoded in the INPUT phase, the recoded link is included.
Variable referencing
The main logic of the program involves processing variables. A variable name may be up to 15 characters in length, and may consist of only letters, digits, and the underscore character. The first character of the name may not be a digit. If the first character of a name is an underscore (_), the variable is only a local working variable, and will not be included in the network. Variables are usually classified as either node or link based. Classification
depends upon the process phase in which the variable is referenced. If a new variable is computed (NEWVAR=...), it will be attached as either a node or link variable. During any INPUT phases, the variables will be associated with the type of file being processed. During the NODEMERGE phase, the variables are node based. During the LINKMERGE phase, variables are link based, but node variables can be referenced. A node variable is referenced during LINKMERGE as either A.name or B.name. If a variable from an input file is to be referenced during NODEMERGE or LINKMERGE, the associated NODEI or LINKI file number must precede the variable name. For NODEMERGE the prefix is NI.#., and for LINKMERGE the prefix is LI.#. For example: LI.3.ABC references the variable ABC from the LINKI[3] file. The program establishes a buffer for a record from each input file for every record in the phase, and the prefix allows access to each of those buffers. If there is no input record for the current working record, the values are all zero. The formal designation for the prefix is LI.#., but the program allows the following variations: For node records: NI.#.name* NI#.name N.#.name N#.name For link records: LI.#.name* LI#.name L.#.name L#.name
*The preferred method of designation. Another type of variable is the working variable. Working variables are variables that are to be used for intermediate storage, and will not be part of an output network. They are distinguished by their first letter, which must be an underscore. Working variables are set to zero at the beginning of the application, and are changed only by user statements. If there is a user SUMMARY phase, every variable referenced within the SUMMARY block is a working variable, unless it is the same as a link variable. If it matches a link variable, the variable from the last link will be processed. Working
variables allow the user to accumulate statistics during link processing, and to then compute and print summaries at the end of processing.
NOTE: In some situations, a PRINT LIST variable may not be
recognized if it is cross-referenced. For example: LIST=A,B,A.X,B.X may not be accepted. To be sure, node based variables to be listed should be set into temporary variables and then listed with that name. (See Examples on page 387 for an illustration.)
Example
_vdiff = L1.vol - L2.vol; get assignment differences _vcnt = _vcnt + 1 if (_vdiff != 0) _sumsqdiff = _sumsqdiff + _vdiff*_vdiff . . Phase=SUMMARY if (_vcnt > 1) RMSV = sqrt(_sumsqdiff / _vcnt); possibly (_vcnt-1) list = 'RMSV =', RMSV endif Phase=LINKMERGE _ax = a.x ; get the Node variable named X for Node A _ay = a.y LIST=a,b,_ax,_ay EndPhase
Output variables
During the merge phases, a work record is generated for each unique record that appears in all the input files (depending upon the value of the MERGE RECORD keyword). Each work record will contain all the unique variables that are defined in/for all the input files and any COMP statements for the phase. The value that is stored for each variable is controlled by the MERGE control statement. If all the variables are not to be included in the output network, the variable list can be modified on the FILEO statement.
Plotting
The network that is formed during the LINKMERGE phase can be plotted by sending information to a standard Windows printer device. There must be an appropriate printer device driver for the media where the network is to be plotted. Typical types of drivers are available for printers, faxes, raster plotters, and pen plotters. The Network program uses the Windows driver to perform the actual formatting of the network information. Many default drivers come with Windows and provide considerable capabilities. This process provides for current and future flexibility. It is possible to directly fax a network plot to a facsimile machine. Windows operating systems are geared towards more recent technology, so pen plotters are being left somewhat behind. They do cause some problems. Pen plotter problems: The standard Windows drivers for pen plotters do not seem to function properly; in particular, they do not always write text at the proper location and angle. There are thirdparty software drivers available that correct this problem, but deficiencies have been reported in these systems, as well. With one driver (WinPlus), if legends are used, the link posting will be oriented properly, but mis-positioned. This release of the program does not address these driver deficiencies; perhaps later versions will internally rectify them. Plotting pens are selected by RGB (RedGreenBlue) standards, so it becomes the responsibility of the user to ensure that the colors that are selected correspond with the pens on the plotter. If standard colors are used (red, green, blue, yellow, etc.), there should be no problems. If esoteric colors are requested, color correspondence is not guaranteed. If roll size is selected in the device driver, the program may not be able to properly scale the plot. In those cases, the user must specify the desired plate size. It is recommended that if pen plotters are to be used that the WinPlus driver be obtained and installed as a printer driver and that the PLOTTER statement contains no LEGEND keywords.
A PLOTTER control statement is used to define the plotting system and the parameters for performing the plot. PLOT statements processed during LINKMERGE determine what will be plotted from the network. If there are PLOT statements, but no PLOTTER statement, the program will fatally terminate; the opposite is not an error. The PLOTTER statement contains information about: The plotting device name, and whether the output is to be sent directly to the plotting device, or to a file. The logical layout of the plot plate on a sheet of the plotter device: the desired size, if different than the driver provided size, and the margins to place the plate within the driver provided dimensions. The optional network window for selection, and optional scaling. The headers and footers to be printed on the plot. Legends that can be displayed in the corners of the plotting window. The link variables that are to be posted when a link is selected for posting. The node variables that are to be posted, when a node is selected for posting. Bandwidths and type of fill and end tapers.
In general, all text that is to be plotted can have its font, color and size specified by the user. The default values for each of these are: ARIAL, black, 0.10. All sizes are specified in inches, so that if a different driver is used, the text would still be readable. Link posting (writing text along a link) can not be varied by link; if a link is posted, its posting will contain the same type of information at the same size and font as any other link that is posted. The user controls the color of link posts; individual variables can not be colored differently. Node posting (writing text near a node) will always post the same variables, but the size and color is controlled by PLOT statements.
Before performing a plot, the device driver must be properly installed. This is done by left clicking the Windows Start button and choosing Printers and Faxes. In the Printers and Faxes window, click Add a printer and follow standard installation processes. The orientation of the plot, (portrait, landscape) is set in the device. If a device is not attached directly to the computer, the driver should have the file option specified, and the PLOTTER DEVICE FILE value (filename) should be specified. Files are generally processed by copying them directly to the plotter port.
PLOT statements control actual plotting. If a PLOT statement is processed in LINKMERGE, the current link is flagged for processing by the plotting process. The following processes are considered:
Process DrawLink LinkPost DrawA NodePost Description Draw the link as specified. Post variables for the link. Draw a specified symbol for the Anode of the link Post variables at the A node.
These values can be specified multiple times for each link; the values that are current at the end of the link are used for plotting. For node processing, the values that are current following the last link outbound from a node are used. If the PLOT statement is invoked by the use of one of these trigger keywords, it may be placed on a short IF statement. Example: IF (...) DrawLink=red, LinkPost=red. If a keyword specifies plotting, but then later conditions determine that it should not really be plotted, the keyword can be nullified by setting its value to -1. Example: NodePost=-1. Many times a link posting may be too long for the link. You can deal with these situations by specifying the fourth value for PLOTTER POSTLINKVAR FONT.
Network Program Examples
Examples
This section contains examples of the Network program: Listing links to the print file Merging link records from multiple ASCII files Dumping link and node records to DBF files excluding select fields Building network from inline data records Simple link plot Complex plot
Listing links to the print file

run pgm=NETWORK ; List the links in a network neti=demo20.net list=a,b endrun
Merging link records from multiple ASCII files

run pgm=NETWORK ; merge two ASCII files with different links linki[1]=demo07.dat,var=a,2,4, b,7,4, dist,14,4, v1,2,4, v2,2,4 linki[3]=demo07m.dat,rev=2, var=a,2,4, b,7,4, dist2,14,4, rev,35,1, v1,2,4, v2,2,4 nodei[1]=c:\demo\demoxy.dat,var=n,x,y merge record=true, AVE=dist report all=no zones=19 phase=LINKMERGE if (li.1.a == 0) list=' LI[1] missing link:', a,b if (li.3.a == 0) list=' LI[3] missing link:' a,b endphase endrun
Dumping link and node records to DBF files excluding select fields
run pgm=NETWORK ; write DBFs for nodes and links, ; but exclude many variables from input
neti=test.Hnt neto=test.tpn, EXCLUDE= SCENARIO STATUS NAME TPCAP1 TPCAP2 TIPRTP CNT, EXCLUDE= FIELDOPT TCNUMBER COUNTY USER DATE OCOUNTA OCOUNTP, EXCLUDE= OCOUNTD OSPEEDA OSPEEDP OSPEEDD, EXCLUDE= OSPEEDX OSPEEDY ECOUNTA ECOUNTP ECOUNTD ECOUNTY, EXCLUDE= ESPEEDA ESPEEDP ESPEEDD ESPEEDY COMMENT6 COMMENT1, EXCLUDE= ATYPE nodeo=testxy linko=testld if (STATUS=='D' || ft==15) delete endrun run pgm=NETWORK ;now look at the results from the link DBF linki=testld.dbf nodei=testxy.dbf,exclude=xcoor,ycoor If (a>b && lanes > 4) list=a,b,lanes endrun
Building network from inline data records

copy file=3pth.lxy ; copy data from inline to a file LD 1 1 10 1000 60 60 4 1 S23456 2 1 11 2000 60 60 8 1 3 1 12 2500 60 60 6 1 4 10 2 0 0 60 4 1 5 11 2 0 0 60 8 1 6 12 2 0 0 60 6 1 XY 1 1 100 200 2 10 200 300 3 11 200 200 4 12 200 100 5 2 300 200 endcopy id=this is my ID... pagewidth=80 RUN PGM=NETWORK ; now build a network from the inline data merge record=y nodes=20 zones=2 nodei[3]=3pth.lxy,var=n1,n,x,y, start=(substr(record,1,2)=='XY'), stop=(substr(record,1,2)=='LD') linki[2]=3pth.lxy,var=n3,a,b,dist,tsva1,spdc1,capc1,lane1,string1,typ=a, start=(substr(record,1,2)=='LD') ,
stop=(substr(record,1,2)=='XY') list=a,b,dist endrun
Simple link plot

; Sample Quickie plot with no parameters: draw links only RUN PGM=NETWORK ; sample quick link plot NETI = C:\DEMO\DEMO20.DAT PLOTTER DEVICE = "HP 7475A", FILE=f:\sample.plt DRAWLINK=0xffff ENDRUN
Complex plot
;This sample illustrates various capabilities of plotting. RUN PGM=NETWORK NETI = C:\DEMO\DEMO20.DAT PLOTTER { ; SETUP Plotter DEVICE="HP LASERJET 4" POSTLINKVAR=A,B,_AB,_STR FONT='COURIER',0.10,YELLOW,BOLD POST=AUTOSIZE(.05) POSTNODEVAR=A, FONT='COURIER',.10 LINKOFFSET=0.01 BANDWIDTH=_BANDWIDTH FILL=SOLID TAPER=45 HEADER= "This is header 1", "This is header 2", align=center, font='courier' ,0.1,green FOOTER="Footer 1" FOOTER[3]="Footer 3" FOOTER[5]='Shows various date tokens: [date] [idate]' FOOTER[7]='Shows various time tokens: [time] [times]', FOOTER[7]='Shows window and scale tokens: [window] [scale]' align=right font='Courier',0.15,green LEGEND=TopLeft, font='courier',.10,blue,italics, LINE[1]=TL.LINE1,symbol=triangle,.15,red LINE[5]=tl.line5,symbol=Dash,.15,red LEGEND=TR, font='courier',.20,blue,italics, LINE[1]=TR.LINE1,symbol=triangle,.5,red LINE[3]=tr.TRne3,symbol=rectangle,.08,red LEGEND=3, font='courier',.10,red,italics, LINE[1]=BL.LINE1,symbol=circle,.10,red LINE[5]=BL.line5,symbol=dashdot,.15,red LEGEND=BottomRight font='courier',.15,purple,italics,
LINE[2]=BR.LINE2,symbol=triangle,.15,red } ; Plotting Controls if (a<=19 || b<=19) _BANDWIDTH = lane/10 _AB = A*100 + B _STR = str(_ab/100,5,2) DRAWLINK=RED,,SOLID, LINKPOST=GREEN IF (A.X == B.X || A.Y == B.Y) LINKPOST=BLUE; FLAT|VERTICAL LINES DRAWA=BLUE,0.20,CIRCLE,YELLOW NODEPOST=r123b220g100,.1 IF (A>=30 && A <40) LINK=GREEN,,DASH ; reset the color of these links ; set node postings and symbols IF (A<=5) DRAWA=RED,0.10,CIRCLE,WHITE NODEPOST=0XFF00FF IF (A>5 && A<=10) DRAWA=RED ,0.40 CIRCLE NODEPOST=G255 IF (A>10 && A<20) DRAWA=R255,0.15,RECTANGLE,BLACK NODEPOST=R255 ENDRUN
Matrix Program
This chapter describes the Matrix program. Topics include: Using the Matrix program Control statements Examples
Matrix Program Using the Matrix program
Using the Matrix program

This section provides information for using the Matrix program. Topics include: Introduction to the Matrix program Control statement types in Matrix program Working with intrazonal cells of a matrix Working with lists of zones Working with RECI/RECO processing in v4.0 and beyond Working with logit choice models
Introduction to the Matrix program

The Matrix program processes zonal data and matrices according to specified expressions. Zonal data and matrices can be input, and matrices and reports can be output. Various file formats for both input and output are supported. There are no default processes; it is the users responsibility to specify what is to be accomplished. This program is also used when invoked as a special function via RUN PGM= FRATAR, GENERATION, or DISTRIBUTION. It is used for the following purposes: Computation of new matrix values Trip distribution (called by Distribution program) Trip generation (called by Generation program) Converting and merging matrices between various formats Reporting values from matrices and zonal data: Selected rows Marginal summaries (trip ends, etc.) Frequency distributions User formatted files
Transposing matrices Generating matrices Renumbering, aggregating, and disaggregrating matrices
Almost any and all of the above processes can be performed in a single application. There are some restrictions when used as a special function (Fratar, Distribution, and Generation programs). The program processes within an overall origin zone loop controlled by the variable named I. The remainder of this document refers to this loop as the I loop. The loop begins with I set to one and continues monotonically until the highest zone number is processed. When Matrix is called by Distribution, I-loops are nested within iteration loops. (See Chapter 6, Highway Program, for details.) The standard input is comprised of definition, computational, reporting, and flow control statements (illustrated below). Definition statements are those that define the input and out files, and are, in most cases, processed outside of the I loop. Computational statements are those that cause data to be revised. Flow control statements provide the capability to iterate through portions and conditionally or unconditionally branch to a different place, within the I loop. When all control statements have been checked for basic syntax, and have been stored in the control stack, the program builds a list of required variables. The input files are opened; zonal data files are read and stored, and other housekeeping is performed. If any input matrices need to be transposed, they are transformed to a single file and made ready for subsequent retrieval. It then starts the I loop, reads the matrices for I, and processes the control stack from the beginning. When the end of the stack is reached, the program performs some end-of-zone summaries, and writes any matrices requested. When the I loop completes (or is terminated), any requested reports are printed, and the program exits.
All variables are initialized to zero (or blank) before the I loop, and are thereafter altered only by computational statements or internal processing. In addition to any variables explicitly specified by the users, there are certain built-in variables that can be referenced. The built-in variable are usually protected; the user is not allowed to alter their values. Subsequent topics discuss: Built-in variables Built-in functions Transposed matrices
Built-in variables
Matrix program built-in variables
Variable FIRSTZONE Description Stores the zone number of the first zone being processed. In a normal run this is 1. Under intrastep distributed processing with Cube Cluster, this is the first zone number of the zones to be processed on the current Cube Cluster node. The current row zone. The iteration number; usually 1. A column index, usually 1, and varies (1-Zones) for MW[] and LOOPs. Stores the last zone number to be processed. In a normal run this would be the same as ZONES. Under intrastep distributed processing with Cube Cluster, this is the highest zone number to be processed on the current Cube Cluster node. Result of LOWEST(); A work matrix; see COMP on page 460 for more details. Holds the number of fields on the input record file. Holds the number of records in the input record file. Holds the record number of the current record being processed from the input record file.
I ITERATION J LASTZONE
LOWCNT MW[] RECI.NUMFIELD RECI.NUMRECORDS RECI.RECERR RECI.RECNO
Matrix program built-in variables (continued)

Variable THISPROCESS Description Contains the process number of the current process when using intrastep distributed processing under Cube Cluster. A copy of I. Number of zones.
Z ZONES
Built-in functions
Described in more detail in COMP on page 460.
Matrix program built-in functions
Function ARRAYSUM() LOWEST() MATVAL() ROWADD() ROWAVE() ROWCNT() ROWDIV() ROWFAC() ROWFIX() ROWMAX() ROWMIN() ROWMPY() ROWSUM() Description Returns the value of the sum of an arrays values. Sum lowest valued cells in a row. Allow random access to values from MATIs Add matrices. Average cell value where value!=0 Number of cells whose values != 0 Divide one matrix by another. Factors the row by fac. Integerize mw (start at column intrazonal + 1) Maximum value in the row. Minimum value in the row. Multiply one matrix by another. Row total
Transposed matrices
A copy of a transposed input is obtained by referencing a variable with a name of MI.n.nameT. In Matrix program terminology, a transposed matrix is one that has had its rows and columns switched. See COMP on page 460 for details.
Control statement types in Matrix program

There are several types of control statements used in the Matrix program:
Definition statements Define static processes.
ARRAY FILEI and FILEO (which define the input and output data.) LOOKUP PARAMETERS RENUMBER
Computational statements Cause variable values to be
updated. BSEARCH CALL CHOICE COMP FREQUENCY SET XCHOICE

Reporting statements Cause values to be accumulated
and/or displayed dynamically. FREQUENCY PRINT PRINTROW REPORT

Flow control statements Set which statement is to be
performed next. GOTO :label
BREAK CONTINUE LOOP ENDLOOP JLOOP ENDJLOOP IF ELSEIF ELSE ENDIF EXIT For more details about control statements, see Control statements on page 436.
Working with intrazonal cells of a matrix

During the processing of demand data it is often necessary to access the intrazonal element of a matrix or to set its value. Special keywords INTRAZONAL or INTRA are provided to assist in this. To set the intrazonal element of a matrix row, the normal COMP command is amended to take one of the following forms:
INTRAZONAL MW[] = expression COMP MW[][INTRAZONAL] = expression COMP MW[][INTRA] = expression
where the appropriate working matrix number is inserted into the []. When such commands are executed, all elements of the matrix which lie off the diagonal are left unchanged. Note that it is invalid to use the above forms of calculation with a JLOOP (as JLOOP implies varying the j, or column, whereas INTRAZONAL or INTRA fixes it to i, or the row index). Neither can it be used with the INCLUDE or EXCLUDE subkeywords of the M[] statement, which are used to select destination zones. Such commands may be used in conjunction with the LOWEST function set an intrazonal cost based on the cost to the nearest zone(s). As an example:
INTRAZONAL mw[10] = 0 INTRAZONAL mw[10] = LOWEST(10, 1, 0.01, 99999)
sets the intrazonal cost to the cost from the origin to the nearest destination, but ignoring destinations with costs less than 0.01 or more than 99999. The preceding setting of MW[10]s intrazonal cell to zero ensures that any starting value in that cell does not become the result of the LOWEST function. The INTRAZONAL or INTRA keywords may be used to access the diagonal element of a matrix during calculations. This keyword is coded in a similar manner to the j (or column) position when a matrix is referenced in an arithmetic expression. Examples are:
MW[1] = MW[1][INTRA]
which copies the intrazonal (or diagonal) element of the first working matrix into all column positions, and:
var1 = MW[10][INTRAZONAL]
which sets a scalar variable var1 to the intrazonal element of working matrix ten, taken from the current row of the matrix.
Working with lists of zones

When modeling travel demand, it is often necessary to apply different treatments to various types of zones, and similarly to movement types within matrices. Examples of such zone groupings are the CBD (central business district), industrial zones, the suburbs, or zones corresponding to external cordon points. Any of these areas comprises a list of zone numbers; lists which are lengthy and used on many occasions in processing could easily be a source of errors in typing or updating. To avoid such difficulties, such lists of zones may be set up once, given a suitable descriptive name to identify them, and then used wherever appropriate in the modeling. This section outlines two methods: Working with lists of zones using the INLIST function Uses the INLIST function to select required zones; it is simple to define lists, but their use is restricted to arithmetic computations.
Working with list of zones using the substitution method Defines lists in the Pilot program, then uses the substitution facility to work with them; it is less easy to define the required lists, but they may be used in a wider range of contexts.
Working with lists of zones using the INLIST function

As an example, zones 1 to 12 and 15 to 20 form the CBD of a study area. A list called CBD may be defined, using the COMP or computation control statement. The list of zones is specified as text data which is enclosed in quotes ('). The INLIST function is then used to construct a condition which determines whether its origin and/or destination are in the specified list. The INLIST function gives a value of 1 when the particular zone (first parameter) is found in the specified list (the second parameter). The particular zone under consideration is often i (the origin zone) or j (the destination zone). The following example illustrates the use of this facility:
CBD='1-12,15-20' suburbs='23-30,34-41,43,47,50-57' ... IF (INLIST(i,CBD) = 1) ; commands here will be processed for origins in the CBD .... ENDIF .... JLOOP IF (INLIST (j,suburbs) = 1) ; commands here processed for destinations in the suburbs .... ENDIF ENDJLOOP IF (INLIST(i,suburbs) = 1) JLOOP IF(INLIST(j,CBD)=1) ; commands are processed for flows which have both ; origins in suburbs and destinations in CBD .... ENDIF ENDJLOOP ENDIF
Working with list of zones using the substitution method

As an example, zones 1 to 12 and 15 to 20 form the CBD of a study area. A list called CBD may be defined, using the COMP or computation control statement. The list of zones is specified as text data which is enclosed in quotes ('). This is done in the script before any RUN PGM statements for programs, and forms part of the script of the Pilot program. Wherever this list of zones is required by a program, its script contains the name of the list, which is enclosed by @ symbols (denoting substitution of the list of zone numbers, in place of the lists name). The example:
CBD='1-12,15-20' ... RUN PGM = MATRIX ... MX[10]=mi.1.LOSmatrix ... JLOOP INCLUDE = @CBD@ MX[10] = MX[10] + 10 ENDJLOOP ... ... ENDRUN
defines the list of zones in the CBD, then adds a parking cost of 10 units into the skim (or level of service) matrix for destination zones in that area. The defined list may contain individual zone numbers and / or ranges of zone numbers; the latter are specified in the form 1-10 with neither space or ',' (comma) between the start and end values. To ensure that the list is generally acceptable, it should be written with commas between items. (Although Cube Voyager scripting allows spaces to be used as delimiters between items of a list, this form is not accepted by the conditional or IF statement which requires commas, and so use of commas is recommended.) A further example changes that part of a matrix which corresponds to origins in the suburbs and destinations in the CBD, dividing these matrix cells by 1.05:
...
suburbs = '100-145,148-191,194-224,227-341' CBD = '1-12,15-20' ... RUN PGM = MATRIX ... if(i = @suburbs@) jloop if(j = @CBD@) mw[1]=mw[1]/1.05 endif endjloop endif ... ... ENDRUN
The calculation may be expressed more concisely as:

if(i = @suburbs@) jloop include = @CBD@ mw[1]=mw[1]/1.05 endjloop endif
or even:
if(i = @suburbs@) mw[1]=mw[1]/1.05 include=@CBD@
The following illustrates the case where the calculation applies to all destination zones for selected origins:
... CordonZones = '540-578' ... RUN PGM = MATRIX ... if(i = @CordonZones@)mw[5]=mw[5] * 1.27 ... ENDRUN
Working with RECI/RECO processing in v4.0 and beyond

Substantial changes have been made in dealing with RECI text (non-DBF) files in versions later than 3.2.x. There were several reasons for these changes: Earlier versions had used the keyword FLD to define data fields. This was inconsistent with most other text file processing where FIELDS was used; so FLD has been decommissioned and replaced with FIELDS. For backward compatibility, script references to RI.FLD[] will act the same and be treated as if RECI.NFIELD[] were coded. New scripts developed after version 3.2.x should reference RECI.NFIELD[]. The earlier versions could deal with only numeric data fields; v4.0 can and later versions can deal with both numeric and character data fields. To incorporate these changes, the entire structure of RECI for text processing had to be completely rewritten. This has rendered older setups unusable, a practice that we generally do not like to condone, but necessary in this situation. We have attempted to minimize these impacts by making program changes such that the only possible change to user script files can be made with simple global search and replace commands in a text editor. There are two forms of text records that have to be dealt with: fixed format and delimited. These forms can not be intermixed in the same record processing step of the Matrix program. The way that the program distinguishes between the two is by the way the data fields are defined in the script. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi), that sets the format as fixed. If a data field is defined by a single number (field number on the records), that sets the format as freeform. All data fields MUST be defined in the same format. All data fields can optionally be defined as character mode (C) or numeric mode (N), with N being the default mode. If the data field is being defined via the name= format, the mode can be appended to the name: ORGZONE(N)= STREET(C)=. If the data fields are being
defined via the FIELDS= format, the mode can be appended to the end of the field definition: FIELDS=1-3(C) for fixed format, or FIELDS=1(N). For every FIELD, there will be two values: a numeric value and a character value. They are referenced as RECI.NFIELD[x] and RECI.CFIELD[x]. If the field is defined as numeric, its parallel character RECI.CFIELD[] value will be blank. Conversely, for all character variables, the parallel RECI.NFIELD[] value will be zero. To define a number of data fields when the user does not wish to have uniquely specified names for all fields, the FIELDS= format is used. FIELDS=6,9,13 will define variables RI.FIELD1, RI.FIELD2, RI.FIELD3 coming from data fields number 6, 9, 13 respectively. These variables can also be referenced as: RECI.NFIELD[3] RECI.NFIELD[2] RECI.NFIELD[3]. Optionally, FIELDS can specify multiple successive fields with a single specification (providing all are the same mode). FIELDS=6(7) specifies that RI.FIELD1RI.FIELD7 will be obtained from fields 6 through 13 of the data records. FIELDS=6(C7) would be the same, but those fields would all be character values. For fixed format, FIELDS=1-5(10), would define variables 10 variables: RI.FIELD1RI.FIELD10, and RECI.NFIELD[1-10]. FIELDS=15(C10) would establish the RI.FIELDs as character, and would cause population of RECI.CFIELD[1-10]. RI.FIELD2 would be obtained from columns 6-10, RI.FIELD3 would be from 11-15, etc. FIELDS=21-22(7) would generate RI.FIELD1-7 with the values coming from columns 21-22, 23-24,25-26 If FIELDS= and name= are intermixed, the monotonic index for FIELDS continues with the next FIELDS value. FIELDS=1,2,3, Var4=4, var5=5, Var6(C)=10, FIELDS=11(5) will generate RI.FIELD1 through RI.FIELD8 (and RECI.xFIELD[1-8]). FIELDS= may be specified multiple times, with, or without multiple definitions. FIELDS=1,2,3,6(3), FIELDS=22(C3) will cause RI.FIELD1 RI.FIELD9 to be obtained from data fields 1,2,3,6,7,8,22,23,24. In addition, RECI.NFIELD[1-9] and RECI.CFIELD[1-9] will be defined. However, RECI.NFIELD[7-9] will all be zero, and RECI.CFIELD[1-6] will be blank.
Application script running under earlier versions that did not have this capability will have to be revised. The basic revisions required are: If FLD= specification (which indicated fixed format records) was used, several revisions are required. If the old script had FLD[3]=3, FLD[10]=10, RI.FLD[3] was obtained from column 3 of the data record and RI.FLD[10] was obtained from column 10. This will have to be revised to FIELDS=0-0,0-0,3-3,0-0,0-0,0-0,0-0,0-0,10-10. Any references to RI.FLD[x] should be revised to RECI.NFIELD[x], or to RI.FIELDx. In addition, if name= was specified, and the definition was a single field (not lo-hi), the definition will have to be changed to lo-lo; for example: INCOME=3 will have to become INCOME=3-3 If FLD= was not specified (free format) and no name= was specified, the program estimated the number of variables (n) on the record and generated variables RI.FLD[1]RI.FLD[n]. This can not be duplicated in this version; the user must specify the maximum number of variables to be obtained from any data record (judicious over estimation should not cause any problems). If the highest field to be referenced is 15, then FIELDS=1(15) should be specified. Any references to RI.FLD[x] must be revised to RECI.NFIELD[x], or to RI.FIELDx. In general, all references to RI.FLD should be changed to RECI.NFIELD. This can usually be done quite easily with any editor with search and replace capabilities.
Working with logit choice models

This section discusses logit choice models. Topics include: Introduction to choice modeling Absolute logit model Incremental logit model Hierarchical logit model Destination choice
Mode and destination choice General notes
Introduction to choice modeling

Beginning with version 4.1 of Cube Voyager, the XCHOICE control statement replaces the CHOICE control statement for implementing logit choice models. XCHOICE implements the same logit model structures as the original CHOICE statement but improves choicemodel run times. A choice model implemented with XCHOICE should run significantly faster than the same model implemented with CHOICE. The CHOICE command statement continues to function as in prior versions. Existing choice models that use the CHOICE statement will continue to run as scripted. However, Citilabs recommends modifying existing models to use the XCHOICE command statement and take advantage of the improvements in run time. Use the XCHOICE command statement whenever developing new choice models in the Matrix program. Note that some of the keywords are different with the XCHOICE command statement. When converting a logit model that uses CHOICE to use XCHOICE, you must make additional changes at the keyword level. For detailed changes please refer to XCHOICE on page 451. The XCHOICE (CHOICE prior to v4.1) command in Cube Voyager scripting provides powerful extensions to the core language designed to allow complex logit choice models to be specified easily. Logit choice models have a number of distinct possible outcomes (for example mode of travel), and the model estimates the probability of choosing each particular outcome. The alternatives are evaluated using either their costs or their utility values. Costs and utilities are related. As the utility of an alternative increases the alternative becomes more attractive, but an increase in cost makes the alternative less attractive. Apart from sign, the other difference is that a utility directly measures the users benefit, whereas the cost has to be multiplied by an appropriate coefficient (or scale parameter) before use in choice models.
The simplest choice model splits total travel demand between two alternatives (or modes); it is known as the binary choice model. This may be extended by adding further alternatives, so forming a multinomial model. In practice when several alternatives exist, the alternatives are not always independent of each other. To overcome this hierarchic choice models are used which sub-divide the choice process into a sequence of decisions. Alternatives which are similar are grouped together to form sub-nests. Typical examples of sub-nests are public transport (which brings together various transit modes), or car use (which includes through-trip by car and park-and-ride). These sub-nests are then brought together in the main (or toplevel) choice process. The choice process may be viewed as initially choosing between sub-nests (representing types of travel), and then choice at the sub-nest level which decides the mode used. The simple choice and hierarchic models described above are forms of the absolute logit choice model. An alternative form is the Incremental model (also known as the Pivot Point model) which has a different methodology. It uses data for demand (by alternative) in the base situation together with changes in costs (or utilities) between the base and forecast scenario, in order to re-allocate the demand between the alternatives in response to those cost changes. The destination choice model is an extension to the logit choice concept where the alternatives are not modes of travel, but destination zones which the traveler chooses between. It may be combined with mode choice to form complex models, and may be used in absolute or incremental form. The section uses a number of examples to illustrate use of the CHOICE command and to explain the underlying theory. The examples start at the simplest level and increase in complexity. They are: Absolute logit model Incremental logit model
Hierarchical logit model Destination choice Mode and destination choice
Each model is described in the context of a typical problem, supported with the relevant theory. Then the method for implementing a solution in the Matrix program is shown, with example scripts. For some models, alternative strategies or more complex variations are also illustrated. Finally, any practical issues related to setting up such a model are discussed. At the end of the section there are some general notes concerning coding of demand models. For a detailed description of the demand modeling function syntax see XCHOICE on page 451.
Absolute logit model

This section discusses the absolute logit model. Topics include: Introduction Logit Choice model Scale parameter (cost-based models) Matrix script for cost-based model Matrix script for utility-based model
Introduction
This section introduces a straightforward example of an aggregate demand model. Suppose that in a transport system there are just two discrete competing modescar and public transport (PT)
between a given set of origins and destinations. A user of such a system is said to have a binary choice, because there are just two alternatives (car and PT).
Structure of absolute logit model
The following paragraphs explain how the absolute logit model can be applied to the problem of estimating the probability of choosing each mode, and in particular how this is implemented in Cube Voyager.
Logit Choice model
The process begins by calculating the generalized cost of travel between each origin and destination by either mode. Usually, this cost is a linear combination of the monetary cost (fare, fuel, etc.) and time (walk, wait, interchange, in-vehicle-time, etc.). There may also be an additive constant to approximate those elements of the cost that cannot be readily quantified, for example the convenience of bus services, or the quality of railway rolling stock. Lets call the cost of travel by car, Ccar, and by PT, Cpt. Suppose that there is a total demand, D, that make such a journey in a given period. For the sake of clarity, subscripts relating to the origin and destination zone have been omitted.
The Absolute Logit Model states that the probabilities of choosing car, Pcar, and PT, Ppt, are given by the equations below.
Where is the scale parameter, of which more later. The forecast demand for car is given by Dcar and for PT, Dpt.
The model also calculates a composite cost (C) that represents the cost of the combined choice (in this case, car and public transport), where:
Where utilities are used instead of costs, this simple choice model does not require a distinct scale parameter, as its effects have already been incorporated into the utility values. Using utilities, the probabilities of choosing car, Pcar, and Ppt, are:
the composite utility (or logsum) is:
and the equations for demand by alternative (Dcar, etc.) are as given above.
Scale parameter (cost-based models)
The behavior of the model is determined by a positive constant known as the scale parameter, called in the equations above. The graph below illustrates the model sensitivity with different values of . If =0 the model is completely insensitive to cost, and demand is shared equally between each of the available choices. Notice that Pcar= and Ppt= when =0. As increases, the sensitivity of the logit model increases, progressively allocating more demand to the choice with the lower cost. The figure Logit model sensitivity on page 411 shows how the model becomes more responsive to the difference in cost for =0.01, 0.02 and 0.04. Finally, as approaches infinity, the model will allocate all the demand to the alternative with the lowest cost.
The value of the scale parameter will depend on the nature of the choice, characteristics of the demand and the units of cost. The examples used here are for illustrative purposes and should not be adopted as default values.
Logit model sensitivity
Where choice models are based on utilities, there is no cost coefficient as it has already been combined with the actual cost to form the utility values. Thus for simple choice models, the scale parameter is not required. Scale parameters are used in more complex (or hierarchic) models, but their specification and values are different from the style of use in cost-base models.
Matrix script for cost-based model
This section describes how this example can be implemented using the XCHOICE command. The fragment of script below will run this model. Variable names have been chosen to match those used in the preceding equations.
; Absolute logit model
XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input total demand DEMANDMW = 10, ; Input costs COSTSMW = 3, 4, ; Forecast demand ODEMANDMW = 15,16, ; Model structure SPLIT = TOTAL 0.02 car pt, ; Forecast composite cost SPLITCOMP = 19, ; Working matrices STARTMW = 30
The XCHOICE command comprises a number of clauses of the form keyword = value(s) each of which defines some aspect of the logit choice model. These specify what alternatives may be chosen, the inputs to the calculations, the resulting outputs, and the structure of the logit choice model. The block begins with the ALTERNATIVES clause listing of the names of the alternatives. In this case the choices are car and PT. These names will be used later to define the model structure. The model inputs are specified, starting with the total demand which is coded in the DEMANDMW clause. The specified input may represent a matrix of true demand (in trips), as shown here using MW[10], or it may be set to 1, in which case the output demand will be the probabilities associated with each alternative. Next, the generalized costs are specified for car, as matrix MW[3], and PT, as matrix MW[4]. These should be listed in the same order as the modes in the ALTERNATIVES clause. Now the output variables are specified. These are forecast demand for each alternative, again specified in the same order as the ALTERNATIVES clause, so MW[15] will contain car trips and MW[16] PT trips.
Finally the structure of the choice model is defined. In this example the choice is between two modes, car and PT, but this may be extended to three or more alternatives. The SPLIT clause defines the models structure in terms of the scale parameter (or coefficient of generalized costs) and the choices given in the ALTERNATIVES clause. The word TOTAL indicates that the entire input demand is to be split between the alternatives listed in this specification. The scale parameter has a value of 0.02 (or =0.02 in the above equations) and the choice is between the car and PT alternatives. In this script, the scale parameter is given as a numerical value but it is equally valid to use a variable instead. The forecast composite cost is output as MW[19] with the SPLITCOMP keyword. Both the forecast demand and composite cost are optional outputs, and either clause may be omitted from the script. The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix program script contains several XCHOICE commands, the same STARTMW value may be used in all instances.
Matrix script for utility-based model
This section describes how this example can be implemented using the XCHOICE command. The fragment of script below will run this model. Variable names match those used in the preceding equations.
; Absolute logit model XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input total demand DEMANDMW = 10, ; Input utilities
UTILITIESMW = 5, 6, Forecast demand ODEMANDMW = 15,16, ; Model structure SPLIT = TOTAL car pt, ; Forecast composite utility SPLITCOMP = 18, ; Working matrices STARTMW = 40 ;
The XCHOICE command comprises a number of clauses of the form keyword = value(s), each of which defines some aspect of the logit choice model. These specify what alternatives may be chosen, the inputs to the calculations, the resulting outputs, and the structure of the logit choice model. The block begins with the ALTERNATIVES clause listing of the names of the alternatives. In this case the choices are car and PT. These names will be used later to define the model structure. The model inputs are specified, starting with the total demand which is coded in the DEMANDMW clause. The specified input may represent a matrix of true demand (in trips), as shown here using MW[10], or it may be set to 1, in which case the output demand will be the probabilities associated with each alternative. Next, the utilities for car, as matrix MW[5], and PT, as matrix MW[6]. These should be listed in the same order as the modes in the ALTERNATIVES clause. Now the output variables are specified, as working matrix (MW) numbers. These are forecast demand for each alternative (MW[15] for car trips and MW[16] for PT, again specified in the same order as the ALTERNATIVES clause). Finally the structure of the choice model is defined. In this example the choice is between two modes, car and PT, but this may be extended to three or more alternatives. The SPLIT clause defines the models structure in terms of the choices given in the ALTERNATIVES clause; here the choice is between the car and PT alternatives. The word TOTAL indicates that this split divides the entire input demand between the specified
alternatives. The forecast composite utility is output as MW[18] with the SPLITCOMP keyword. Both the forecast demand and composite utility are optional outputs, and either clause may be omitted from the script. The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW clause specifies a working matrix number which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several XCHOICE commands, the same STARTMW value may be used in all instances.
Incremental logit model

This section discusses the incremental logit model. Topics include: Introduction Incremental logit choice model Matrix script for cost-based model Alternative script using cost differences Matrix script for utility-based models Alternative script using differences in utilities
Introduction
This example returns to the structure of the absolute choice example, but now forecasts the change in demand based on the change in cost from a known base situation. This is known as the incremental form of the logit model. The structure of the model shown below in Figure 1.
Structure of incremental logit model
This model is developed, both using costs and utilities below.

Incremental logit choice model
The model inputs are base demand by mode (Dcar, Dpt), base costs by mode (Ccar, Cpt) and forecast costs by mode (Ccar, Cpt). The change in cost is denoted by DCcar and DCpt where:
Base probabilities are denoted by Pcar and Ppt where:
The choice model now takes the form of the equation below where P denotes the forecast choice probability and is the scale parameter.
So that the forecast demand by mode (Dcar, Dpt) is:
The incremental composite cost (DC) is given by:
When working with utilities, the above equations are adapted to reflect the absence of any scale parameter (as this is combined into the utility values). The utility differences are calculated as:
and the probabilities of using each alternative are:
The equations for base and forecast demand by mode are the same as for cost-based models. The utility-based form of the composite costs is given by:
Matrix script for cost-based model
Comparing the example code below with the first example (same structure, but an absolute logit model), one can see that only the model inputs change to construct an incremental model. The model requires base demand, base costs and forecast costs for both modes as input. The output composite cost is the incremental change in composite cost.
; Incremental logit model XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input base demand by mode BASEDEMANDMW = 10, 11, ; Input base costs by mode BASECOSTSMW = 20, 21, ; Input forecast costs by mode COSTSMW = 30, 31, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL 0.02 car pt, ; Forecast incremental composite cost SPLITCOMP = 7, ; Working matrices
STARTMW = 40
Alternative script using cost differences
The XCHOICE command allows cost changes to be given instead of base and forecast costs. This variant is particularly useful when the costs do not change for all modes. For example, suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. In this case, there is no need to calculate the car cost for each test. Instead, the change in car cost, DCcar, can be set to zero. Where the cost difference is zero, the numeric value may be specified as the cost difference for the alternative (rather than needing to construct a matrix of zero values). The example excludes the calculation of incremental composite costs.
; Incremental logit model (specifying cost differences) ; Specify scale parameter (or cost coefficient) lambda = 0.02 XCHOICE ; List choices ALTERNATIVES = car, pt, ; Input base demand by mode BASEDEMANDMW = 10, 11, ; Input CHANGE in cost (= ForecastCost - BaseCost) DCOSTSMW = 24, 25, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL lambda car pt, ; Working matrices STARTMW = 30
Matrix script for utility-based models
Comparing the example code below with the first example (same structure, but an absolute logit model), one can see that only the model inputs change to construct an incremental model. The model requires base demand, base costs and forecast costs for both modes as input. The output composite cost is the incremental change in composite cost.
; Incremental logit model
XCHOICE, ; List choices ALTERNATIVES = car, pt, ; Input base demand by BASEDEMANDMW = 10, 11, ; Input base costs by BASEUTILSMW = 20, 21, ; Input forecast costs UTILITIESMW = 30, 31, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL car pt, ; Forecast incremental SPLITCOMP = 7, ; Working matrices STARTMW = 50
mode mode by mode
composite utilities
Alternative script using differences in utilities
The XCHOICE command allows changes in utility to be given instead of base and forecast utilities. This variant is particularly useful when the costs do not change for all modes. For example, suppose that the car cost is constant and that a series of tests are to be conducted for different PT scenarios. In this case, there is no need to calculate the car utility for each test. Instead, the change in car utility, DCcar, can be set to zero. The example excludes the calculation of incremental composite costs.
; Incremental logit model (specifying cost differences) XCHOICE ; List choices ALTERNATIVES = car, pt, ; Input base demand by mode BASEDEMANDMW = 10, 11, ; Input CHANGE in cost (= ForecastCost - BaseCost) ; Car Utilities are unchanged, so are specified as '0' DUTILSMW = 24, 25, ; Forecast demand ODEMANDMW = 2,3, ; Model Structure SPLIT = TOTAL car pt,
Working matrices STARTMW = 100
Hierarchical logit model

This section describes the hierarchical logit model. Topics include: Introduction Cost-based examples of hierarchic logit models Utility-based examples of hierarchic logit models
Introduction
The second example splits the PT mode of the first example into two distinct sub-modes; bus and train. This is an example of a Hierarchical Logit Model, which can be implemented in Absolute or Incremental form.
Structure of hierarchical logit model
Hierarchic models group related choices together in nests (or hierarchies). In this example, bus and train are members of the public transport nest that is considered to be distinct from the (private) car mode. In an absolute model, the choice probabilities are calculated by starting at the bottom of the tree and moving up the hierarchy, calculating the choice probabilities and the composite costs in each nest. In this model the process begins in the PT nest.
Firstly, conditional probabilities for each of the two PT modes (Pbus|pt and Ptrain|pt) and the composite PT cost are calculated within the lower nest with equations similar to those in the previous section. The composite PT cost will be used next to represent the cost associated with the combined PT choice. The choice probabilities for car (Pcar) and all PT (Ppt) can now be calculated using the technique described in the first example. It is now possible to move back down the hierarchy forecasting demand for each mode with the information derived above, so that:
For incremental models, the calculations are again performed in two stages, using the equations of the Incremental Logit Choice Model. The first pass calculates conditional probabilities and composite costs working up the tree structure; then in the second pass working down the tree, the resulting probabilities are calculated.
Cost-based examples of hierarchic logit models
As before the total demand is specified together with generalized costs for each choice (car, bus and train). A scale parameter must be associated each nest. In this example, the scale parameters are =0.02 in the upper nest (consistent with the previous example) and =0.03 in the lower nest. It is a result of the model theory that the value of the parameters must increase (or at least not decrease) as one moves down the hierarchy. That is to say, the models sensitivity to cost increases down the hierarchy.
Matrix script
The example below shows how the earlier absolute-choice example can be extended to include the lower nest in the hierarchy:
; Absolute hierarchical logit model ; Specify scale parameters lambda = 0.02 mu = 0.03 XCHOICE, ; List choices ALTERNATIVES = car bus train, ; Input demand DEMANDMW = 1, ; Input costs COSTSMW = 4, 5, 6, ; Forecast demand ODEMANDMW = 14,15,16, ; Model Structure ; Top level nest SPLIT = TOTAL lambda car pt, ; Forecast composite cost top level SPLITCOMP = 19, ; PT nest SPLIT = PT mu bus train ; Forecast composite cost PT level SPLITCOMP = 20, ; Working matrices STARTMW =70
First the modes (car, bus and train) are declared with the ALTERNATIVES clause. Notice that PT is not declared as an alternative; this is the name given to the combined choice of bus and train. Then the model inputs and outputs are specified. The input total demand and costs for the three distinct modes are given first, followed by the output forecast demand by mode. The hierarchical structure is specified by moving down the tree describing each nest. Beginning at the top of the tree, the first split command divides TOTAL (the total demand) into car and (all) PT with scale parameter =0.02. Notice that a scalar variable called lambda has been used to
represent the scale parameter in this case. PT is not considered as an individual mode now, but as a link with the lower nest. The SPLITCOMP keyword computes the composite costs for the nest associated with this SPLIT, in this case the top level. The second split command sub-divides PT trips between the bus and train alternatives using a scale parameter =0.03. The name pt is used as the first value in the SPLIT clause, and this acts as a link to the next level up the tree (where total demand was divided between car and PT). Another SPLITCOMP keyword for this SPLIT keyword computes the composite costs specific to the PT nest.
More complex absolute hierarchical models
The hierarchy can be extended with additional nests on either side of the tree. For example, a large absolute hierarchical logit model structure might have six choices: car, park and ride, bus, heavy rail, light rapid transit (LRT), and metro.
Structure of a large absolute hierarchical logit model Matrix script illustrating the complex example
This example may be codes as an absolute model as below, with park and ride abbreviated as pandr, and heavy rail as hrail:
; Extract from a large absolute logit model XCHOICE, ; List choices ALTERNATIVES = car pandr bus hrail lrt metro, ; Input demand DEMANDMW = 1,
Input costs COSTSMW = 11, 12, 13, 14, 15, 16, ; Forecast demand ODEMANDMW = 21,22,23,24,25,26, ; Model Structure ; Top level nest SPLIT = TOTAL 0.02 allcar allpt, ; All car nest SPLIT = allcar 0.05 car pandr, ; All PT nest SPLIT = allpt 0.03 bus train, ; Train nest SPLIT = train 0.04 hrail lrt metro, ; Working matrices STARTMW = 45
Utility-based examples of hierarchic logit models Scale parameter in utility-based models
The hierarchic choice model comprises a main choice nests, and a number of sub-nests. As with cost-based models, there is a requirement that higher level nests are less sensitive to cost differences than any sub-nests which lie below them. In the estimation of the utility equations used in the choice model coefficients are estimated for individual cost-terms (such as travel time, and fare) and for scale parameters. The scale parameter is a factor which is applied to the composite utility of a sub-nest before it is used in the choice process of the parent choice nest. To meet the sensitivity requirements noted above, the scale parameter must be greater than 0, and must not exceed 1.0. Thus, the scale parameters of utility-based models are viewed as part of the specification of the output of a split process, and different values may apply to each sub-nest in a choice nest. Where the scale parameter for a sub-nest is 1.0 there is no need to specify its value as this the assumed default. Where a scale parameter applies to two or more sub-nests, it may be specified once and brackets used to group the relevant sub-nests, so avoiding repetition of the parameter.
Matrix script illustrating two-level hierarchy
Using the tree structure shown in Structure of hierarchical logit model on page 421 as the basis of an absolute choice model, the total demand is specified together with the utility of each choice (car, bus and train). A scale parameter of 0.6 is applied to the PT sub-nest when its composite (or logsum) utility is used in the calculations of the higher-level nest.
; Absolute hierarchical logit model XCHOICE, ; List choices ALTERNATIVES = car bus train, ; Input demand DEMANDMW = 1, ; Input costs UTILITIESMW = 4, 5, 6, ; Forecast demand ODEMANDMW = 14,15,16, ; Model Structure ; Top level nest. PT sub-nest has scale parameter 0.6 SPLIT = TOTAL 1.0 car 0.6 pt, ; Forecast composite cost for the top level SPLITCOMP = 19, ; PT nest SPLIT = PT bus train ; Forecast composite cost for the PT nest SPLITCOMP = 20, ; Working matrices STARTMW =70
First the modes (car, bus and train) are declared with the ALTERNATIVES clause. Notice that PT is not declared as an alternative; this is the name given to the combined choice of bus and train. Then the model inputs and outputs are specified. The input total demand and utilities for the three distinct modes are given first, followed by the output forecast demand by mode. The hierarchical structure is specified by moving down the tree describing each nest.
Beginning at the top of the tree, the first split command divides TOTAL (the total demand) into car and (all) PT, and specifies a scale parameter of 0.6 which applies to the PT sub-nest. PT is not considered as an individual mode now, but as a link with the lower nest. The composite costs for this SPLIT are output with SLITCOMP. The second split command sub-divides PT trips between the bus and train alternatives, but no scaling parameters are used. The name pt is used as the first value in the SPLIT clause, and this acts as a link to the next level up the tree (where total demand was divided between car and PT). The composite cost for this SLIT are output with another SPLITCOMP keyword.
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 424. The example below is coded below in incremental form using utility differences:
; Extract from a large absolute logit model XCHOICE, ; List choices ALTERNATIVES = car pandr bus hrail lrt metro, ; Base demand BASEDEMANDMW = 1, 2, 3, 4, 5, 6, ; Utility differences DUTILSMW = 11, 12, 13, 14, 15, 16, ; Forecast demand ODEMANDMW = 21,22,23,24,25,26, ; Model Structure ; Top level nest SPLIT = TOTAL 0.4 allcar 0.667 allpt, ; All car nest SPLIT = allcar car pandr, ; All PT nest SPLIT = allpt 1.0 bus 0.75 train, ; Train nest SPLIT = train hrail lrt metro, ; Working matrices STARTMW = 45
In this example a scale parameter of 0.4 is applied to the all-car subnest; also 0.667 to the all-PT sub-nest and 0.75 to the train sub-nest.
Destination choice
This section describes the destination-choice model. Topics include: Introduction Matrix script
Introduction
This section shows how a logit model can be used to forecast destination choice. Suppose that an aggregate demand model has 100 zones. Associated with each origin zone (denoted i) there is a total demand of Di that is to be distributed between the 100 possible destinations (denoted j) according to the cost of the trip Cij. The figure Structure of destination choice model illustrates the structure, where d1, d2,... denote the choice of destination 1, destination 2 and so on.
Structure of destination choice model
For the absolute choice model, the probability of choosing destination zone j from origin zone i is given by Pij:
Where is the scale parameter. This equation is no more than a generalized case of the equation in the absolute logit model that forecasts the demand for car and PT. In this case, the choices are destination zones. The incremental logit model is also supported. Its underlying theory is similar to the equations in the incremental logit model, but with alternative modes replaced by destination zones. In this model, the base situation matrices of demand and cost (or cost differences) are also input rather than total travel demand. The incremental model is more widely used in studies than the absolute formulation. For absolute utility-based models, the destination choice model takes the form:
The incremental forms of logit choice model is also supported, and uses the incremental choice equations with alternative modes replaced by different destination zones. The clauses defining data input reflect the data required by the model, for examples UTILITIESMW (utilities) and DUTILSMW (differences in utilities).
Matrix script
The destination choice model described above is coded in the script below.
;Simple destination choice model ;Specify choice parameter lambda = 0.01 XCHOICE, ; Alternatives (only one, as doing destination choice) ALTERNATIVES = all ; Input demand from each origin DEMAND = TripsFromI[i], ; Input cost matrix COSTSMW = 3,
Forecast demand from each origin to each destination ODEMANDMW = 7 ; Model Structure DESTSPLIT = TOTAL lambda all, ; Working matrices STARTMW = 20
The extract begins with the specification of alternatives, which comprises just one alternative as we have no choice between modes. This is followed by the model inputs, in this case the demand is an array of trips from each zone and the generalized cost is matrix MW[3]. The outputs are a forecast demand matrix, MW[7]. The structure of this model is defined by the DESTSPLIT clause which defines a destination choice process. A scale parameter of =0.01 has been chosen for this example. The output from the split clause is the alternative all, as listed on the ALTERNATIVES keyword. The main differences for utility-based scripts are use of utility keywords (UTILITIESMW being used in place of COSTSMW ), and no use of lambda, the scale parameter, so that the DESTSPLIT clause now becomes DESTSPLIT = TOTAL all.
Mode and destination choice

This section discusses the mode-and-destination-choice model. Topics include: Introduction Mode followed by destination choice Destination followed by mode choice
Introduction
The XCHOICE command supports both mode and destination choice in the same structure. This section considers first mode followed by destination choice, then destination followed by mode choice.
Which form of model is appropriate for a study is determined during model calibration. The values of scale parameter for the various choice nests, which reflect sensitivity to cost differences, determine which form is used.
Mode followed by destination choice
Consider first an example of mode followed by destination choice. The figure illustrates a system with two modes, car and PT, and 100 destination zones (labelled d1, d2,..., d100).
Mode followed by destination choice
Here the total demand is split first by mode (into two vectors representing car and PT demand for each origin) then by destination (giving car and PT matrices).
Matrix script
The script extract below is similar to previous examples shown in Incremental logit model on page 415 and Destination choice on page 428. The model structure specification splits the total demand by mode first with scale parameter =0.01, then across destinations for each mode individually. The parameters for destination choice are =0.02 and =0.03 for car and PT respectively.
; Mode choice above destination choice model ; Specify choice parameters lambda = 0.01 mu = 0.02 theta = 0.03 XCHOICE,
; ; ; ; ; ; ; ; ; ;
List choices ALTERNATIVES = car pt, Base Demand BASEDEMANDMW = 1,2, Base Costs BASECOSTSMW = 11,12, Forecast costs COSTSMW = 21,22, Forecast demand matrices by mode ODEMANDMW = 31,32, Model Structure Mode choice SPLIT = TOTAL lambda destcar destpt Car destination choice DESTSPLIT = destcar mu car, PT destination choice DESTSPLIT = destpt theta pt, Working matrices STARTMW=110
Destination followed by mode choice
Now consider the case of destination followed by mode choice. The figure illustrates such a system with two modes, car and PT, and 100 destination zones (labelled d1, d2,..., d100).
Destination followed by mode choice
The total input demand is first by destination (into a matrix), which is then split by mode (giving two matrices representing car and PT demand).
Matrix script
Starting from the top, the model structure specification splits the total demand by destination. The mode-choice sub-nests has scale parameters of 0.5, and the intermediate matrix is identified by the name distribution. This name, distribution, is then used as the link (or input) to the lower choice nest.
; Destination followed by mode choice model XCHOICE, ; List choices ALTERNATIVES = car pt, ; Input base demand and utility-difference matrices BASEDEMANDMW = 11,12, DUTILSMW = 16,17, ; Forecast demand matrices by mode ODEMANDMW = 21,22, ; Model Structure ; Destination choice DESTSPLIT = TOTAL 0.5 distribution, ; Mode choice SPLIT = distribution car pt, ; Working matrices STARTMW = 50
General notes
This section provides general notes about logit choice models: Availability of choices Applying choice models to selected parts of matrices Practical considerations: Incremental models Practical considerations: Scale parameters
Availability of choices
Within a demand model, it is often useful to make certain choices unavailable. For example, a rail mode might not be a practical alternative for travel between all zones in the study area. To make a choice unavailable you should give that choice a large positive generalized cost (or large negative utility). Large in this context is
100 times greater than typical costs. For example, if costs are up to 400 generalized minutes, try using a cost of 40000 minutes to make a particular choice unavailable.
Applying choice models to selected parts of matrices
There are instances when it is desirable to apply choice models to selected parts of a matrix, rather than the entire matrix. These typically arise when matrices can be broken down into distinct segments (such as trips entirely within study area, through trips etc.), and different choice models apply to these different segments. In some instances the model structure is common to all segments, but the sensitivity (and so cost-coefficient) varies between segments. Under these conditions, the cost coefficient may be specified as a matrix (such as MW[5], or mi.1.coefficient) rather than a scalar value. Where the model structure varies between segments, or the user wishes to apply the choice model separately for each segment, the following provides guidance on techniques used. When a XCHOICE control statement occurs in the Matrix program it will typically be applied to all cells (or origin-destination pairs). The XCHOICE control statement may be coded inside a conditional test which selects the origin zones it is applied to:
; test to see if model applies to this origin zone if (i < 45) ; if so, then apply the model XCHOICE, ; subsequent clauses of XCHOICE statement, as needed ; ... endif
For simple choices between alternative modes, this may be extended, by use of the JLOOP command, to select particular rows and columns of the matrix where the choice model is applied:
;apply the model to trips from zones 1-45 to zones 46-53 if (i < 45) JLOOP INCLUDE = 46-53 XCHOICE, ; subsequent clauses of XCHOICE statement, as needed ; ...
ENDJLOOP endif
Where the choice model applies to a segment which is not a regular set of rows and columns, but is determined by some other matrix attribute (such as distance from origin to destination), a script may be coded as follows:
;start a JLOOP to process each origin-destination pair in turn JLOOP ; test to see if O-D meets selection criteria for the segment if (mi.1.distance > 50) ; if so, then apply the model XCHOICE, ; subsequent clauses of XCHOICE statement, as needed ; ... endif ENDJLOOP
Where a model seeks to use destination choice, this cannot be coded inside a JLOOP construct. If only selected destinations are valid for the destination choice, then the INCLUDE or EXCLUDE subkeyword should be specified immediately after the DESTSPLIT keyword in order to include or exclude the required zones.
Practical considerations: Incremental models
In an incremental model, if the base demand for a choice is zero, the forecast demand for that choice will always be zero. This is made clear if one examines the equation in the Incremental logit model on page 415, where, if Pcar=0 then Pcar=0 whatever costs are given. If this effect is a problem, then the modelling approach should be reviewed.
Practical considerations: Scale parameters
For models calibrated in terms of generalized costs to give sensible results, it is important to ensure for cost-based models that the size of the parameters increase (or at least not decrease) as one moves down the hierarchy. That is to say, the models sensitivity to cost increases down the hierarchy. Where these conditions are not met, an error message will be output.
Matrix Program Control statements
Control statements
The following control words are available in the Matrix program.
Control word ABORT ARRAY BREAK BSEARCH CALL CHOICE COMP CONTINUE EXIT FILEI FILEO FILET FILLMW FREQUENCY GOTO IF ... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LOOKUP LOOP ... ENDLOOP PARAMETERS PRINT PRINTROW RENUMBER REPORT SET Description Abort current program Set arrays and values Break out of current process Finds a key or set of keys in a sorted array, or series of sorted arrays using a binary search. Call users dll (external process) Implement logit choice models (prior to v4.1) Compute variables from expressions Continue at end of loop statement Terminate current program Input files Output files Set path for temporary files Fill work matrices Accumulate distributions of one matrix versus another Immediate jump to :label Define IF ENDIF block Define a loop for destination zones (J) Define lookup tables (see Chapter 3, General Syntax) Define user controlled loop Set static parameters Print variable values Print a row of a matrix (see Chapter 3, General Syntax, for details) Set zone renumber specifications Select standard reports Set multiple variables/arrays to same value
Control word SORT WRITE XCHOICE
Description Sort user arrays Writes records to a DBF file defined by RECO Implement logit choice models (starting at v4.1)
ABORT
Programs: Distribution, Fratar, Generation, Matrix
Aborts the entire run. MSG Use ABORT to terminate the program and return a fatal code to Cube Voyager. Though not normally used, you can use this statement to terminate processing due to some detectable conditions. For example, suppose that during a mode-split process, the program detects walk access and drive access between the same zone pair, but you know that this should not occur. You can create a test to find this and abort if it occurs.
Keyword MSG |S| Description Optional message that can be printed when the program terminates.
Example
IF (MW[1][I] != 0) ABORT ; Intrazonal present in MW[1] INTRA = MW[1][I] IF (! INTRA) LIST='No intrazonal value for MW[1] at Zone ', I ABORT ENDIF
ARRAY
Declares user single-dimension arrays. VAR=n, VAR=n-str
Use ARRAY to allocate user arrays. An array is different than a variable in that it represents vectored data. Values stored to arrays in this program can be numeric or string. When an array is referenced, it must include an index [ ], and if the index exceeds the size, the program will fatally terminate. Arrays can be useful for different processes; the most common use may be to store information for specific zones. ARRAY statements are not dynamic (stack oriented); they are allocated prior to any stack operations. When an array variable appears in a SET statement, all the cells in the array are set to the same value.
ARRAY keyword
Keyword VAR |I| Description Name of the variable that is to be allocated according to the specified size, n. VAR must be a unique name. The size following the keyword is the highest index possible for VAR. Size may be either a numeric constant, or a special nameZONES. Arrays are cleared when they are allocated. Designate an array as a string array by appending a dash followed by the string size, str, to the array size, n. The size n defines the dimension of the array, either numeric or string, and an appended -str defines the array as a string array and sets the string length.
Example
ARRAY sum_mat=10, cbd2ext=500 IF (M <= 10) sum_mat[M] = sum_mat[M] + rowsum(M) IF (I=1-10,51-58,63,96) cbd2ext[I] = cbd2ext[i] + MW[1] include=501-535 ARRAY row_total=zones ; example of defining a string array ARRAY StrArray=1000-5 ; defines a string array with size of 1000 and a character width of 5.
BREAK
Use BREAK to break out of a loop. When encountered, control immediately passes to the stack statement after the associated end of loop. If BREAK is within a LOOP or JLOOP block, control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J will be reset to 1). Otherwise, stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed.
Example
LOOP L1=1,3 IF (condition) statements ELSE BREAK ; jump to IF statement ENDIF ENDLOOP IF (condition) BREAK ; no more processing for this origin zone LOOP L2=K1,K2,KINC JLOOP EXCLUDE=25-50,88 IF (condition) BREAK ; jump to LOOP L3= ENDJLOOP LOOP L3=L2,L2+5 IF (condition) BREAK; ; jump to ABC= ENDLOOP ABC=... ENDLOOP
BSEARCH
Program: Matrix
Performs a binary search to find a key or set of keys in a sorted array or series of sorted arrays. The format is:
BSEARCH ARRAY=value, ARRAY=value, ...
ARRAY |N| is the name of a user array that is in ascending sort. The
routine will do a binary search to expedite the search for the key. If there are multiple arrays specified, the search will begin at the first
array and then proceed through the remaining arrays for matching keys (at the same record level as the first array). All arrays must be in ascending sort. If the array is a string (C) array, any constant value must be placed within quotes. If the value is an expression, the result of the expression must be a string.
BSEARCH stores results in the variable _BSEARCH. Possible values in _BSEARCH are:
+n Indicates an exact match was found at the nth location in the array -n Indicates that no match was found, but the nth location is where one would insert the key (that is, the nth location is higher than the key, and the n-1 location is lower than the key). 0 Indicates that the key is greater than the value in the highest location in the array.
Example
ARRAY MYARRAY=100, YOURARRAY=100 some code to populate the arrays SORT ARRAY=MYARRAY,YOURARRAY BSEARCH MYARRAY=32, YOURARRAY=(MYARRAY[j]*3)
Example
FILEI ARRAY BSEARCH DBI[1]=MYDBF, AUTOARRAY=FIELD1 SORT=FIELD1 MYARRAY=100, YOURARRAY=100 DBA.1.FIELD1='875'
CALL
Executes an external routine. DLL
Use CALL to execute an external process. To use this statement, there must be an external file that is a dynamic link library (DLL), which contains the entry point that is desired to be used at this location. The DLL file may have multiple entry points, and they can all be accessed by this run of the Matrix program.
Keyword DLL |S| Description Single string that contains the DLL file name, without extension, followed by the name of the routine entry point enclosed within parentheses. The DLL extension is appended by the program. In some operating systems, the file name may be case sensitive. The routine name is usually case sensitive; this depends upon the compiler/linker system used to develop the DLL. NOTE: The compiler/linker system that was used to develop the DLL might have added some characters to the entry name: Borland C/C++ compilers prefix the entry name with an underscore.
The routine is called with one argument: the address of a structure that contains: I, J, Zones, Iteration, address of MW, address of a routine to obtain address of any variables, and address of a routine to print messages. The calling process adheres to standard C notation. The C structure is illustrated in the sample code section below. I, J, Zones, and Iteration are passed as integers. The addresses of these variables could be found by using the pfFindVar routine, but because these variables must be protected, pfFindVar will return NULL if the routine tries to obtain their addresses. MW is the address of an array of pointers to the individual MW arrays. MW[1] is the address of the first cell for MW[1]. Note that this is the cell for column 0, NOT column 1. MW[1][1] would be the correct notation to address the cell for zone 1 in MW[1]. MWs are allocated individually, rather than as a single block. In Fortran (without pointers), the access to MW[1][1] would NOT be the typical MW(1,1). Instead, the address of each MW would have to be obtained individually, and passed through an interface to a separate routine for actual use of the MW. The routine would probably declare the array as: DOUBLE PRECISION MW1(0:*).
The MW array can be accessed in several ways: Saving the MW value from the passed structure: the suggested way if MWs need not be allocated, and there are many references to MWs. Saving the address returned from pfVarFind (MW...): the required way if MWs need to be allocated. Indirect referencing to MW from the passed structure; an efficient way if MWs need not be allocated, and there are not many references to MWs. Indirect referencing is not quite as efficient as direct addressing, but there is minimal difference.
The pfFindVar routine is used to obtain the pointer to any variables that are to be made available to the external process. All variables (with a few isolated exceptions) are stored as double precision values. Calls to pfFindVar need to be made only during the first entry into the procedure; the returned addresses can be stored in static cells so that pfFfindVar need not be called on every entry. The Matrix program allocates MW arrays only when it is necessary, so the routine has to make sure that any MWs that it wishes to use are allocated. This can be done by calling pFfindVar for MW, and appending the integer numbers of the MWs that the procedure will use. If this is not done, and the routine accesses an MW that has not been allocated, the routine will access a dummy array. If the user is sure that all the desired MWs have been previously allocated by the Matrix program, pfFindVar need not be used at all. The pfPrnLine function is called, with two arguments, to print a message:
nCtl The control word for print the message. It has the
format SFEN where, F is a 1 if the message is to be written to the error file E is the level of the message (0,1,2=Message, Warning, Fatal), N is the number of newlines to print before printing the message.
sMmessage The message string (ASCIIZ) to be printed; it may
contain any normal printer characters, including \n, \r,\f,\t etc.

Example
CALL DLL=user(_User1) ; call the following code in user.dll // Sample of user function code in C /*TITLE: User1 -- user function*/ #include <stdio.h> typedef struct { int I, J, Zones, Iteration; double** MW; void* (*pfFindVar)(char*,...); void* (*pfPrnLine)(int, char*); } CallStack; int _export User1 (CallStack* Stack) { char message[100]; static double** MW=NULL; /* store the address of MW array */ int m,j; /* * At first entry (when MW==NULL), * establish MW and insure that MW[1-5] have been allocated */ if (MW == NULL) { MW = (*Stack->pfFindVar)("MW",1,2,3,4,5); /* Example of forming a message */ sprintf(message,"User1 Call I=%i, J=%i, Zones=%i", Stack->I, Stack->J, Stack->Zones); /* Example of printing a message */ (*Stack->pfPrnLine)(1,message); } /* Sample to fill in MW[1-5] */ for (m=1; m<=5; m++) for (j=1; j<=Stack->Zones; j++) MW[m][j] = Stack->I*100 + m*10 + j; /* Stack->MW[m][j] is a similar way to reference MW[m][j] */ return 0; }
CHOICE
Program: Matrix
Implements a logit-choice model.

NOTE: XCHOICE is the preferred command statement for
implementing logit-choice models. ALTERNATIVES BASECOSTS BASEDEMAND BASEUTILS COSTS DCOSTS DEMAND DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE) DUTILS OCOMPCOST OCOMPUTIL ODEMAND SPLIT (COEFF, SPLITINTO) STARTMW UTILITIES Use the CHOICE command to implement logit-choice models, which can be based either on generalized costs or utilities. The actual keywords supported depend on whether you use costbased or utility-based models: CHOICE keywords: Cost-based models
CHOICE keywords: Utility-based models

CHOICE keywords: Cost-based models
Keyword ALTERNATIVES
Description Lists the set of discrete choices in the forecast scenario. If the model is confined to destination choice, then the alternatives list comprises just one item (representing the demand matrix). The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT commands which define the structure of the logit choice model, and also determine the order that input or output data are specified. Supplies the names of the base-cost variables. For lists of two or more variables, the order must match the list of choices given in the ALTERNATIVES clause. This clause is only used in incremental models which specify base and forecast costs (as opposed to cost differences). The corresponding forecast costs are specified using the COSTS clause.
BASECOSTS
BASEDEMAND
Supplies the names of the base-demand variables for incremental models only. For lists of two or more variables, the order must match that in the ALTERNATIVES clause. Specifies forecast costs. If there is more than one cost specified, their order must be the same as that used in the ALTERNATIVES clause. See also BASECOSTS and DCOSTS (cost-differences) for incremental models; the COSTS clause is not used in conjunction with the latter.
COSTS
DCOSTS
For incremental models only, the change in cost for each choice can be given instead of the base and forecast costs. These cost-differences may be specified as matrices, or numeric values such as 0.0. Specifies total demand for an absolute model. Demand is typically a matrix, although numeric values may be specified. For example, a demand of 100.0 will give output demand corresponding to the percentages which choose each alternative.
DEMAND
CHOICE keywords: Cost-based models (continued)

Keyword DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE) Description The DESTSPLIT clause is used when the nest in the hierarchy corresponds to a destination choice model. It divides the travel demand between destination zones, rather than alternatives. The output list must comprise just one item, representing either a distinct choice from the ALTERNATIVES clause or an output which links to a subnest. Like the SPLIT command, it may be specified in one clause or divided into constituent parts by use of the COEFF and SPLITINTO clauses. Examples are:
DESTSPLIT = TOTAL, 0.3, allTrips,
and
DESTSPLIT = TOTAL, COEFF = 0.3, SPLITINTO = allTrips,
By default the destination choice model works over all zones. By using the INCLUDE or EXCLUDE clauses the choice process may be restricted to a subset of all zones. The following example shows destination choice over zones 1 to 57:
DESTSPLIT = TOTAL, 0.3, allTrips, INCLUDE = 1-57,
This shows destination choice over zones except for 88 to 100, which are specified by the EXCLUDE subkeyword:
DESTSPLIT = TOTAL, COEFF = 0.3, SPLITINTO = allTrips, EXCLUDE = 88-100,
Note that certain restrictions apply to the use of destination choice models. The composite costs may not be saved, and this form of logit model may not be used inside a JLOOP construct. OCOMPCOST Optional. Outputs the composite cost of all choices for an absolute model. The list contains a numeric value, which specifies the working matrix (MW) that stores the result. Where the choice model has a hierarchic structure, the composite cost for the highest level nest may be saved. This clause is not supported for destination-choice models, as the composite costs are zonal values rather than matrices. Specifies the working matrices (MWs) used to store the forecast demand; the list comprises a list of working matrix numbers. If there is more than one cost variable, then the list must be in the same order as used in the ALTERNATIVES clause. This command is optional, and may be omitted if only the composite costs are required.
ODEMAND
CHOICE keywords: Cost-based models (continued)

Keyword SPLIT (COEFF, SPLITINTO) Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT clauses. One of these clauses is required for each nest (or subnest) in the model hierarchy. For a hierarchic model, these are typically specified starting at the top-level and working down the structure. Each SPLIT clause specifies an input, a scale parameter (or coefficient of cost), and one or more outputs. The coefficient and outputs may both be specified in the SPLIT clause or specified using the COEFF and SPLITINTO subkeyword clauses. The input (or first item listed in a SPLIT clause) may either be TOTAL (representing the total demand at the top level of the choice hierarchy) or for subnests it is the name of an output from the appropriate higher level nest. The coefficient is specified as the second item in the SPLIT clause, or using the COEFF subclause. It may be specified as a numeric value, a variable, or even a matrix with differing values between origindestination pairs. The latter is appropriate when the demand matrix comprises distinct segments (such as travel within study area, trips from cordon into study area, and through traffic) and these segments respond differently to cost differences. The remainder of the SPLIT clause, or the SPLITINTO clause define the output list. The items represent either distinct choices (from the ALTERNATIVES clause), or links to subnests which are given unique meaningful names and used as inputs to lower splits. The following examples shows a subnest taking AllPT as an input and using a scale parameter of 0.3 to divide between bus and rail alternatives. Specified as a SPLIT clause it takes the form:
SPLIT = AllPT, 0.3, Bus, Rail,
and using subkeywords it is:

SPLIT = AllPT, COEFF = 0.3, SPLITINTO = Bus, Rail,
STARTMW
The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the CHOICE command. The STARTMW clause specifies a numeric value corresponding to a particular working matrix which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the CHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several CHOICE commands, the same STARTMW value may be used in all instances.
CHOICE keywords: Utility-based models

Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario. If the model is confined to destination choice, then the alternatives list comprises just one item (representing the demand matrix). The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT commands which define the structure of the logit-choice model, and also determine the order that input or output data are specified. Supplies the names of the base-demand variables. For incremental models only. For lists of two or more variables, the order must match that in the ALTERNATIVES clause. Supplies the names of the base utilities for the various alternatives. For lists of two or more variables, the order must match that given in the ALTERNATIVES clause. This clause is only used in incremental models which specify base and forecast utilities (as opposed to utility differences). The corresponding forecast costs are specified using the UTILITIES clause. DEMAND Specifies the total demand for an absolute model. Demand is typically a matrix, although numeric values may be specified. For example, a demand of 100.0 will give output demand corresponding to the percentages which choose each alternative. Use the DESTSPLIT clause when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand between destination zones, rather than alternatives. The output list must comprise just one item, representing either a distinct choice from the ALTERNATIVES clause or an output which links to a subnest. This output item may be preceded by a scale parameter. The following example applies a scaling factor to the ModeSplit logsum utility, and performs a destination choice dividing the total trips across all destinations:
DESTSPLIT = TOTAL 0.9 ModeSplit,
BASEDEMAND
BASEUTILS
DESTSPLIT (INCLUDE, EXCLUDE)
By default the destination-choice model works over all zones. By using the INCLUDE or EXCLUDE subkeyword clauses the choice process may be restricted to a sub-set of all zones. The following example restricts destination choice to zones 1 to 23:
SPLIT = TOTAL, allTrips, INCLUDE = 1-23,
NOTE: Certain restrictions apply to the use of destination-choice models. The composite utilities cannot be saved, and this form of logit model may not be used inside a JLOOP.
CHOICE keywords: Utility-based models (continued)

Keyword DUTILS Description Gives the change in utility for each choice rather than the base and forecast utilities. For incremental models only. These utility-differences may be specified as matrices, or numeric values such as 0.0. Optional. Outputs the composite utility (or logsum value) of all choices for an absolute model. The list contains a numeric value which specifies which working matrix (MW) is used to store the result. Where the choice model has a hierarchic structure, the composite utility for the highest level nest may be saved. This clause is not supported for destination-choice models, as the composite costs are zonal values rather than matrices. Optional. Specifies the working matrices (MWs) used to store the forecast demand; the list comprises a list of working matrix numbers. If there is more than one cost variable, then the list must be in the same order as used in the ALTERNATIVES clause. This command may be omitted if only the composite costs are required.
OCOMPUTIL
ODEMAND

Keyword SPLIT Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT clauses. One of these clauses is required for each nest (or subnest) in the model hierarchy. For a hierarchic model, these are typically specified starting at the top-level and working down the structure. Each SPLIT clause specifies an input, and one or more outputs which may have their own scale parameters. (A choice with only one output may be specified to apply a scaling factor to a sub-nest logsum utility, and so achieve consistent scaling at all equivalent levels in a complex hierarchic structure.) The input (or first item listed in a SPLIT clause) may either be TOTAL (representing the total demand at the top level of the choice hierarchy) or for subnests it is the name of an output from the appropriate higher level nest. The remainder of the SPLIT clause define the output list, and any scale parameters which apply to subnests. The main items in the output list represent either distinct choices (from the ALTERNATIVES clause), or links to sub-nests which are given unique meaningful names and used as inputs to lower splits. An example is:
SPLIT = AllPT Bus Rail,
Subnests in the output list may be preceded by a scale parameter, which is applied to the composite (or logsum) utility of the subnest before evaluating this choice nest. The scale parameter should be greater than 0, and must not exceed 1.0. The scale parameter may be omitted where its value is 1.0, as this is the assumed default. Examples are:
SPLIT = TOTAL Car 0.5 PT 0.4 WalkCycle,
where scale parameters are applied to the PT and walk/cycle subnests. Car either is a distinct alternative, or a subnest with a default scale parameter of 1.0. Where the same scale parameter applies to several subnests, the scale parameter may be specified once followed by the list of relevant subnests grouped together by use of brackets. An example is:
SPLIT = TOTAL, 0.4 Car 0.5 (Bus Rail),
where the bus and rail subnests share the same scale parameter, and a different value applies to the car subnest.

Keyword STARTMW Description The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the CHOICE command. The STARTMW clause specifies a numeric value corresponding to a particular working matrix which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the CHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several CHOICE commands, the same STARTMW value may be used in all instances. Specifies forecast utilities. If there is more than one utility, their order must be the same as that used in the ALTERNATIVES clause. See also BASEUTILS and DUTILS (utility-differences) for incremental models; the UTILITIES clause is not used in conjunction with DUTILS.
UTILITIES
XCHOICE
Program: Matrix XCHOICE implements a logit choice model. XCHOICE replaces the CHOICE command statement, resulting in improved run times. Though you can continue to use CHOICE, Citilabs recommends using the XCHOICE command statement for logit choice models. Usage is similar with XCHOICE, but there are some differences in
keyword usage and in value formats for keywords. See Summary of syntax usage differences between XCHOICE and CHOICE on page 458. ALTERNATIVES COSTSMW BASECOSTSMW DCOSTSMW UTILITIESMW BASEUTILSMW DUTILSMW
DEMANDMW DEMAND BASEDEMANDMW ODEMANDMW SPLITCOMP SPLIT (COEFF, SPLITINTO SPLITCOMP) DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE) STARTMW Use the XCHOICE command to implement logit choice models, based on either generalized costs or utilities. The actual keywords supported depend on whether you use cost-based or utility-based models: XCHOICE keywords: Cost-based models XCHOICE keywords: Utility-based models
XCHOICE keywords: Cost-based models
Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario. If the model is confined to destination choice, then the alternatives list comprises just one item (representing the demand matrix). The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT keywords which define the structure of the logit choice model, and also determine the order that input or output data are specified. Supplies the names of the base cost matrices. For lists of two or more matrices, the order must match the list of choices given in the ALTERNATIVES keyword. This keyword is only used in incremental models which specify base and forecast costs (as opposed to cost differences). The corresponding forecast costs are specified using the COSTSMW keyword. BASEDEMANDMW Supplies the names of the base demand matrices. For incremental models only. For lists of two or more matrices, the order must match that in the ALTERNATIVES keyword.
BASECOSTSMW
XCHOICE keywords: Cost-based models (continued)

Keyword COSTSMW Description Specifies forecast costs matrices. If there is more than one cost specified, their order must be the same as that used in the ALTERNATIVES keyword. See also BASECOSTSMW and DCOSTSMW (cost-differences) for incremental models; the COSTSMW keyword is not used in conjunction with DCOSTSMW. DCOSTSMW Gives the change in cost for each choice rather than the base and forecast costs. For incremental models only. These cost-differences may be specified as matrices, or numeric values such as 0.0. The demand value for a destination-choice or mode- and destination-choice model. The demand matrix for a pure mode-choice model. Use the DESTSPLIT keyword when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand between destination zones, rather than alternatives. The output list must comprise just one item, representing either a distinct choice from the ALTERNATIVES keyword or an output which links to a subnest. Like the SPLIT command, it may be specified in one keyword or divided into constituent parts by use of the COEFF and SPLITINTO subkeywords. Examples are:
DESTSPLIT = TOTAL, 0.3, allTrips,
DEMAND DEMANDMW DESTSPLIT (COEFF, SPLITINTO, INCLUDE, EXCLUDE)
and
DESTSPLIT = TOTAL, COEFF = 0.3, SPLITINTO = allTrips,
By default the destination choice model works over all zones. By using the INCLUDE or EXCLUDE subkeywords the choice process may be restricted to a subset of all zones. The following example shows destination choice over zones 1 to 57:
DESTSPLIT = TOTAL, 0.3, allTrips, INCLUDE = 1-57,
and this shows destination choice over zones except for 88 to 100, which are specified by the EXCLUDE subkeyword:
DESTSPLIT = TOTAL, COEFF EXCLUDE = 88-100, = 0.3, SPLITINTO = allTrips,
NOTE: Certain restrictions apply to the use of destination-choice models. The composite costs may not be saved, and this form of logit model may not be used inside a JLOOP construct. ODEMANDMW Specifies which working matrices (MWs) store the forecast demand; the list comprises a list of working matrix numbers. If there is more than one cost matrix, then the list must be in the same order as used in the ALTERNATIVES keyword.

Keyword SPLIT (COEFF, SPLITINTO, SPLITCOMP) Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT keywords. One of these keywords is required for each nest (or subnest) in the model hierarchy. For a hierarchic model, these are typically specified starting at the top level and working down the structure. Each SPLIT keyword specifies an input, a scale parameter (or coefficient of cost), and one or more outputs. The coefficient and outputs may both be specified in the SPLIT keyword or specified using the COEFF and SPLITINTO subkeyword clauses. The input (or first item listed in a SPLIT keyword) may either be TOTAL (representing the total demand at the top level of the choice hierarchy) or for subnests it is the name of an output from the appropriate higher level nest. The coefficient is specified as the second item in the SPLIT keyword, or using the COEFF subkeyword. It may be specified as a numeric value, a variable, or even a matrix with differing values between origin-destination pairs. The latter is appropriate when the demand matrix comprises distinct segments (such as travel within study area, trips from cordon into study area, and through traffic) and these segments respond differently to cost differences. The remainder of the SPLIT keyword, or the SPLITINTO subkeyword define the output list. The items represent either distinct choices (from the ALTERNATIVES keyword), or links to sub-nests which are given unique meaningful names and used as inputs to lower splits. The following examples shows a subnest taking AllPT as an input and using a scale parameter of 0.3 to divide between bus and rail alternatives. Specified as a SPLIT keyword it takes the form:
SPLIT = AllPT, 0.3, Bus, Rail,
and using subkeywords it is:

SPLIT = AllPT, COEFF = 0.3, SPLITINTO = Bus, Rail,
The SPLITCOMP subkeyword specifies the working matrix to store the composite costs or composite utilities for the nest defined by its parent SPLIT keyword.

Keyword SPLIT (continued) Description Example:
XCHOICE ALTERNATIVES = A,b,c, baseCOSTSmw = 2,3,4, COSTSmw = 2,3,5, basedemandmw=1,1,1, ODEMANDmw=6,7,8, SPLIT= Total 0.1 desta, destpt, SPLITCOMP=20, destSPLIT= desta 0.15 a, destSPLIT= destpt 0.15 pt, SPLIT= pt 0.2 B C, SPLITCOMP=21, startmw=30 MW 20 is composite cost of alternative "Total" MW 21 is composite cost of alternative "pt"
STARTMW
The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW keyword specifies a numeric value corresponding to a particular working matrix which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several XCHOICE commands, the same STARTMW value may be used in all instances.
XCHOICE keywords: Utility-based models

Keyword ALTERNATIVES Description Lists the set of discrete choices in the forecast scenario. If the model is confined to destination choice, then the alternatives list comprises just one item (representing the demand matrix). The names used in the alternatives list are subsequently used in SPLIT or DESTSPLIT commands which define the structure of the logit choice model, and also determine the order that input or output data are specified. Supplies the names of the base demand matrices. For incremental models only. For lists of two or more matrices, the order must match that in the ALTERNATIVES keyword.
BASEDEMANDMW
XCHOICE keywords: Utility-based models (continued)

Keyword BASEUTILSMW Description Supplies the names of the base utility matrices for the various alternatives. For lists of two or more matrices, the order must match that given in the ALTERNATIVES keyword. This keyword is only used in incremental models which specify base and forecast utilities (as opposed to utility differences). The corresponding forecast costs are specified using the UTILITIESMW keyword. DEMAND DEMANDMW DESTSPLIT (INCLUDE, EXCLUDE) The demand value for a destination-choice or mode- and destination-choice model. The demand matrix for a pure mode-choice model. Use when the nest in the hierarchy corresponds to a destination-choice model. It divides the travel demand between destination zones, rather than alternatives. The output list must comprise just one item, representing either a distinct choice from the ALTERNATIVES keyword or an output which links to a subnest. This output item may be preceded by a scale parameter. The following example applies a scaling factor to the ModeSplit logsum utility, and performs a destination choice dividing the total trips across all destinations:
DESTSPLIT = TOTAL 0.9 ModeSplit,
By default the destination choice model works over all zones. By using the INCLUDE or EXCLUDE subkeywords the choice process may be restricted to a subset of all zones. The following example restricts destination choice to zones 1 to 23:
SPLIT = TOTAL, allTrips, INCLUDE = 1-23,
NOTE: Certain restrictions apply to the use of destination choice models. The composite utilities cannot be saved, and this form of logit model may not be used inside a JLOOP. DUTILSMW Gives the change in utility for each choice rather than the base and forecast utilities. For incremental models only. These utility-differences may be specified as matrices, or numeric values such as 0.0. Specifies working matrices (MWs) used to store the forecast demand; the list comprises a list of working matrix numbers. If there is more than one cost matrix, then the list must be in the same order as used in the ALTERNATIVES keyword. This command is optional, and may be omitted if only the composite costs are required.
ODEMANDMW

Keyword SPLIT Description The structure of the logit choice model is specified by the SPLIT and DESTSPLIT keywords. One of these keywords is required for each nest (or subnest) in the model hierarchy. For a hierarchic model, these are typically specified starting at the top level and working down the structure. Each SPLIT keyword specifies an input, and one or more outputs which may have their own scale parameters. (A choice with only one output may be specified to apply a scaling factor to a subnest logsum utility, and so achieve consistent scaling at all equivalent levels in a complex hierarchic structure.) The input (or first item listed in a SPLIT keyword) may either be TOTAL (representing the total demand at the top level of the choice hierarchy) or for subnests it is the name of an output from the appropriate higher level nest. The remainder of the SPLIT keyword define the output list, and any scale parameters which apply to subnests. The main items in the output list represent either distinct choices (from the ALTERNATIVES keyword), or links to subnests which are given unique meaningful names and used as inputs to lower splits. An example is:
SPLIT = AllPT Bus Rail,
Subnests in the output list may be preceded by a scale parameter, which is applied to the composite (or logsum) utility of the subnest before evaluating this choice nest. The scale parameter should be greater than 0, and must not exceed 1.0. For utility-based models, if one alternative has a scalar, all others must also have scalars. For example:
split=total,0.5,auto,1.0,pt,
Scalars of 1.0 cannot be omitted in XCHOICE. Examples are:

SPLIT = TOTAL 1.0 Car 0.5 PT 0.4 WalkCycle,
where scale parameters are applied to the PT and walk/cycle subnests. Car either is a distinct alternative, or a subnest with a scale parameter of 1.0. Where the same scale parameter applies to several sub-nests, the scale parameter may be specified once followed by the list of relevant subnests grouped together by use of brackets. An example is:
SPLIT = TOTAL, 0.4 Car 0.5 (Bus Rail),
where the bus and rail subnests share the same scale parameter, and a different value applies to the car subnest.

Keyword STARTMW Description The calculations performed by the logit choice model require a number of working matrices (or MWs) to be allocated for the use of the XCHOICE command. The STARTMW keyword specifies a numeric value corresponding to a particular working matrix which is higher than that of any other working matrix referenced in the script. Working matrices from the STARTMW value upwards are used by the XCHOICE command, and should not be used elsewhere in the script. Where a Matrix script contains several XCHOICE commands, the same STARTMW value may be used in all instances. Specifies forecast utilities. If there is more than one utility, their order must be the same as that used in the ALTERNATIVES keyword. See also BASEUTILSMW and DUTILSMW (utility-differences) for incremental models; the UTILITIESMW keyword is not used in conjunction with DUTILSMW.
UTILITIESMW
Summary of syntax usage differences between XCHOICE and CHOICE

In each XCHOICE, there must be one and only one case-insensitive Total in a SPLIT clause. Total is the starting node for mode split. All matrix valued keywords must end with MW. For example:
UTILITIES is now UTILITIESMW COSTS is now COSTSMW
DEMANDMW is only available to pure mode choice models where
input demand is a matrix. In destination-choice or mixed modeand destination-choice models, use DEMAND instead. DEMAND in XCHOICE can be any of these values: Constant Variable Array without index Array with constant index Array with variable index
For example:
.... array tripsfromi=5 if(i==1) tripsfromi[1]=100 tripsfromi[2]=200 tripsfromi[3]=300 tripsfromi[4]=400 tripsfromi[5]=500 endif myvar=100 myindex=3 ... DEMAND =100, .OR. DEMAND =myvar, .OR. DEMAND =tripsfromi, .OR. DEMAND =tripsfromi[1], .OR. DEMAND =tripsfromi[myindex],
For mixed mode- and destination-choice models, DESTSPLIT must start with alternatives prefixed with dest (for example, destx), and end with corresponding alternative name, for example x. Here is an example:
ALTERNATIVES=car b c, SPLIT = TOTAL 0.01 destcar destpt, DESTSPLIT = destcar 0.02 car, DESTSPLIT = destpt 0.03 pt,
Both x or destx are acceptable in the higher level SPLIT clause. In previous example, both of these two following cases work:
SPLIT = TOTAL 0.01 destcar destpt,
Or
SPLIT = TOTAL 0.01 car pt,
For utility-based model, if one alternative has a scalar, all others must also have scalars, example:
split=total,0.5,auto,1.0,pt,
Scalar 1.0 can be omitted in CHOICE, but it cannot be omitted in XCHOICE.

OCOMPCOST and OCOMPUTIL in CHOICE are replaced by a new keyword SPLITCOMP in XCHOICE. Unlike OCOMPCOST and OCOMPUTIL, which can be used only on the upper most level of a nested mode choice structure, SPLITCOMP can be used on any level to get nest specific composite costs or composite utilities.
COMP
Computes a variable, matrix, or matrix element.

VAR=expression MW[]=expression (INCLUDE EXCLUDE)
The COMP statement is probably the most important of all the statements in the program. It is used to compute variable and work matrix values.
COMP keywords
Keyword MW Subkeyword |KN| Description Value for a working matrix. You can specify this keyword in two formats: MW[n] Defines the value for row n of a working matrix. Matrices can contain up to MAXMW rows, as indexed by n. The index n may be either a constant or a variable name. The program solves the expression for all values of J (1 through Zones), filtering values indicated by any INCLUDE or EXCLUDE lists on this statement. Within a JLOOP statement, the program only solves the expression one time only, with J being the value of the loops current J. MW[n][o] Defines the value for column o in row n. The second index, o, must be between one and Zones. The program solves the expression one time only, with J being the loops J if within a JLOOP, or 1, if not.

Keyword MW Subkeyword EXCLUDE |IP| Description Optional. Values of J excluded when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the EXCLUDE list. If the current J is on the list, the program does not evaluate or store the expression for that J. Specified values can range from 1 to the highest zone number. Filter applies to all MW[n] values on the COMP statement. Not permitted if COMP statement within JLOOP ... ENDJLOOP block. Always processed after INCLUDE subkeyword. By default no zones are excluded. MW INCLUDE |IP| Optional. Values of J included when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the INCLUDE list. If the current J is not on the list, the program does not evaluate or store the expression for that J. Specified values can range from 1 to the highest zone number. Filter applies to all MW[n] values on the COMP statement. Not permitted if COMP statement within JLOOP ... ENDJLOOP block. By default all zones are included.

Keyword VAR Subkeyword |KN| Description VAR is the name of a variable where the result of expression is to be stored. The name may be as long as desired (within reason). The expression is solved one time for each encounter, with J being either one (not in JLOOP), or the value of the JLOOP J. If expression results in a character string, the variable must be a character string variable. All variables are assumed to be numeric variables, unless their first appearance as a result in a COMP statement is with an expression that results in a character string. Examples:
abc = '123' def = 123 abc = def ; invalid: abc has been declared a string abc = abc+'456' ; valid abc = abc+def ; messy -- dont mix types jkl = 1 ; jkl is declared numeric jkl = xyz ; invalid: xyz is declared a string (later) xyz = 'xyz' ; xyz is declared a string
The program does not always bother computing expressions for variables that are not used as input to some process. In the above examples, the statements with jkl= might never be executed, because jkl is never used.
If a COMP statement includes any INCLUDE or EXCLUDE filters, the filters apply to all MW[]= values, and special matrix functions on the statement, no matter where they appear on the statement. EXCLUDE is processed after INCLUDE. INCLUDE and EXCLUDE may not be specified within a JLOOP block.
Supported expressions
Special Matrix variables:

MW[] MI.n.name MI.n.matnum MI.n.name.T MI.n.matnum.T
The expression is a standard Cube Voyager numeric expression, but there are also certain special variables names that may be used within it.
Variable MW[Rexpression] Description Value from any work matrix; the column index (not explicitly expressed) will be supplied as J. Rexpression may contain nested MW[]; be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression. Value from the MATI[n].name matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n], must be a constant. MI.n.name[Cexpression] is a variation; the column index is computed. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
MI.n.name
MI.n.matnum
Value from the MI[n].matnum matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n] and the matnum must be constants. MI.n.matnum[Cexpression] is a variation; the column index is computed. Special cases for the above two MI formats. The appended .T indicates to use the transposed values for the matrix. This triggers a preprocessor program that will transpose the matrix. Thus, the retrieved cell represents the J-I value, instead of the I-J value. If a column index is used, the retrieved cell will represent the value of the cell for the index to I. Transpose operation can only be applied to binary data. Value from the ZDATI[n].name matrix; the zone index (not explicitly expressed) will be supplied as I. ZI.n.name[Cexpression] is a variation; the zone index is computed.
MI.n.name.T MI.n.matnum.T
ZI.n.name
The expression may contain the following special matrix row processing functions: ROWSUM() ROWCNT() ROWMIN() ROWMAX() ROWAVE() ROWFIX() ROWFAC() LOWEST() ROWADD() ROWMPY() ROWDIV() ROWREAD() In addition to the standard numeric expression functions (abs, exp, int, ln, log, max, min, round, sqrtsee Expressions on page 30 for more details), some special purpose functions are available. The matrix oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists), and should not be used within JLOOP blocks and MW[]= expressions. Most of these functions could be duplicated with a combination of MW[]= statements. The function format has two advantages: coding is much easier, and processing is more efficient. Combining functions on a single statement is permissible; they will be processed in appropriate order. Example: DUMMY = ROWFAC(3,1.5) + ROWFIX(3) will factor matrix 3 and then integerize it. In the following matrix function descriptions, the first argument (mw) indicates the work matrix to process, and must be specified. If lo,hi is allowed, and lo is supplied, and hi is not, hi will be set to lo. Lo and hi are inclusive values. If an invalid argument is detected by a function, the function will return a zero, without any diagnostics.
Matrix function descriptions
Function1 ARRAYSUM(array_name) LOWCNT Description Returns sum of an array (see Examples on page 534). Stores actual number of cells used in LOWEST. Warning: Dividing by LOWCNT, if it is 0, will cause a program error message. In some cases, you can use the max function to prevent this. For example:
W[mw][I] = LOWEST(mw,4,.01,5,I) /max(1,LOWCNT)/ 2
Matrix function descriptions (continued)

Function1 LOWEST (mw,#) LOWEST(mw,#,lo,hi) LOWEST(mw,#,lo,hi,z,z,...) Description Sum of lowest # cells Sum of lowest # cells where lo>=value<=hi Sum of lowest # cells but exclude specific cells LOWEST is quite useful for computing an intrazonal value based upon the proximity to the nearest zones. The range of arguments accommodates most situations. Use lo and hi to exclude possible dummy zones that appear as zero in the row. Use z to exclude specific zones; normally, the intrazonal cell (I) would be excluded. This exclusion is in addition to any on an EXCLUDE list. NOTE: LOWEST treats zeros as regular numbers. Since all MWs are initialized to zeros, use caution when applying LOWEST with no range specified. MATVAL (F, M, I, J [, E]) Returns random access values from MATIs (see Examples on page 534). F = MATI[#] M = Matrix # I=I J=J E = the value to return if the request for the cell is invalid. Each of the arguments can be an expression, variable, or constant. Because the arguments are dynamically set, the program can not pre-edit the values. For example: K = matval(3,1,I,J,-1) indicates to get the value from I to J from matrix 1 on MATI[3]. Since this is direct access, the function can be slow in some cases and quite efficient in others. The Matrix program maintains a cache of the matrix rows to try to help speed up the process. However, some types of processing will not be helped much by the use of the cache. In general the larger the cache, the more efficient the access will be. The cache size is specified by the PARAMETERS MATVALCACHE.

Function1 ROWADD(d,s1...sn) Description Add matrix mw[1] + mw[sn] into mw[d] Same as:
MW[d] = MW[s1] + MW[s2] + MW[sn]
ROWAVE(mw) ROWAVE(mw,lo,hi) ROWCNT(mw) ROWCNT(mw,lo,hi)
Average cell value for nonzero values Average cell value for nonzero values, including only cells where: lo>=value<=hi Number of cells with nonzero values Number of cells with nonzero values, but include only cells where: lo>=value<=hi (this can include 0). Divide MW[d] by MW[s] making all divided-byzero cells equal to 0. Same as:
JLOOP IF (MW[s] == 0) MW[d] = 0 ELSE MW[d] = MW[d] / MW[s] ENDIF ENDJLOOP
ROWDIV(d,s)
ROWFAC (mw,fac)
Factors the row by fac. Same as:

MW[mw] = MW[mw] * fac
ROWFIX(mw) ROWFIX(mw,n)
Integerize mw (start at column intrazonal + 1, with rounding factor = 0); Integerize mw (start at column n, w/ rounding factor = 0)

Function1 ROWFIX(mw,n,rnd) Description Integerize mw (start at column n, using specified rounding factor, rnd) ROWFIX integerizes the values in each cell of the matrix (that is, drops all fractional portions of the number). ROWFIX ensures the integer total is consistent with the original total. It integerizes each cell after adding the rounding factor and the accumulated fractional portions from the previously treated cells. With a rounding factor of 0, each cell is truncated and its fractional remainder is carried to the next cell. With a rounding factor of 0.5, each cell is rounded to the nearest integer and the difference (original rounded) is carried to the next cell. If the process always begins at zone 1, the lowest numbered zones never gets their fair share of the fractions. To eliminate this bias, the default condition starts at the cell after the intrazonal cell and wraps around until the intrazonal cell is the last cell processed. The optional second argument specifies which cell the process is to end with. ROWMAX(mw) ROWMIN(mw) ROWMPY(d,s) Maximum value in the row Minimum value in the row Multiply MW[d] by MW[s] Same as:
MW[d] = MW[d] * MW[s]

Function1 ROWREAD(MW#, MATI#, I, M) Description Reads a random row from the input matrix and places it in the current row of the referenced working matrix. Allows for processing input matrix data not in I zone ascending sort order. Where: MW# Desired MW to which the record will be saved MATI# Number of the input matrix file being accessed (Mati[#]) I Desired origin zone M Desired matrix number on the input file to process Example:
run pgm=matrix FILEI MATI[1]=trips00.mat ; input matrix ; with random I zone order from ; external user program FILEO MATO[1]=Fixed_trips00.mat,mo=1-20, dec=20*8 ; Matrix automatically runs an ILOOP ; from I=1 to I=ZONES loop m=1,20 ; loop over the 20 matrices ; in the input file x=ROWREAD(m,1,I,m) ; read row for the ; current value of I and places it ; in the work matrix endloop endrun
ROWSUM(mw) ROWSUM(mw,lo,hi)
Row total Row total, but include only cells where: lo>=value<=hi
1. mw is a working matrix number (that is, MW[1]) lo is the lo end of a range hi is the hi end of a range; defaults to lo if not specified
Example
MW[2]=J MW[K]=MW[2] * MW[5] / SQRT(A*MW[3][MW[22]]) A=1, B=2, MW[A]=A+B INCLUDE=1-5,8,47-93 MW[3]=5*A, MW[4]=MW[3]*2, MW[K][I%10+1]=ODD, INCLUDE=1-100,401-500, EXCLUDE=90,93,452; will apply to all MW[]s= ABC=LOOKUP(DEF)*3 ; move input matrices to work areas MW[11]=MI.1.1, MW[12]=MI.1.2, MW[13]=MI.1.3 MW[21]=MI.2.1, MW[22]=MI.2.2, MW[23]=MI.1.3 JLOOP J=I MW[6]=J ; store only at intrazonal column ENDJLOOP set var=sumaf1,rowsum1 ; clear variables lookup name=f1, file=f1.txt JLOOP rowsum1 = rowsum1 + mw[1] ; get total for mw[1] mw[2] = zi.1.attr[j] * f1(mi.12.1) ; A * F's sumaf1 = sumaf1 + mw[2] ; sum A*F endjloop ; Next line is same process done with functions: rowsum1=ROWSUM(1) mw[2]=zi.1.attr[j]*f1(MI.12.1) sumaf1=ROWSUM(2)
CONTINUE
Jumps to end of loop. Use CONTINUE to immediately jump to the end of a loop, bypassing all stack statements between it and its associated end of loop. If it is within a LOOP or JLOOP block, control passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise, stack processing for the I zone is terminated but output and zonal reporting statistics will not be bypassed.
Example
LOOP L1=1,3 IF (!(condition)) CONTINUE ENDLOOP IF (condition) CONTINUE ; no more processing for this origin zone LOOP L2=K1,K2,KINC
JLOOP EXCLUDE=25-50,88 IF (condition) CONTINUE ; jump to ENDJLOOP . ENDJLOOP LOOP L3=L2,L2+5 IF (condition) CONTINUE ; jump to ENDLOOP for L3 . ENDLOOP ENDLOOP
EXIT
Exit the program before the end of zone processing Upon encountering EXIT, the program immediately terminates stack processing, and goes to the end of I loop processing.
Example
FILEI
and for important limitations when using Application Manager.

Selects input data files. DBI (FIELDS name SORT DELIMITER AUTOARRAY MAXRECS JOINTODBI(JOINTOFIELDS)) LOOKUPI MATI (PATTERN FIELDS) RECI (FIELDS name SORT DELIMITER MAXERRS LISTERRS MAXRECS MAXSCAN)
ZDATI (Z SELECT name (DEFAULT) AVE AVEX0 CNT FIRST LAST MAX MIN SUM) Note for v4.0 and later: Significant changes in RECI/RECO processing have been made from v3.2.x series. If running scripts developed under v3.2.x or earlier and using the RECI/RECO keywords you may need to make some slight modification to your scripts for proper processing. Refer to the descriptions below for the updated coding and comments on the processing.
FILEI input data is normally entered in either matrix format or zonal
vector format. Matrix data is read dynamically (at the start of each I loop), and must be in origin zone (I) order, whereas zonal data is read prior to the initiation of the I loop, and need not be in any specified order. Data from these files is accessed via COMP statements, and are identified as MI.n.name and ZI.n.name. The n designates subscript of the file, name designates the matrix name or number. Cube Voyager matrices can have names and/or numbers, other matrices have only numbers, and zonal data files have names only. Example: MI.1.3 indicates matrix number 3 on the MATI[1] file. ZI.6.POP indicates the POP variable from ZDATI[6] file. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
On the FILEI statement the subscript is either explicitly, or implicitly, specified. MATI=... defaults to MATI[1], and MATI[3]=name3,name4,name5 sets up MATI[3], MATI[4], and MATI[5]. Since it is required that ZDATI files have variables explicitly defined for them, the vector form of ZDATI (ZDATI=file1, file2...) will be treated as an error. When an input file is used in an expression, it may have an additional subscript appended to it to specify a zone number. For matrices, the subscript references the column within a row, and for zonal data, it references the nth item in the vector. Zonal data can be viewed as having zones rows with one column per zone, or as
one row having zones columns (users choice, it doesnt matter). If there is no subscript specified, the current value of J is used. J will always be in the range 1-zones. Example: MI.6.3[I] accesses the intrazonal cell. ZI.1.TRMTIME[I] and ZI.1.TRMTIME[J] reference the origin and destination terminal times, respectively. Matrices can be input as either binary matrices, EMME/2 matrices stored in an EMME/2 data bank file, or as data on ASCII or DBF type records. In the latter case, PATTERN and FIELDS must be specified. ASCII type records are more subject to variation (empty fields, invalid values, etc.), and the program is a bit more tolerant with them. If a J or M is out of range, the values for the field are ignored. On the other hand, if the field contains non-numeric data, it is treated as an error, and further processing of the record is terminated. If MATI specifies an EMME/2 data bank file, then the file name must be emme2ban with no file extension. The Matrix program will not recognize any other file name as an EMME/2 data bank file. In this case, input matrices referenced in the script can be referenced by their matrix number in the bank just as they are in a binary Cube Voyager matrix file. The FILEI file keywords ZDATI, RECI, and DBI can point to elements in a multidatabase (MDB) file by designating the filename followed by a backslash and the element name. The program will generate a temporary file of records, each record containing all the variables in the element. If the FILEI file keyword value is followed by variable definitions, those definitions are ignored, or in some cases, cause a fatal termination. On a ZDATI file name, you can specify a definition for Z to indicate which MDB element represents the zone number. Z= is not necessary if one of the element variables has an appropriate name for the zone number (see description of ZDATI for details). If ZDATI specifies an EMME/2 data bank file, the Matrix program can read the scalar and vector matrices stored in the EMME/2 data bank file as zonal data records. To specify an EMME/2 data bank file, the file name must be emme2ban with no file extension. The Matrix program will not recognize any other file name as an EMME/2 data bank file.
FILEI keywords
Keyword DBI Subkeyword |KF9| Description Name of a DBF file, MDB data element, or an ASCII record file with either delimited (separated by a space or a comma or combination of both space and comma) or fixed format records. If you specify a DBF file, the program recognizes the file and the fields. Reference the field names in the DBF header directly in the script as DI.#.fieldname. Do not explicitly define the variables in the DBI statement. If you specify an MDB\element file and name, the program recognizes the file and the fields. Reference the field names in the MDB data element directly in the script as DI.#.fieldname. Do not explicitly define the variables in the DBI statement. If you specify an ASCII record file, define all variables that you want the program to recognize (DBI.#.name) in the DBI statement, using the appropriate keywords. ASCII record files are either a fixed format text file (fixed field locations and lengths), or free format. You must indicate which format is used in the definition of each field. Indicate free format with field definitions containing a single number. Indicate fixed format fields by using name=lo[-hi] or field=lo[-hi] syntax, where lo is the first column number of the field and hi is the last column. (Indicate a single-column character with the hi column number the same as the lo column number.) Define a field as a character variable by appending (C) to the name. For example, TITLE(C)=1 would define the variable named DI.#.TITLE as a character variable, and would read the data from the first data field in the input file You can specify the delimiters for free-format records using the DELIMITER keyword.

Keyword DBI (continued) Subkeyword Description The following special variables are available for all file formats: DBI.# String variable containing the full data record DBI.#.NUMFIELDS Number of defined data fields DBI.#.NUMRECORDS Number of data records in file DBI.#.RECNO Number of the currently processed record Different arrays are available. Each array is dimensioned as [DBI.#.NUMFIELDS]. All the values (except Name and Type) are updated each time the record is processed. The arrays are: DBI.#.NAME Name of the field DBI.#.TYPE Type of field (either N for numeric or C for character DBI.#.NFIELD Numeric value for the field (0 if DBI.#.TYPE=C) DBI.#.CFIELD String value for the field (Null if DBI.#.TYPE=N) DBI.#.FIELDERR 1 if the field had a format conversion error DBI.#.FIELDERRCNT Cumulative count of errors for this field. See More on DBI on page 489. DBI AUTOARRAY |S| Designates the name(s) of the field(s) that are to be stored in arrays with the specified name. An array for each named field will be generated and populated with values from the DBI records. If you enter a value of ALLFIELDS, all the fields will be placed into arrays (no other names need be supplied). You can reference each array as DBA.#.name[Index], where Index may be 0-DBI.#.NUMRECORDS. If Index is less than 0 or greater than NUMRECORDS, the value in DBA.#.name[0] is used. By default, the value at ARRAY[0] will be 0 for numeric fields and NULL for character fields. You can provide a substitute value for invalid Index processes, such as DBA.1.Name[0] = 'ERROR' or DBA.1.Name[0]=999999. Note that if the name is included in a SORT, [0] will be revised during the SORT, because the SORT routine uses that cell for temporary storage.

Keyword DBI Subkeyword DELIMITER |S2| Description Use to specify two different controls for free-format records. DELIMITER[1] specifies the field-separator characters. The default values are ,t; where t is used to designate a tab:
DELIMITER[1]=" ,t"
DELIMITER[2] specifies escape-character sequences that permit field-separator characters in free-format records. Specify characters in pairs, the character that marks the start of an escape sequence along with the character that marks the end of an escape sequence. Upon encountering the starting escape-sequence character, Cube Voyager treats all subsequent data as part of the same record until it encounters the ending escape-sequence character, even if it encounters a field-separator character. The default value specifies single quotes, double quotes, parenthesis, brackets, and braces as escape character sequences:
DELIMITER[2]="""''()[]{}"
NOTE: You must enclose the entire value in double quotes or single quotes. If you include a single space as the last character in DELIMITER[2], Cube Voyager will remove the leading and trailing character from any string it reads. The starting escape-sequence character in DELIMITER[2] cannot be a field-separator character in DELIMITER[1]. You can specify both DELIMITER[1] and DELIMITER[2] in one expression: Specify DELIMITER= followed by two values enclosed within quotes and separated by a space or a comma. Cube Voyager automatically removes leading spaces from all fields, unless the field is enclosed in an escape-character sequence and DELIMITER[2] does not contain a space as its last character. Example Suppose you set a comma as field-separator and double quotes as an escape sequence:
DELIMITER=',' '""'
When reading the following input data:

John Smith, "Oakland, CA", USA
Cube Voyager reads three fields: John Smith, Oakland, CA, and USA.

Keyword DBI Subkeyword FIELDS |IPV| Description An optional method for defining data fields in the input file. Used only when the DBI records are fixed or free format. If this keyword is present, only the fields specified will be extracted. The values specify the columns or fields of the DBI file records where a desired field is located. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi), that sets the format as fixed. If a data field is defined by a single number (field number on the records), that sets the format as freeform. All data fields must be defined in the same format. For example:
FIELDS=1-5,6-10,21-25
Specifies that the data is fixed format and DBI.#.NFIELD[1] is in columns 1-5, DBI.#.NFIELD[2] is in columns 6-10, and DBI.#.NFIELD[3] is in 21-25.
FIELDS=6,9,13
Specifies that the data is in free format and defines DBI.#.NFIELD[1] comes from field number 6, DBI.#.NFIELD[2] comes from field number 9, and DBI.#.NFIELD[3] comes from field number 13. Optionally, FIELDS can specify multiple successive fields with a single specification (providing all fields are the same type, N or C). For example:
FIELDS=6(7)
Specifies that DBI.#.NFIELD[1]DBI.#.NFIELD[7] will be obtained from fields 6 through 13 of the data records.
FIELDS=6(C7)
Specifies the same, but those fields would all be character values. You can reference these field values as DBI.#.NFIELD[#], DBI.#.CFIELD[#] or as DI.FIELD# in script statements. DBI JOINTODBI |I| Specifies the number of the input DBI file to join this DBI file to. If JOINTODBI is specified for a DBI file, then the SORT keyword must also be specified. The field names referenced by the SORT keyword define the join key. You must also specify the JOINTOFIELDS subkeyword.

Keyword DBI Subkeyword JOINTOFIELDS |SV8| Description Specifies the fields on the file referenced by JOINTODBI that corresponds to the join key fields identified by the SORT keyword. This keyword can have fewer referenced field names than the SORT keyword but cannot have more than the number of sort keys. For example:
FILEI DBI[1] = "TRIPRECORDS.DBF", SORT=HHNO,PERSNO TRIPNO FILEI DBI[2] = "PERSON.DBF", SORT=HHID,PERSID JOINTODBI=1 JOINTOFIELDS=HHNO,PERSNO
In this example, DBI file 2 is a person-level survey record file. This file contains the fields HHID and PERSID, which uniquely identify the person record, along with other household and person-level demographic data fields. DBI file 1 contains the person-level trip records from a travel survey. This file contains the fields HHNO, PERNO, and TRIPNO, which uniquely identify each person-trip record, along with other trip-related data fields. Note that the key field name on which the join is performed does not need to match in the two files. With the files joined, script statements that process a trip record are linked to the corresponding person-level data file, enabling trip-based computations to directly reference the household and person-level characteristics in the joined file. DBI MAXRECS |I| Limits the number of records read from the DBI file. If the DBI is not a DBF file, the program treats both zero length and blank records as legitimate records. If the file is a DBF file, deleted records (flagged with a *) are not counted as records.

Keyword DBI Subkeyword NAME |IP| Description Name of a variable to extract from a text format record. The value contains the location of that variable on the data record. You can reference the variable in other parts of the script as DI.#..name. If the name has (C) appended to it, the variable type is character. If the name has nothingor (N) appended, the variable type is numeric. The value must be either a single integer, or a pair of integers (separated by a dash). If the records are in free format, the values must be single integers indicating the field number in the data record. If the input records in fixed format, the value will be lo-hi; if the field is a single column, it must be designated as lo-hi, where lo=hi=the column number of the data field. DBI SORT |S9| Designates that the input records are to be processed in a specified sorted order. The values are the names of the variables that the sort is based upon. There may be up to nine sort keys. If a sort name is preceded by a minus (-) sign, that field is to be sorted in descending order. If there is no leading sign, or there is a preceding plus (+) sign, that field is to be sorted in ascending order. Name of file containing records for a lookup function implemented with the LOOKUP control statement. Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI. MATI |KFV20| Specifies the input files with matrix data. If the file specifies a Cube Voyager, TP+, MINUTP, or Tranplan binary matrix file, or a standard data base (DBF) file, the program will automatically detect it. If it is not detected as one of those, it is assumed to be an ASCII text file. If it is not a binary matrix file, PATTERN and FIELDS must be associated with the MATI. If the input file name is specified as emme2ban with no file extension, then the Matrix program will recognize the file as an EMME/2 data bank file. You can reference input matrices from an EMME/2 data bank file in the script by matrix number. For example if FILEI MATI[1]=emme2ban, then MW[1]=mi.1.10 in the script would place matrix values from MF10 from the EMME/2 data bank into the internal working matrix MW[1] for each I-zone processed. See Example of FILEI statements on page 494 for an example of MATI usage when accessing an EMME/2 data bank file.
LOOKUPI
|FKV999|

Keyword MATI Subkeyword FIELDS |S| Description Specifies the data fields to be read from an input record. Any one (and only one) format may be used to specify the fields. If the MATI file is a database file, the values in FIELDS must be names found in the dbf dictionary. A range of names (namename) may be used to specify a string of consecutive fields. If the file is not a DBF, its format may be either fixed or variable; the first field definition establishes the format. If the first field value is a number, the format will be fixed; if it begins with a letter (not a digit), the format will be variable. With variable format, every field value must end with a number (only the first field value is required to have a leading non-digit). Ranges of variable format fields may be specified. For example: #4-6,10,13,2. A leading # is recommended for variable format, although any character string is acceptable. The program extracts the number from the right end of the definition; leading non-digits are ignored. With fixed format, the field values define the positions on the record where a data field is located. The field values may be entered as single values (single column), pairs of numbers (beg-end), or as a group of three (beg-end-numflds) to indicate a series of equal length fields. Example: FIELDS=13, 6-8, 10,11-20-8. For a PATTERN=IJM:V, this example would indicate that I is in columns 1-3, J is in columns 6-8, M is in column 10, and eight data fields (each 10 characters wide) are in columns 11-20, 21-30,etc. (Note: When reading with fixed format, the highest begin column number may not exceed 2047. For example, for a record longer than 2047 bytes, FIELDS=1-10-204 is OK, while FIELDS=1-10-205 will get a warning because the program is unable to read in the last field. This limit is not applicable to variable format files.) When the field value of M is set to zero, it indicates that the starting matrix number is not included in the input data, hence, implied, and the matrix number always starts at one for each record. The specification of FIELDS with implied matrix number will be shown in the example in the next section.

Keyword MATI Subkeyword PATTERN |S| Description Sequence of letters that specifies how the program processes the associated text or DBF MATI file. The pattern has two portions separated by a colon: a base portion and a repeating portion. In the pattern definition: There must be a single I, J, and V. I must be the first letter in the base portion, and V must be in the repeating portion. There may be one M to specify the starting matrix number. If there is no M, matrix 1 is assumed. The highest M that the program recognizes is 255. If there are multiple characters in the base portion, the last character in the base portion indicates which variable is incremented for each repeating set.
Valid combinations are: IJ:V I J values for J,J+1,J+2... IMJ:V I M J values for J,J+1,J+2... IJM:V I J M values for M,M+1,M+2... I:JV I sets of J and V I:VJ I sets of V and J IJ:VM I J sets of V and M IJ:MV I J sets of M and V IM:JV I M sets of V and J IM:VJ I M sets of J and V I:JVM I sets of J, V, and M I:JMV I sets of J, M, and V I:MJV I sets of M, J, and V I:MVJ I sets of M, V, and J I:VJM I sets of V, J, and M I:VMJ I sets of V, M, and J

Keyword MATI Subkeyword PATTERN (continued) Description This method allows Cube Voyager to read any commonly encountered input format. It is necessary to have FIELDS specified in conjunction with PATTERN. The above examples assumed that the FIELDS values implied variable format and that there was an appropriate number of FIELDS values specified. If the values specified in FIELDS do not align correctly with the PATTERN, a warning message is issued. When reading a data record, the program aligns the next FIELDS value with the next letter in the PATTERN, and extracts the data. When the PATTERN is exhausted, the reading continues from the beginning of the repeating portion of the PATTERN. This continues until the FIELDS list is exhausted. If the FIELDS list is exhausted before the end of the PATTERN, reading is terminated without storing the last repeat value. Note that the data values need not be read in sequential order from the input records. The FIELDS values can be used to specify any order. See More on MATI PATTERN on page 490.

Keyword RECI Subkeyword |KF| Description Name of a DBF file, an element in a multidatabase file, or an ASCII record file with either delimited or fixed format records. If the file records are delimited (separated by a space or a comma or combination of both space and comma), or if the file records are fixed format all variables that are to be recognized (RI.name) must be defined in the FILEI RECI statement using the appropriate keywords described below. If the file format is DBF or MDB, the program will recognize it and the field names in the DBF or MDB header can be referenced directly in the script as RI.fieldname. For a DBF or MDB file, the variables should not be explicitly defined on the statement. When RECI is not a DBF or MDB file, it is considered a text file (fixed field locations and lengths), or free format. It is the user responsibility to indicate which format is to be used; this is accomplished by the definition of the first variable. If that field definition is a single number, the records will be considered free format. Fixed format variables are defined by use of the name=lo[-hi] or field=lo[-hi] syntax, where lo is the first column number of the field and hi is the last column. A single column character does need to have the hi column designated as the same as the lo column number. To define a variable as a character variable, the name has (C) appended to it. For example, TITLE(C)=#1 would define the variable named TITLE as a character variable and data read from the first data field on the input file would be considered as character data. The user can also specify the delimiters for free format records using the DELIMITER keyword. If there are any RECO statements, all RECI variables (RI.name) on the input file are automatically copied into equivalent RO.name variables immediately when a record is read. The RI.variable attributes are ported to the corresponding RO.variables. Only variables with the RO.prefix can be written to the RECO file.

Keyword RECI (continued) Subkeyword Description The following special variables are available to the user for all file formats: RECI String variable containing full data record RECI.NUMFIELDS Number of defined data fields RECI.NUMRECORDS Number of data records on the RECI file RECI.RECNO Number of the current record being processed The program also makes four different arrays available to the user. Each array is dimensioned as [RECI.NUMFIELDS]. The arrays are: RECI.NAME Name of the field RECI.TYPE Type of field (either N for numeric or C for character RECI.NFIELD Numeric value for the field (0 if RECI.TYPE=C) RECI.CFIELD String value for the field (Null if RECI.TYPE=N) The NFIELD and CFIELD values are updated to the values from each record as the record is read. If a RECI statement is present, the program enters a record processing loop instead of the traditional I Loop. Thus, MATIs are not read unless a MATVAL function is used, and FILEO MATO keywords should not be used. As each RECI record is read, it is processed against the script statement stack. The PRINT statement allows the user to write out any portion of the input record plus any computed variables. The record processing loop sets I=1 and reads records until the end of file is found where it sets I=0. To test on end of file the IF (I=0) condition can be used. See More on RECI on page 492 for some examples. RECI DELIMITER |S2| Use to specify two different controls for free-format records. For details, see DELIMITER description under DBI keyword on page 475. Usage of DELIMITER is the same under both keywords.

Keyword RECI Subkeyword FIELDS |IPV| Description Only available in v4.0 and beyond. Is an optional method to NAME for defining data fields on the input file and it is used only when the RECI records are fixed or free ascii format. If this keyword is present, only the fields specified will be extracted. The values specify the columns or fields of the RECI file where a field is located. If a data field (FIELDS= or name=) is defined by a pair of numbers (lo-hi), that sets the format as fixed. If a data field is defined by a single number (field number on the records), that sets the format as freeform. All data fields must be defined in the same format. For example: FIELDS=15,6-10,21-25 specifies that the data is fixed format and RECI.NFIELD[1] is in columns 1-5, RECI.NFIELD[2] is in columns 6-10, and RECI.NFIELD[3] is in 21-25. FIELDS=6,9,13 specifies that the data is in free format and will define RECI.NFIELD[1] RECI.NFIELD[2] RECI.NFIELD[3] coming from data fields number 6, 9, 13 respectively. Optionally, FIELDS can specify multiple successive fields with a single specification (providing all are the same TYPE, N or C). FIELDS=6(7) specifies that RECI.NFIELD[1]RECI.NFIELD[7] will be obtained from fields 6 through 13 of the data records. FIELDS=6(C7) would be the same, but those fields would all be character values. These fields can either be reference as RECI.NFIELD[#], RECI.CFIELD[#] or as RI.FIELD# in stack statements. Flag that indicates if errors should be listed to the run print file. Default value is F. If LISTERRS=T then MAXERRS automatically defaults to MAXERRS=1000. This is to prevent excessive listing of error messages to the run print file. If the user wishes to see more than 1000 error messages in the run print file then he must explicitly code the MAXERRS value desired. Maximum number of errors allowed in reading the RECI records before a fatal error message is returned. Default value is no limit. The default setting will not return a fatal error message no matter how many errors are detected. Places a limit on the number of records to be read in from the RECI file. Default value is no limit.
RECI
LISTERRS
|?|
RECI
MAXERRS
|I|
RECI
MAXRECS
|I|

Keyword RECI Subkeyword MAXSCAN |I| Description Allows the user to limit the file sampling for text records in order to reduce front end time on very large files. The program normally scans the entire file to obtain the longest record, the number of records, the maximum length of each field, etc. That could be quite time consuming, and not really productive for very large files such as the census files. If the user is certain that all the records are the same length, the use of this keyword can reduce front end time. This value will be used only if the format is fixed, and there is no SORT specified. The value must be >= 10, if specified. This control should not generally be used and was added primarily for internal Citilabs use. I maybe save time if processing very large data files. Name of a variable to be extracted from a text format record and the value will be the location of that variable on the data record. It can be referenced in all other parts of the script as RI.name. If the name has (C) appended to it, the variable will be considered as character. If it has nothing, or (N), appended, the variable will be considered numeric. The value must be either a single integer, or a pair of integers (separated by a dash), to designate where the variable will be obtained from each record. If the records are read in free format, the values must be single integers indicating the field number on the data record. If the input records are read in fixed format, the value will be lo-hi; if the field is a single column, it must be designated as lo-hi, where lo=hi=the column number of the data field. Designates that the input records are to be processed in a specified sorted order. The values are the names of the variables that the sort is based upon. There may be up to five sort keys. If a sort name is preceded by a minus (-) sign, that field is to be sorted in descending order. If there is no leading sign, or there is a preceding plus (+) sign, that field is to be sorted in ascending order. Specifies the input files containing zonal data. There can be up to 10 zonal data files. Zonal data is data which is specific for each zone. Every zonal record must include a field that identifies the zone to which the record data applies. Aside from the zone number, any fields from the record can be extracted and used by the program.
RECI
NAME
|IP|
RECI
SORT
|S5|
ZDATI
|KFV10|

Keyword ZDATI (continued) Subkeyword Description The file format can be: ASCII, DBF, MDB, EMME/2 data bank, or a Cube Voyager binary network. The program will try to detect what type of file it is. If it cannot identify the file as a DBF, MDB, EMME/2 data bank, or a Cube Voyager network, it will assume ASCII. When the program detects a Cube Voyager network file, it opens the node database portion of the file as zonal data. If the file is of ASCII format, the fields to be extracted must be named and identified on the ZDATI statement by either relative field number, or by exact column positions on the records. The field that contains zone number must be specified using 'Z=' keyword. If the file is a DBF, MDB, or a Cube Voyager network, it is not necessary to name the fields to be extracted. All fields will be extracted and can be referenced, in the script, by existing field names from the input file. The specification of zone number field is optional for those two file formats. If 'Z=' is present, the specified field will be used to extract zone number. Otherwise, the program will try to determine the zone number field based on file type. For DBF or MDB files, the program will go through all field names to find a match with one of the following possible zone field names, in the given order: {Z, I, J, ZONE, ZONA, TAZ}. The first matched name will be used to extract zone number. (Note: For files with more than one possible zone field from the list above, it is recommended to specify zone number field explicitly to ensure the correct field is used.) For Cube Voyager network files, node numbers (N) will be used as zone numbers by default. If the file is an EMME/2 data bank file, then the file name must be emme2ban with no file extension. The program will not recognize any other file name as an EMME/2 data bank file. EMME/2 data bank files store zonal data as a vector matrix, referred to as either an origin-based matrix (MO#) or a destination-based matrix (MD#) where # is the reference matrix number. Bank files store scalar data (or constants) as a scalar matrix, referenced as MS#. To reference zonal data from an input Emme2 data bank file in the script, use the standard zi.#.name convention, where name is the EMME/2 bank matrix name for the origin, destination, or scalar matrix. See Example of FILEI statements on page 494 for an example of ZDATI usage when accessing an EMME/2 data bank file.

Keyword ZDATI (continued) Subkeyword Description In general, string valued arrays are not supported at this time. ZDATI is the one exception to this rule with some limitations. ZI fields that have string values are valid but only up to 7 characters in length. AVE AVEX0 CNT DEFAULT |SV| |SV| |SV| |R| Average of all records. Average of all records, where the value from the file records is not 0. Count of the records that contain the variable. Value with which to initialize the array for the named variable. Then, if there are no records for a zone, or the field is blank on a record, this value will be used. The following keywords indicate a process to use in obtaining the value for the variables that are listed following the keyword when there is more than one record per zone. The values for the variables will be obtained only from file records that contain the variable. A variable may appear in only one keyword list; any variables that are not in any list will be set to LAST. ZDATI ZDATI ZDATI ZDATI FIRST LAST MAX MIN |SV| |SV| |SV| |SV| Directly from the record from the FILEI with the lowest index []. Directly from the record from the FILEI with the highest index []. Maximum value of all the records. Minimum value from all the records.
ZDATI ZDATI ZDATI ZDATI

Keyword ZDATI Subkeyword name |S| Description Identifies a data variables that is to be extracted from each record. Only the variables named will be extracted. If the file is a dbf, the value for each name is the name from the DBF dictionary. In most DBF cases, name=name would be the standard, but it is not necessary to keep the same names. For text files, the value assigned to name is either a field number (delimited format), or the columns (fixed format) where the variable is located on the record. All names must be specified with the same format; the first name value (including Z) establishes the format. If the first value is a number, fixed format is assumed; otherwise, delimited format is assumed. If delimited format is specified, each name value MUST end in a number. It doesnt matter what string precedes the number (the value need not be prefixed with a string). Example: Z=#1,POP=#2, AREA=3, SALES=xxx4. These are all be valid, because Z specified triggered delimited format. Z=15,POP=#2 would be invalid because Z specifies fixed format. Used to cause selective reading of zonal data records from ASCII files. The program will compare a field from each record with the string specified in SELECT[1], and if the comparison fails, the record is bypassed. This selection is not used if SELECT is not specified. SELECT[2] specifies the input record field whose value is to be compared with the value of SELECT[1]. If SELECT[2] is a number, it designates the beginning column of the comparison field on the input record, and SELECT[3] can be optionally specified to designate the ending column. SELECT[2] and [3] must both be numeric and should be separated by a dash. Alternatively, if`SELECT[2] is not numeric, but ends with a number (first example), it is assumed that the value indicates a relative field number on the data record. That field is the comparison string. SELECT[3] is ignored if SELECT[2] is a free field definition. SELECT=abc,6-8 select only if columns 6-8=abc SELECT=1,#2 select only if a 1 in field no. 2 ZDATI ZDATI SUM Z |SV| |S| Sum of all the records. Identifies where the zone number identifier is found on each data record; Z is required only for ASCII files. 'Z=' is a special case for 'name='.
ZDATI
SELECT
|S3|
Caveat: The program establishes a buffer to read file records into. It has to know how long a buffer is required. With DBFs and fixed format records, the required length is known, but with delimited format, the required length can not be estimated exactly. For delimited files, the record length is estimated by multiplying the highest field number by 10. If the estimated length is inadequate, a dummy variable with a high field number can be specified to generate a larger record length.
More on DBI
DBI files are not automatically processed. You must write scripts to read the records. Several functions are available to read the records. Use these functions in a COMP statement with the form: N=DBIfunc(DBI#,...). DBI# must always be the first argument. All the functions return a value to indicate the success of the operation. A return value of 0 indicates a successful operation; any other value indicates the read was not 100% successful. You must check the return code. The functions are: DBIReadNext(#,R) where R indicates the record to read, specified relative to the current record. A negative R means prior to the current record, and a positive R means after the current record. Write sequential reads as DBIReadNext(#,1), though DBIReadNext(#) is also allowed. A return code of 1 indicates any of the following errors: bad #, R<1, or R>DBI.#.NUMRECORDS. DBIReadRecord(#,R) where R indicates the record to read. R must be 1 DBI.#.NUMRECORDS, or the return code will be 1. DBISeek(#, R,...) where R is a value to search for in the field specified as SORT[1]. In order to use this function, there must be at least as many SORT values as there are R arguments. There may be fewer R values than there are SORT fields, but not more. This function searches for the record that matches all the specified R values. The return values are: 0 A match was found. 1 An error in setup occurred.
2 A match was not found, and DBI.#.RECNO is set to the record that is above the R selections. 3 The R values are greater than the last record and DBI.RECNO is set to the last record. In all cases, the DI.#.field values are extracted from the record indicated by DBI.#.RECNO, and the record pointer points to that record. See Example 5 on page 538 and Example 6 on page 539 for examples of DBI processing.
NOTE: You can create and populate arrays with just a FILEI DBI
statement; you do not need DBIRead functions.

More on MATI PATTERN Example for MATI[1]
PATTERN Data record fields I M [J] Values IJ:V 1 15 21 22 23 24 I=1 MI.1.1[15-18] 21,22,23,24 IMJ:V 1 6 18 100 101 105 I=1 MI.1.6[18-20] 100,101,105 I:JMV 5 12 1 8 14 2 90 I=5 MI.1.1[12] 8 I=5 MI.1.2[14] 90 IJM:V 5 12 3 8 14 2 90 I=5 MI.1.3[12] 8 I=5 MI.1.4[12] 14 I=5 MI.1.5[12] 2 I=5 MI.1.6[12] 90
The above PATTERNS do not provide for the situation where the record contains I, J, then multiple values to represent matrix 1, 2, 3 In this case, the PATTERN IJM:V, with the FIELD value of M set to zero, can be used to describe the input data. The matrix number is implied and always starts with 1 on each record. The following example illustrates the specification of PATTERNS and FIELDS for input data with implied matrix number:
Example (implied matrix number)
(input data record)

1 15 21 22 23 24 (Cube Voyager script)
MATI[1]=input.txt, PATTERN=IJM:V, FIELDS=1-2,3-4,0,5-7-4 ; fixed format or MATI[1]=input.txt, PATTERN=IJM:V, FIELDS=#1,2,0,3-6 ; variable format or MATI[1]=input.dbf, pattern=IJM:V, FIELDS=I,J,0,V1,V2,V3,V4; DBF format ; The input dbf in this example would have the named ; fields I,J,V1,V2,V3,V4 (results) I=1, J=15, MI.1.1=21, MI.1.2=22, MI.1.3=23, MI.1.4=24
The above PATTERNs also do not provide for the situation where the record contains I, then multiple values to represent J values 1, 2, 3... for a single matrix (implied matrix number M=1). In this case, the PATTERN IJ:V, with the FIELDS value of J set to zero, can be used to describe the input data. The J value is implied and always starts with 1 on each record. The following example illustrates the specification of PATTERN and FIELDS for input data with implied J number:
Example (implied j index number)
(input data record)

1 2 3 4 37.3912 167.1612 13.0612 31.6512 54.5413 269.2513 22.1213 54.2813 6.8414 35.5314 4.8514 12.2914 14.5015 75.1215 10.6815 31.3815
This example data represents a 4 zone matrix with the I values in column and the cell values for the implied J zones in columns 2 through 5. The script example below will build a binary matrix using the implied J values.
RUN PGM=MATRIX FILEI MATI=temp1.DAT FILEO MATO=temp1.mat PAR ZONES=4 MW[1]=mi.1.1 ENDRUN PATTERN=IJ:V MO=1 FIELDS=#1,0,2-5
More on RECI
Example RECI statements:

FILEI RECI=myfile.dbf, SORT=key2, -key1, +key6 FILEI RECI=myfile.mdb\mytable, SORT=key2, -key1, +key6 FILEI RECI=myfile.txt, nvar1=1-3, nvar2=5-8, cvar3(c)=1010, SORT=nvar2, cvar3 FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(C)=3, DELIMITER[2]='//' FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(C)=3, DELIMITER[2]='""'' ' FILEI RECI=myfree.txt, nvar1=1, cvar2(C)=2, cvar3(c)=3, DELIMITER=' ,;t' , '//() ' SORT=-nvar1,+cvar3
Example of usage: to sum all the housing units in a record (even if the exact names are not known, but we do know that all units fields are named xxUNITS):
TotUnits=0 Loop k=1,RECI.NUMFIELDS If (RECI.TYPE[K] = 'N' && substr(RECI.NAME[k],3,5) = 'UNITS') TotUnits = TotUnits + RECI.NFIELD[K] EndLoop
Example: In a record processing run of matrix

VAR1TOTAL=VAR1TOTAL+VAR1 IF (I=0) VAR1AVG=VAR1TOTAL/RECI.NUMRECORDS PRINT LIST=RECI.NUMRECORDS,VAR1TOTAL,VAR1AVG ENDIF
would sum the values of the variable VAR1 and once all records have been read (I=1) compute the average value of VAR1 and print to the report file the number of records, the total of VAR1 and the average of VAR1 Example:
RUN PGM=MATRIX FILEI RECI=network_link.dbf PARAMETERS MAXSTRING=100 if (RI.A>25 & RI.B>25)
print, list=ri.A,',',ri.B,',',ri.ROAD_TYPE,',', ri.IMPORTANCE,',',ri.ROAD_NAME,',', ri.CLASS,',',ri.SPEED,',', ri.PICTUREFIL file=tmp1.csv endif if (I=0) print list='Number of link records=', RECI.NUMRECORDS file=tmp2.dat endif ENDRUN
Example:
copy file = junk.txt 11 22 33 44 55 66 77 88 99 aa bb cc dd 56 78 90 12 aa bb cc dd 56 78 90 12 endcopy RUN PGM=MATRIX ;get 1st 5 data fields as numeric fields and also as character fields FILEI RECI = junk.txt,Fields=1(c5),1(n5) FILEO RECO[1]=junkout.dbf FIELDS=reci.allfields FILEO PRINTO[1]=junkprn.prn write reco=1 print printo=1 form=5lr,list='\nRecno=',reci.recno,' NumFields=',reci.numfields, ' highest field=',reci.fields,' lng=',reci.lng print printo=1 form=5lr,list=reci,'\ncfield[1-5] =', reci.cfield[1],'..',reci.cfield[2],'..',reci.cfield[3],'..', reci.cfield[4],'..',reci.cfield[5],'..\nnfield[6-9] =', reci.nfield[6],'..',reci.nfield[7],'..',reci.nfield[8],'..', reci.nfield[9],'..',reci.nfield[10],'..\nri.field1..5 =', ri.field1,'..',ri.field2,'..',ri.field3,'..', ri.field4,'..',ri.field5,'..\nri.field6..10=', ri.field6,'..',ri.field7,'..',ri.field8,'..', ri.field9,'..',ri.field10,'..' endrun Results of the PRINTO file from the above example:
Recno=1 NumFields=10 highest field=5 lng=50 11 22 33 44 55 66 77 88 99 aa bb cc dd 56 78 90 12 cfield[1-5] =11..22..33..44..55.. nfield[6-9] =11..22..33..44..55.. ri.field1..5 =11..22..33..44..55.. ri.field6..10=11..22..33..44..55.. Recno=2 NumFields=10 highest field=5 lng=23 aa bb cc dd 56 78 90 12 cfield[1-5] =aa..bb..cc..dd..56.. nfield[6-9] =0..0..0..0..56.. ri.field1..5 =aa..bb..cc..dd..56.. ri.field6..10=0..0..0..0..56..
Example of FILEI statements
These statements show various examples of FILEI usage:

FILEI MATI=test11.dat,test12.dat ; MINUTP binary matrix files MATI[4]=tppltrips.mat ; TPP or MINUT matrix file MATI[5]=external.txt, PATTERN=IJ:V, FIELDS=1-4,6-8,11-10-20 MATI[6]=external.var, PATTERN=IJM:V FIELDS=#1-30 MATI[7]=external.dbf, PATTERN=I:JMV FIELDS=ORG,DEST,MAT,TRIPS ZDATI[1]=housing.txt, Z=#1,DU1=#2,DUPLEX=3,MULTI_FAMILY=4, CONDO=5,RETIREMENT=6 SELECT=abc-1-3 FIRST=DU1, LAST=DUPLEX ZDATI[4]=pop.txt,Z=1-5,poptotal=6-15,popmale=16-25,popfemale=26-35, popyouth=36-45,pop19-65=46-55,popsr=56-65
These statements show an example of simple record processing:

copy file=reci_in.txt ; generate input file A 1 2 3 4 5 6 7 8 9 10 B 1 2 3 4 5 6 7 8 9 10 endcopy run pgm=matrix reci=reci_in.txt, FIELDS=1-3 ; switch to record processing mode ; each data record is stored in a string variable reci s2=substr(reci,11,12) s3='Z' if (substr(reci,1,1)=='A') s3='B' ; I is the end-of-file indicator print list=i(3.1), ' ', reci(10), s2, '.', s3, file=out_reci.txt, print=y ; will result in ; 1.0 A 1 2 3 4 5 6 7 8 9 10.B ; 0.0 B 1 2 3 4 5 6 7 8 9 10.Z
endrun
These statements show an example of getting I-J values from a delimited file:
RUN PGM=MATRIX RECI = myfile, org=1, dest=2 MATI[1] = mymat; contains time and distance matrices in 1 and 2 If (RI.ORG > 0 && RI.DEST>0) Time = matval(1,1,RI.ORG,RI.DEST,0) Dist = matval(1,2,RI.ORG,RI.DEST,0) Else Time=0, dist=0 Endif print file=outfile, list=reci, time(6.2LR), dist(8.2LR) ; duplicate RECI and append time and dist in delimited format ENDRUN
These statements show an example of getting matrices from an EMME/2 data bank file:
RUN PGM=MATRIX FILEI MATI[1]="emme2ban" FILEO MATO[1]="M2_to_Voy.mat" mo=1-8 DEC=8*9 ; get matrices mf104 to mf111 from emme2ban ; and put into work matrices 1 to 8 MW[1]=MI.1.104 MW[2]=MI.1.105 MW[3]=MI.1.106 MW[4]=MI.1.107 MW[5]=MI.1.108 MW[6]=MI.1.109 MW[7]=MI.1.110 MW[8]=MI.1.111 ENDRUN
These statements show an example of getting zonal vector and scalar matrices from an EMME/2 data bank file:
RUN PGM=MATRIX FILEI ZDATI[1]="emme2ban" FILEO RECO[1]="emmeVector2Voy.dbf" FIELDS=ms10(5.2),mo20(6.3),mo21(6.3),mo23(6.3), mo22(6.3),mo25(6.3),md22(6.3),md23(6),md25(6.3),md80(6), md81(6),md82(6) report zdat=t
zones=900 ro.ms10=zi.1.ms10 ro.mo20=zi.1.mo20 ro.mo21=zi.1.mo21 ro.mo23=zi.1.mo23 ro.mo22=zi.1.mo22 ro.mo25=zi.1.mo25 ro.md22=zi.1.md22 ro.md23=zi.1.md23 ro.md25=zi.1.md25 ro.md80=zi.1.md80 ro.md81=zi.1.md81 ro.md81=zi.1.md82 write reco=1 ENDRUN
FILEO
Programs: Distribution, Fratar, Matrix
Outputs data files. MATO (FORMAT MO NAME DEC PATTERN DELIMITER FIELDS MAXFIELDS) PRINTO (APPEND) RECO (FIELDS EXCLUDERECI CFORM FORM REPORT) Use FILEO to specify the type and number of output files for the program to produce. Cube Voyager writes matrix type output files at the end of each I zone.
PRINT statements write formatted print files to the PRINTO file. WRITE statements write RECO files to the referenced DBF file or can point to elements in a multidatabase (MDB) file by designating the file name followed by a backslash and the element name.
FILEO keywords
Keyword MATO Subkeyword |KFV20| Description Name of an output matrix file. May have an index [x] appended. If you do not specify an index, the program assumes the index is 1. Indices need not be monotonic or sequential. The program can write output matrices in various formats, which you can use with other software. MATO may reference an existing EMME/2 data bank file in order to store matrix data into the existing data bank. EMME/2 data bank files must be named emme2ban. The program will overwrite an EMME/2 data bank file in the format specified by FORMAT if the name is not emme2ban. The data bank file must exist already. If it does not exist, the program will not create the data bank file.

Keyword MATO Subkeyword DEC |SV*| Description Specifies numeric format of values in the output matrix. Specify a separate DEC for each MO. Valid values vary by file format: Cube Voyager files Valid values include: 0 through 9 Writes output matrix cells in fixedpoint format, preserving the indicated number of digits following the decimal. This is the traditional format for transportation planning matrices. NOTE: Cube Voyager stores fixed-point format as a decimal-coded integer. If the cell value exceeds the maximum integer value (2,147,483,647), then Cube Voyager reduces the number of digits stored after the decimal. For example, with DEC=5, Cube Voyager stores 1,258,756.33715 as the integer 1,258,756,337, which translates to 1,258,756.337. S Writes output matrix cells in single-precision floating-point format (4 bytes). This format provides seven to eight significant digits. Additional digits may change from their original value when a program reads them. Certain matrices might require more precision. D Writes output matrix cells in double-precision floating-point format (8 bytes). This format provides 15 to 16 significant digits. If you do not specify DEC, the default value is 2. Cube Voyager processes all matrices in double-precision floating-point format to accommodate a wider range of values and to maintain accuracy and precision. However, writing double-precision numbers to the matrix files might produce very large files. In most cases, a few decimal places for each cell value are adequate. For example, for a cell computed as 10/3, the result is 3.33333333... to sixteen digits. If stored as fixed-point with DEC=0, the result is 3, and requires one byte to store. However, this result might not be precise enough for the subsequent uses. If stored as fixed-point with DEC=2, the result is 3.33, and requires two bytes to store. If stored as single precision with DEC=S, the result is accurate to about seven digits, and requires four bytes to store. If stored as double precision with DEC=D, the result requires eight bytes to store.

Keyword MATO Subkeyword DEC (continued) Description MINUTP or Tranplan files Do not set DEC. The program ignores the DEC setting and automatically writes 4-byte values, usually integer numbers. You must set the included work matrices to the desired external format before the program writes the matrices. Storing numbers larger than the maximum integer value (2,147,483,647) will result in erroneous values. NOTE: Normally, you round matrices that represent levelof-service (time, distance, cost, and so on), and bucket round matrices that represent trips to ensure row totals.
COMP MW[1]=INT(MW[1]*100+.5) ; LOS rounding COMP MW[2]=MW[2]*100, Total=ROWFIX(2) ; bucket rounding
Optionally, set DEC=S to write a single-precision matrix. However, you cannot use such a matrix as input to Cube Voyager. TRIPS files Set DEC to the number of digits after the decimal point (0 to 9). The program stores numbers as integers with implied decimal. If you set DEC to S or D, the program treats as DEC=0. If a numbers integer value with implied decimal exceeds the maximum integer value (2,147,483,647), the program substitutes the maximum integer value for that number. Text files Set DEC to the number of decimal places to format in text records. If you do not code DEC, the program uses the default value of 2. If you specify DELIMITER, the program writes variable-length values and truncates trailing zeros, otherwise the program writes fixed field lengths, based on the values of FIELDS. DBF files Set DEC as for Cub Voyager files. However, the program uses the DEC[1] value for all the matrix data fields unless M immediately precedes the colon in PATTERN (for example, PATTERN=IJM:V ). If you set PATTERN such that M varies in a records matrix data values, the program uses DEC[#] appropriately.

Keyword MATO Subkeyword DEC (continued) Description EMME/2 data bank files Do not set DEC. The program stores values in singleprecision floating-point format in the data bank file. MATO DELIMITER |S| For text files only (FORMAT=TXT ). Character that separates data values. When you code this subkeyword, the program writes data values in variable length and separates values with this character. If you do not specify DELIMITER, the program writes fixed field lengths, based on the values of FIELDS. Usually, you delimit data with a comma or space. To use a comma or space, enclose with quotes, ' '. Field width for data values when DELIMITER is not specified. The number of values specified with FIELDS must match the number of letters in PATTERN (the base portion precedes the colon, and the repeating portion follows the colon). The first FIELDS value always sets the length for I. After exhausting the list of FIELDS values, the program reverts to the FIELDS value that corresponds to the repeating portion of PATTERN. If the FIELDS value that corresponds to a base portion of PATTERN is set to 0, the program omits the corresponding data. Examples:
PATTERN=IJ:V FIELDS=4,4,6
MATO
FIELDS
|IV4|
I will always be in 1-4 J will always be in 5-8 V will be in 9-14,15-20,21-26 ... I will always be in columns 1-4 J will be in 5-8, 17-20, 29-32 ... V will be in 9-14, 21-26, 33-38 ... M will be in 15-16, 27-29, 39-40 ... I will always be in columns 1-4 J will always be in 5-8 M will not be written to the data records V will be in 9-16,17-24,25-32 ...
PATTERN=I:JVM FIELDS=4,4,6,2
PATTERN=IJM:V FIELDS=4,4,0,8

Keyword MATO Subkeyword FORMAT |S| Description Type of file written: TPP Standard Cube Voyager/TP+ matrices MINUTP Standard MINUTP matrices TRANPLAN Standard Tranplan matrices TRIPS Standard TRIPS matrices (also used for Cube Analyst) TXT Text records of matrix values DBF DBF records for matrix values
Default value is TPP, unless you set PATTERN. With PATTERN set, the default value is TXT. Ignored if MATO is set to emme2ban. In that case, the program updates an EMME/2 data bank file.

Keyword MATO Subkeyword MAXFIELDS |I| Description Maximum number of value sets written on a single record. If not set, the program does not limit the size of a data record (there is a limit of 255 fields in a DBF record). A value set is the group of values that follow the colon in PATTERN. For example, with IJ:V, MAXFIELDS=10, the program writes at most 10 V values on a record. With IJ:VM, MAXFIELDS=10, the program would write at most 10 sets of VM values on a record, for a maximum of 20 fields. Use care with DBF files. If MAXFIELDS is less than the number of matrices specified with MO, the program will split a logical data record into multiple records. The results might be confusing. Citilabs recommends that you always set MAXFIELDS. The program tests MAXFIELDS before writing a value set. If the repeating portion of PATTERN (the repeating portion follows the colon) is only V and the program encounters a string of zero values, the program will start a new record if starting a new record requires less space. The new record will begin with the next J containing a value. If the repeating portion of PATTERN is more than V (contains a J or M, or both), and V is zero, the program does not write the value set. Example
FILEO MATO=TPPTEST.MAT, MO=1-5, NAME=HBWORK,HBOTHER,NHB,IXI,XX MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7, NAME[3]=PURP_5 MATO[4]=TEST4.TXT, PATTERN=IJ:MV, MO=1-8, MAXFIELDS=1000, DELIMITER=',' MATO[15]=TEST15.TXT, PATTERN=I:JMV, MO=3-7,42, FIELDS=4,4,2,6, DEC=6*0, DEC[3]=2

Keyword MATO Subkeyword MO |IVP| Description List of working matrices that the program writes in the output file. You may index MO. Note that missing MO index values are acceptable when writing binary files but not when writing text files. The highest implicit or explicit index determines the number of matrices included in the output file. You may write the same working matrix more than one time. For example, with MO=1-5,11-15, MO[20]=1, MO[6]=31 the program will write 20. Nine of the matrices (11-19) will be empty because no data was entered for them. The program numbers output matrices monotonically beginning with 1. When writing output matrices to an EMME/2 data bank file, the program only writes the specified matrices. For other formats, the program starts output matrices at 1 and writes through the highest MO index. For example, with MO=1,8, MO[200]=7, the program will write 200 matrices, most set to 0. If writing to an EMME/2 data bank output file, the program will write MF1, MF2, and MF200. MATO NAME |SV| For TP+, Cube Voyager, Tranplan, and TRIPS output files, specifies the names for the matrices. Each output matrix (specified by MO) does not require a name, but including a name helps document the file. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). Cube Voyager programs reading the file can reference the matrices by name and/or number. For MINUTP and text output files, the program ignores NAME. For DBF output files, specifies user names for the record variables. NAME[1..n] will refer to the beginning n record fields, which will align with PATTERN. If there are three characters prior to the colon in PATTERN, NAMES[1-3] refers to those fields. NAME[n+1] refers to the first actual data field that corresponds with the first character following the : in PATTERN. For EMME/2 data bank output files, specifies names of output matrices, which you can use for internal documentation. For such files, the program stores the first four characters of NAME into the bank short name and the entire name into the bank long description. See Example: FILEO MATO for EMME/2 file on page 507 for an example of writing matrices to an EMME/2 data bank file, specifying matrix numbers and names.

Keyword MATO Subkeyword PATTERN |S| Description Sequence of characters that indicates the order the program writes values to the output records. Valid values of PATTERN are listed and described under FILEI MATI PATTERN on page 480. The program begins a new record each time either of the first two characters of PATTERN change values (exception: IJ:V begins new record for each I change). Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT PRINTO=#. See APPEND under PRINT on page 62. File name for the RECO specified. Each RECO must have an index [x] appended to it. If there is no index, the index is assumed to be 1. The indices need not be monotonic or sequential. Data written to this file is defined with the FIELDS keyword below and directed to the appropriate file using the RECO keyword on the write statement. See WRITE on page 532. Currently, DBF, MDB and EMME/2 data bank files are the only file formats supported for this record file. If specifying an EMME/2 data bank file, the file name must be
emme2ban. The program will write any other file name to binary
PRINTO PRINTO RECO APPEND
|KF| |?| |KF20|
format and not in bank-file format. The bank file must exist already. If it does not exist, the program will not create the bank file. You can use RECO to write scalar or vector matrices into an EMME/2 data bank file. RECO CFORM |I| Length of field for all character variables that follow it on the statement, and do not have a specific format associated with it. A later occurrence of CFORM will reset the value for character variables following it. The allowed range is 1-255; the default is 15. Used to exclude selected fields when using the RECI.ALLFIELDS include macro described under FIELDS above.
RECO
EXCLUDERECI
|S|

Keyword RECO Subkeyword FIELDS |S| Description Defines the variable names to be written to the output RECO file. These variables are referenced as RO.name variables in the script. If a RECO variable name matches a variable in the RECI record, the RO.name variable will take on the same value as the matching RI.name variable each time a new RECI record is read. All RO. variables (with or without matching RI. variables) can be modified in the script, the current variable values are written to these fields in the RECO DBF file when the WRITE statement is executed. For RECO fields that have no matching RECI fields, the field values are NOT initialized when a new RECI record is read. For RECO fields that are not assigned a value in the script or do not have a matching RI. variable, they will be left empty in the output record. The include macro RECI.ALLFIELDS can be specified on the FIELDS list to indicate that all of the data fields on the input RECI file are to be included on this RECO output file. The RECI fields will be inserted on the RECO file at the location where this macro is found. Care should be taken to ensure that the other names in the FIELDS list do not conflict with the names on the RECI file. For backward compatibility to version 3.2, the RO. prefix of the RECO variable name can be omitted when referencing the variable in the script if the variable has no matching RECI variable and it is not referenced with the RO. prefix anywhere in the script (a 3.2 script would never have an RO. Prefix in the first place). However, it is strongly recommended that the RO. prefix be used at all times to avoid confusion. If specifying an EMME/2 data bank file with RECO, the format is: RECO=emme2ban FIELDS=Mx#, where x=S, O, or D, and # is a valid number for the data bank. EMME/2 references scalar matrices as MS#, origin matrices as MO#, and destination matrices as MD#. Cube Voyager usually refers to these as constants and zonal arrays. When the output file is an EMME/2 data bank, the program ignores any FIELDS not named with this format (Mx#). If you specify MO or MD, you must also specify a Z=variable to indicate for which zone to store the data. If using RECO in conjunction with matrix processing, a logical variable for Z would be I (Z=I) if there is one RECO per zone. See the Example: FILEO RECO for EMME/2 file on page 508 for an example of writing record data to an EMME/2 data bank file, specifying fields and field names.

Keyword RECO Subkeyword FORM |R| Description Format specification (w.d) for all numeric variables that follow it on the statement, and do not have a specific format associated with it. A later occurrence of FORM will reset the value for numeric variables following it. The allowed range is 1-31.5; the default is 10.2. Optional. Used in conjunction with the FIELDS subkeyword. For output to EMME/2 data bank files, specifies name in the data bank for scalar and vector matrices. Example:
reco[1] =..\emme2\emme2ban Z=I, fields=MS1 MO1 MD1 name=ms1 mo1 'md1 term time'
RECO
NAME
|S|
For this example, the script must set the variables .MS1, RO.MD1, and RO.MD2. Upon encountering each WRITE RECO=1 statement in the script, the program would update the data bank, changing the names as defined. RECO REPORT |?| Can be specified to have the program print a listing of the fields (name, mode, length, decimals) as they will appear in the DBF. Default value is F. Optional. Used in conjunction with the FIELDS subkeyword. Required when writing MO or MD matrices. For output to EMME/2 data bank files, specifies zone for which the program stores the data.
RECO
|S|
Example: FILEO
These statements demonstrate FILEO.

RUN PGM=MATRIX FILEI RECI = " LINK_DATA.DBF",SORT = -VULNERABIL FILEO RECO[1] = "PRESCEENED_LINKS.DBF", FIELDS=A,B,rank_bas NUMLINKS=RECI.NUMRECORDS ; number of records (links) in the input file LOG PREFIX=CNT VAR=NUMLINKS ; writes the number of links to CNT.NUMLINKS ; in the *.var file ; PrescreenType and PRESCREEN value set in SM with KEYS IF ({PrescreenType}=1) ; screen based on a fixed number of links ; (i.e., top N based on Vulnerability) PRESCREEN={PRESCREEN} ELSE ; screen based on a percentage of number of links ; in the input network (i.e., top N% of links based ; on Vulnerability) PRESCREEN=ROUND(NUMLINKS*{PRESCREEN}/100)
ENDIF LOG PREFIX=CNT VAR=PRESCREEN RO.RANK_BAS=RO.rank_bas+1 Anode=RI.A Bnode=RI.B If (RO.rank_bas<=PRESCREEN) If (Anode <={Zones} | Bnode <= {Zones}) ; prevents any centroid links ; from being included in set ; of links to be analyzed RO.rank_bas=RO.rank_bas-1 Else WRITE RECO=1 EndIf EndIf ENDRUN
Example: FILEO MATO for EMME/2 file
These statements demonstrate FILEO MATO to an EMME/2 data bank file.

RUN PGM=MATRIX FILEI MATI[1] = "Purpose_Trips.MAT" FILEI MATI[2] = "HWY_SKIMS.MAT" FILEI MATI[3] = "PT_SKIMS.MAT" FILEO MATO[1] = " EMME2BAN", MO=1-4,9-17,MO[17]=101-106,201-220,MO[171]=221-240,MO[191]=5-7,MO[206]=8, NAME=mf01,mf02,mf03,mf04,mf05,mf06,mf07,mf08,mf09,mf10,mf11,mf12,mf13, NAME=mf17,mf18,mf18,mf20,mf21,mf22,mf23,mf24,mf25,mf26,mf27,mf28,mf29, mf30,mf31,mf32,mf33,mf34,mf35,mf36,mf37,mf38,mf39,mf40,mf41,mf42, NAME[191]=mf191,mf192,mf193,NAME[206]=mf206 ; get mf01-mf04,mf191-mf193,mf206,mf05-mf13 FILLMW MW[1]=mi.1.1(9) MW[10]=mi.1.11,15,19,21,22,23,25,27 ; get mf17-mf22 FILLMW MW[101]=mi.2.4(6) ;get mf23-mf42, mf171-mf190 FILLMW MW[201]=mi.3.1(40) ENDRUN
Example: FILEO RECO for EMME/2 file
These statements demonstrate FILEO RECO to an EMME/2 data bank file.

RUN PGM=MATRIX FILEO RECO[1] = " EMME2BAN", Z=I FIELDS=ms02,ms10,mo20,mo21,mo22,mo23,mo25,md22,md23, md25,md80,md81,md82 FILEI ZDATI[1] = "VECTORDATA.DBF" FILEI MATI[1] = "HWY_SKIMS.MAT" ;get mo20, mo21, mo23 FILLMW MW[1]=mi.1.1(3) JLOOP IF (I=J) ro.z=I ro.mo20=MW[1][I] ro.mo21=MW[2][I] ro.mo23=MW[3][I] ro.mo22=zi.1.MO22 ro.md22=zi.1.MD22 ro.mo25=zi.1.MO25 ro.md25=zi.1.MD25 ro.md23=zi.1.MD23 ro.md80=zi.1.MD80 ro.md81=zi.1.MD81 ro.md82=zi.1.MD82 ro.ms02=8 ;scalar ro.ms10=34.7 ;scalar WRITE RECO=1 ENDIF ENDJLOOP ENDRUN
FILET
Sets temporary file paths. PATH FILET is used to specify where various temporary files are to be written.
FILET keyword
Keyword PATH |KS| Description Specifies the path(s) to the disk area where any temporary files are to be written. When transposing is required, the transposed matrices are written to a temporary file and then recalled during stack processing. Up to two files are required for this process. The first file is the actual transposed data, and the second file is an index to the data file. The index file may not be necessary, and if it is, it will be relatively small. It may speed retrieval somewhat if the two files are on different physical drives. If there is a ram disk installed, then the index file might fit on it. The index file size will be zones * chunks * transposes * 4 bytes. Chunks depends upon the amount of RAM that is available for the transposing processing; it could be none. Assume a 1000 zone system, 20 matrices to be transposed, and 2 Mb of RAM available. The actual RAM requirement would be 1000 * 1000 * 20 * 4, or 80 Mb. The number of chunks would be 40 (80 Mb / 2 Mb). The index file would require 800,000 bytes of RAM. The amount required for the data would be something less than 80 Mb, depending upon how well it compresses. In most cases, the compressed data would require about 30 Mb. The values for PATH are entered as standard operating system paths. If PATH[1] is specified, and PATH[2] is not, or vice-versa, the non-specified path is set equal to the specified one. If neither is specified, they both will default to the path in the environment variable named TMP, or TEMP. The logic for determining the appropriate path, and opening the files is: If the PATH=' ', use current directory. If the PATH is specified, use the PATH. If not specified, and TMP is specified in the Operating System environment, use the TMP.setting. (Same logic for TEMP.) If the open fails, Fatal.
Example
PATH=' ' ; use current directory for both PATH=..\,R: ; up a directory for data, drive R: for index PATH=c:\ d ; root of c: for data, current directory on d: for index
FILLMW
Fill work matrices MW This statement is used to speed up the process of filling matrices with values from other matrices. Because of its structure, matrices can be very easily moved from input matrices to work matrices or from work matrices to other work matrices. Multiple matrices can be easily filled on one specification. The beginning MW target is the keyword and the values are the matrices that are to be moved into the target matrices. After the first value, the following values may be unqualified (they do not have to have MI.#. prefixed to their names/numbers). This is also true for MW sources. Everything that can be done on a FILLMW statement can be accomplished by COMP statements, but FILLMW sets up very fast moves in contrast to internal computational solutions performed by COMP statements.
FILLMW keyword
Keyword MW |s| Description Specifies the matrices to be moved directly from their source to the destination work matrices named on the keyword.
Example
; The following five statements all do the same thing FILLMW MW[1]=mi.1.1(3) FILLMW MW[1]=mi.1.1,mi.1.2,mi.1.3 FILLMW MW[1]=mi.1.time,mi.1.distance,mi.1.cost FILLMW MW[1]=mi.1.1,2,3 FILLMW MW[1]=mi.1.time,distance,cost
; The next two statements illustrate the simplicity of FILLMW vs. COMP FILLMW MW[11]=mw[1],2,3,9,6 COMP MW[11]=mw[1], mw[12]=mw[2], mw[13]=mw[3], mw[14]=mw[9], mw[15]=mw[6] ; An example of multiple keywords FILLMW MW[1]=mi.1.1,2,3, MW[4]=mi.2.2,3,4 FILLMW MW[101]=mi.1.1(5), MW[1](3) ;will fill MW[101-108] with MI.1.1-5,MW[1,2,3]
FREQUENCY
Program: Distribution, Fratar, Matrix
Stratifies one matrixs values based upon the values of another. BASEMW RANGE REPORT SAVE TITLE VALUEMW
Use FREQUENCY to obtain a frequency of occurrence of the values of a work matrix. A typical use is for a trip length distribution, where the number of trips in a matrix is stratified according to the times from a time or distance matrix. The final results are reported at the end of all zone processing.
FREQUENCY keywords
Keyword BASEMW |I| Description Work matrix number ( MW[ ] ) whose values will be used for the stratification (the time matrix for a trip length distribution).
FREQUENCY keywords (continued)

Keyword RANGE |RP| Description Set of two, or three, numbers that establishes the valid values for stratification. The numbers are separated by a dash. The first number (RANGE[1]) is the lowest value for which there is to be a stratification. The second number (RANGE[2]) is the highest value for stratification. The third, optional, number (RANGE[3]) is an increment for stratification. If there is no increment, the default will be 1. During accumulation, if the value from BASEMW is less than RANGE[1], or higher than RANGE[2], the value from VALUEMW is accumulated into an out-of-range bucket. Iterations for which the report will be printed. If this keyword is not specified, or if any of the values exceed the last iteration, the report will be printed for the last iteration. REPORT is used primarily only when the Matrix program is invoked as a process that runs in a multiple iteration mode (Distribution program). Not yet in use. Title for identifying the final report at the end of the application. Work matrix number ( MW[ ] ) whose values will be accumulated according to the values of BASEMW (the trip matrix for a trip length distribution).
REPORT
IP|
SAVE TITLE VALUEMW
|?| |S| |I|
Example
FREQUENCY BASEMW=1,VALUEMW=2,RANGE=1-100, TITLE='Work Trips vs. Minutes' FREQUENCY BASEMW=1,VALUEMW=2,RANGE=0-100-0.5, REPORT=99
GOTO
Program: Distribution, Fratar, Generation, Matrix
Use GOTO to jump to statement named :label. When GOTO is processed, flow immediately branches to the statement named label. Label can be within IF and LOOP blocks; but care should be taken if this is to be done.
label is a character string that must have a matching LABEL statement. The leading colon : is removed from label when determining the qualified name of the statement to branch to.
NOTE: The placement of a :label inside a JLOOP is not allowed. This prevents using GOTO from jumping into a JLOOP. A GOTO may be
used inside a JLOOP to jump to a :label that is outside the JLOOP but not to one that is inside the JLOOP.
Example
GOTO buildhwy GOTO :buildhwy
A statement that begins with : is a label statement, that has meaning with only GOTO statements. A label statement can be within IF and LOOP blocks; care should be taken if this is done. The leading : is ignored.
Example
GOTO buildhwy . . :buildhwy IF (expression) GOTO :buildhwy
; It is permissible to go backwards.

Program: Distribution, Fratar, Generation, Matrix
IF (expression) ELSEIF (expression) ELSE (expression) ENDIF IF/ENDIF blocks are used to determine if certain operations are to be performed. IF blocks may be nested, but they may not overlap LOOP, JLOOP, or other IF blocks. If a variable in the expression is MI.n.name, ZI.n.name, or MW[], the same rules for indexing in a COMP statement are applied. MI.n.name or MW[] should realistically only be used within a JLOOP. Lengthy IF expression solutions could be time consuming; it is suggested that they be used judiciously. Although IF expressions can be quite powerful for
zonal selection, sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples in this section). The following control statements may be appended to a single IF statement:
BREAK CONTINUE COMP EXIT GOTO PRINT Example
IF (time_to_bcd < 20) simple statement ;single IF with process IF (expression) EXIT IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) ) . ELSEIF (loop_cntr > 10) . ELSEIF (loop_cntr > 5 && diff.time < 32) . ELSE . ENDIF ; The above IF example is rather esoteric, ; and probably can not be aided by a filter. ; The J selection could have been filtered, but that might have caused ; conflicts with the use of J in other parts of the expression. ; The following illustrates a more efficient process for using IF for ; lengthy zonal selections within JLOOPs ; ***** Inefficient ***** JLOOP IF (I=i_ranges... && J=j_ranges...) statement ENDJLOOP ; ***** More efficient ***** IF (I=i_ranges...) JLOOP INCLUDE=j_ranges... statement ENDJLOOP ENDIF
JLOOP ... ENDJLOOP

Control a J loop for processing matrices.
J INCLUDE EXCLUDE JLOOP ENDJLOOP blocks are used primarily to control computations on matrices that a single COMP MW[]= can not properly control. A JLOOP block causes the program to loop between the JLOOP statement and its ENDJLOOP varying J from Jbeg to Jend by increments of Jinc. The logic for JLOOP and ENDJLOOP processing is: at JLOOP: If J is specified, establish values for J, Jend, and Jinc. Else set J=1, Jend=Zones, Jinc=1. If (J < 1 or J > Zones or Jend <1 or Jend > Zones) fatal termination. If (INCLUDE, and J fails INCLUDE) go to ENDJLOOP. If (EXCLUDE, and J meets EXCLUDE) go to ENDJLOOP. Next statement. at ENDJLOOP: Add Jinc to J. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. If (INCLUDE, and J fails INCLUDE) go to ENDJLOOP. If (EXCLUDE, and J meets EXCLUDE) go to ENDLOOP. All statements between the JLOOP and ENDJLOOP statements are processed with the current value of J. JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP or IF blocks. COMP MW[]= statements are processed only for the current value of J. Only the following statements are valid within a JLOOP block: BREAK CALL COMP CONTINUE EXIT GOTO IF ELSEIF ELSE ENDIF
PRINT REPORT SET

NOTE: The placement of a :label inside a JLOOP is not allowed. This prevents using GOTO from jumping into a JLOOP. A GOTO may be used inside a JLOOP to jump to a :label that is outside the JLOOP but not to one that is inside the JLOOP. JLOOP and ENDJLOOP keywords
Keyword J Jbeg Jend |I| Description Sets Jbeg, Jend and Jinc. Expression to initialize J; the value may not be less than 1, nor greater than Zones. Expression that establishes the Jend for the loop; the value may not be less than 1 nor greater than Zones. If there is no Jend, Jend is set to Jbeg, and Jinc is set to 1. Expression that establishes the Jinc for the loop. If Jinc is not specified, Jinc is set to 1 or -1, depending upon the direction from Jbeg to Jend.
Jinc
If Jbeg is not specified, Jend and Jinc can not be, and the values 1,Zones,1 are used. If Jend is not specified, Jinc can not be, and the values Jbeg and 1 are used. If Jinc is not specified, it is set to 1 ( -1, if Jbeg > Jend). Because all these values can be expressions, they must be separated by commas; if an expression contains any commas, it must be enclosed within ().
Example
JLOOP J=I EXCLUDE=500-535 ;process only intra zonal values . ; but exclude externals ENDJLOOP ROWSUM1 = 0 ROWSUM3=0 JLOOP ; get rowsums for matrices ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP
LOOP ... ENDLOOP

Control a general variable loop. LVAR = Lbeg, Lend, Linc LOOP ENDLOOP blocks are used to repeat of a series of statements. LOOP initializes a variable; ENDLOOP compares the contents of the variable to another value, and branches back to the statement following the LOOP statement if the comparison fails. LOOP blocks may be nested; they may not overlap IF blocks. The process differs considerably from JLOOP. The logic is as follows: at LOOP: Initialize LVAR to Lbeg. Proceed to next statement. at ENDLOOP: If Lend not specified, jump to next statement. Compute Lend. If Linc not specified: Set Linc to 1 or -1 (if Lbeg and Lend are constants, and Lbeg > Lend) Else compute Linc. Add Linc to LVAR. Compare LVAR to Lend. If (Linc > 0 and LVAR > Lend) jump to statement after ENDLOOP If (Linc > 0 and LVAR <= Lend) jump to statement after LOOP If (Linc < 0 and LVAR < Lend) jump to statement after ENDLOOP If (Linc < 0 and LVAR >= Lend) jump to statement after LOOP
Because of the flexibility of this logic, unpredictable results and/or endless loops can occur if care is not taken. This would only happen if the Lend and/or Linc values are expressions that contain variables which could be altered during the loop. On the other hand, the flexibility provides for powerful control. The loop will be processed at least one time regardless of Lend and Linc values. Most uses will involve constants. Because LVAR values can be expressions, Lbeg, Lend, and Linc must be separated by commas (standard white space delimiting can not be interpreted properly).
LOOP and ENDLOOP keywords
Keyword LVAR Description Name of the loop control variable. LVAR is not protected during the loop; computational, program, and other LOOP statements can alter its value. LVAR must be followed by Lbeg, and optionally, Lend and Linc. Numeric expression to initialize LVAR. Numeric expression that LVAR is to be compared with when the ENDLOOP statement is processed. If it is not specified, it is assumed no comparison is to be made (rather meaningless loop). Numeric expression that is to be added to LVAR before the ENDLOOP comparison is made. If Linc is not specified, it will be set to 1 (-1 if Lbeg and Lend are both constants and Lbeg < Lend; a backwards loop).
Lbeg Lend
Linc
Example
LOOP iter=1,10 ; perform 10 iterations . ENDLOOP LOOP xyz=abc*def,ghi+jkl,mno/pqr LOOP abc=xyz,xyz+2,2 ; nested LOOP ENDLOOP ENDLOOP LOOP jj=10,3,-2.5 ; 10, 7.5, 5.0 ENDLOOP
PARAMETERS
Program: Matrix
Sets general parameters. MATVALCACHE MAXMW MAXSTRING TRAM ZONEMSG ZONES

PARAMETERS keywords
Keyword MATVALCACHE |KI| Description Number of matrix rows to cache when dealing with the MATVAL function. Default value is 50. Each matval call requires a direct access lookup on the designated MATI. Each read of a row for matval results in a matrix row being read and stored for possible later use. In general, the larger the number, the more efficient matval is. Each value requires (zones*8 + 4) bytes of RAM. If too large a value is used, the RAM for cache might come from disk, which could possibly hinder performance. The user might have to experiment to determine the best number of his application. Optional. Maximum index for work matrices (MWs). Valid values range from 1 to 999. Default value is 999. Normally, you do not specify this keyword and override default value. Establishes the maximum length for a string variables value. The default is 100, but if it is desired to compute longer strings, the value must be defined. All string variables will have this possible length.
MAXMW
|KI|
MAXSTRING
|KI|

Keyword TRAM |KI| Description Establishes the maximum amount of memory that is to be used for temporary storage when transposing matrices. The program will request the amount that it thinks will provide the most efficient processing. The most efficient amount would be (Zones * Zones * 8 * NumberTransposes), but that would probably be more than the computer has available in real memory. However, if Windows is controlling the computer, it will provide that much memory, but a portion of it might be virtual memory (temporary work space on disk). The use of virtual memory is disastrous in terms of efficiency for the transposing process. The program can not detect if the ram is real or virtual; therefore, care should be taken to not specify a value that is too large. In general, 4MB (4000000) should be adequate for most applications; 4000000 is the default, and should not normally be reset. Optional. Frequency with which the program writes zonal timing messages to the run monitor or console. Value corresponds to number of zones. For example, with a value of 1, the program writes a message for every zone. With a value of 10, the program writes a message for every 10 zones. With a value of 0, the program writes no zonal messages. Specify a larger value to reduce run times. Program writes to the run monitor when initiated through Application Manager or voyager.exe. The program writes to the console when initiated through runtpp.exe. Valid values are greater than or equal to zero. Default value is 1. ZONES |KI| Establishes the number of zones to process. If ZONES is not specified, and the program has no other way to identify the appropriate number of zones, it will be set to 100. If there are any input MATIs being processed, the default value for ZONES will be determined by the highest value from any of the MATIs.
ZONEMSG
|IK|
Example
ZONES=3000
PRINT
Format and print a line of information. CFORM CSV FORM LIST FILE (PRINT APPEND REWIND) PRINTO (REWIND PRINT) See PRINT on page 62 for details about the standard Cube Voyager statement.
Example
PRINT FORM=0 LIST=I,J,TOTAL(6.2CS) 'ABCDE'(6.3), FORM=LRCD, LIST=N,JLOOP_J ;Note this line is a continuation LIST= I(6) J(6) TOTAL1, TOTAL2, TOTAL3 FILE=PRINTFIL.001 PRINT FORM=6.0CDLR LIST=I,J,TOTAL1,TOTAL2 FILE=PRINTFIL.002
PRINTROW
Program: Distribution, Fratar, Matrix
Prints row of matrices. MW J TITLE FORM MAXPERLINE BASE1 See PRINTROW on page 69 for details about the standard Cube Voyager statement.
Example
Examples of output with various parameters follow:

pagewidth=80 mw[1]=j mw[2]=j include=1-5,31-60,90-100 exclude=35,83 printrow mw=1-2,1 form=LRD title='form=LRD' printrow mw=1-21 form=6D base1=y maxperline=10, title='form=6D base1=y, maxperline=10'
Resulting Output:
J: I=1 1: 1 2 27: 27 50: 50 73: 73 96: 96 J: I=1 1: 1 2 33: 33 57: 57 90: 90 J: I=1 1: 1 2 11: 11 21: 21 31: 31 41: 41 51: 51 61: 61 71: 71 81: 81 91: 91 J: I=1 1: 1 2 31: 31 41: 41 51: 51 81: -91: 91 PRINTROW MW[1] form=LRD Tot=5,050 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 97 98 99 100 PRINTROW MW[2] form=LRD Tot=2,390 3 4 5 - - - - - -- - - - - - - - - - -- - - - - - - - - - 31 32 34 - 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 58 59 60 -- - - - - - - - - - -- - - - - - - - - - -- - - - - - 91 92 93 94 95 96 97 98 99 100 PRINTROW MW[1] form=6D base1= Tot=5,050 3 4 5 6 7 8 9 10 12 13 14 15 16 17 18 19 20 22 23 24 25 26 27 28 29 30 32 33 34 35 36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 62 63 64 65 66 67 68 69 70 72 73 74 75 76 77 78 79 80 82 83 84 85 86 87 88 89 90 92 93 94 95 96 97 98 99 100 PRINTROW MW[2] form=6D base1= Tot=2,390 3 4 5 -- -- -- -- -32 33 34 -- 36 37 38 39 40 42 43 44 45 46 47 48 49 50 52 53 54 55 56 57 58 59 60 -- -- -- -- -- -- -- -- 90 92 93 94 95 96 97 98 99 100
RENUMBER
Programs: Fratar, Matrix
Renumbers (aggregate, split) zones for output matrices FILE ZONEO ZONES MISSINGZI MISSINGZO FILES INRAM
RENUMBER causes the program to assign new zone numbers to all values in the output matrices. This causes an extra layer of processing, because the matrices must be saved, and then retrieved and combined after all normal processing is completed.
Each input zone must be assigned a new output zone number, and a pair of percentages (ROWPCT and COLPCT ) to indicate how the outgoing matrix zonal values are to be allocated to the renumbered zones. These equivalencies are obtained from records in the designated FILE. The records may have from one to four fields to specify the renumbering. A semi-colon (;) terminates data on a record; anything following the ; is a comment. The standard fields are:
Field IPZONE OPZONE ROWPCT COLPCT Description Input zone number Output zone number Percentage of IPZONEs values to be assigned to OPZONE when renumbering the IPZONE row Percentage of IPZONEs values to be assigned to OPZONE when renumbering the IPZONE columns
If there is only one field, OPZONE is set to 0. If there are less than three fields, ROWPCT and COLPCT are set to 100. If there are three fields, COLPCT is set to ROWPCT. ROWPCT and COLPCT may not exceed 327 An alternate record format for aggregating several zones into a single district:
Description District OPZONE IPZONEs Word that begins with the letter D (for traditional DISTRICT). The word may be any length, but the first character must be D. Output zone number; it MUST be followed by =. Remaining fields are the input zones that are allocated 100% (ROWPCT and COLPCT) into OPZONE. Two fields may be separated by a dash (-) if the two are to form a range.
If the list of IPZONEs is large, and the length of the record would exceed 250 characters, the record must be broken into several records. Each record must begin with the District string, and may not terminate with a dash.
Example
D 1=1-10,20-30 45,48, 58-60 D 1=100-110 200-210 300-305 410 415 500-515 Those two formats can be mixed in the same file to allow efficient specification of zonal equivalencies. An IPZONE may appear more than one time; usually the case when a zone is to be split into several new zones. An OPZONE may appear more than one time, usually the case when aggregating zones. The sum of all ROWPCTs and COLPCTs for each IPZONE should each be 100; if not, a message is issued. Every IPZONE (1-IPzones) should be fully allocated. An IPZONE of 0 means there is intentionally no IPZONE for the OPZONE. An OPZONE of 0 means there is intentionally no OPZONE for the IPZONE. There should be an OPZONE for every zone (1-OPZONES); if not, a message is issued. To accommodate this process, the normal output matrices are trapped, renumbered, and saved, at the normal output phase. When all zones have been processed, the saved matrices are retrieved in appropriate order, combined when necessary, and written to the MATO files. The intermediate matrices are saved either in RAM (normal format), or on disk files (compressed format). If saved on disk, there must be sufficient disk space for both the intermediate rows, and the final output files. The process is optimized to the extent possible; the use of the FILES and INRAM keywords could help considerably in reducing running times.
RENUMBER keywords
Keyword FILE |F| Description File that contains the zonal equivalencies. FILE and ZONEO are mutually exclusive. Only one of those two keywords can be used at one time.
RENUMBER keywords (continued)

Keyword FILES |I| Description Number of temporary files to use to store intermediate factored matrix rows, until they can be sorted and combined in the final stages of the application. The value must be in the range 1-10, inclusive. If the keyword is not specified, the program will set the value to ZONES/100, but never less than 1, nor greater than 10. The number of files affects the running time when the final matrices are being formed; more files generally speeds up the final stage. Ten files will normally reduce the application time by a factor of about 20-35 per cent as compared to one file. Single character (if a longer string is specified, only the first character is processed) to indicate how to treat input zones that are not fully allocated (ROWPCT and COLPCT totals of 100). The character may be F, W, or M, and if it is none of these, or MISSINGZI is not specified, it defaults to F. The meanings are: F Fatal W Warning M Message only (no penalty associated) MISSINGZO ZONEO |S| |S| Indicator similar to MISSINGZI. It indicates the level of error associated with gaps in the OPZONE structure. Alternate method of specifying zonal equivalencies using an input zonal data file. A typical value of ZONEO is an input zonal attribute: ZI.**.***. In this convention, the IPZONE is the current zone number and the OPZONE is the specified input zonal attribute, for example, district or TAZ number. ZONEO and FILE are mutually exclusive. Only one of those two keywords can be used at one time. Designates the highest new zone number and serves as an editor as the file records are read, to ensure that each OPZONE doesnt exceed this value. If ZONES is not designated, no edit is performed, and ZONES is set to the highest OPZONE. A check is made to ensure that there is an OPZONE for all values: 1-ZONES; if there are any gaps, a message is issued.
MISSINGZI
|S|
ZONES
|I|
Example[1]
FILEI MATI=IN.MAT FILEO MATO=OUT.MAT, MO=1
MW[1]=MI.1.1 ; must load values into MW[1], else OUT.MAT will be all zeros ; renumber OUT.MAT according to 2005ZON.EQ RENUMBER FILE=2005ZON.EQ, MISSINGZI=M, MISSINGZO=W
Example[2]
FILEI MATI=IN.MAT, ZDATI=ZDATIN.DAT, Z=#1, DIST=2 FILEO MATO=OUT.MAT, MO=1 MW[1]=MI.1.1 ; must load values into MW[1], else OUT.MAT will be all zeros ; renumber OUT.MAT according to ZDATIN.DAT RENUMBER ZONEO=ZI.1.DIST
Example[3]
/* This is a two step process to show an example of using RENUMBER to split an existing pair of trip tables for a new disaggregate zone system. A typical process might be to split zones into fully nested sub zones in ArcView. This example assumes such a spatial procedure has been preformed and the resulting dbf file has the zonal area of both the parent zones and the new split zones. This first step uses MATRIX to compute split factors based on the ratio of the new zone-to-old zone area and writes out the zonal equivalency file for use in the subsequent renumbering step. */ ;STEP 1 RUN PGM=MATRIX FILEI ZDATI[1] = TAZDATA1.DBF ; Data structure of TAZDATA1.DBF is: ;Z NEW_Z1 NEW_Z2 Z_AREA Z1_AREA Z2_AREA ;1 1 2 6.40 2.22 4.18 ;2 3 4 6.42 3.18 3.24 ;3 5 6 6.44 3.78 2.66 ;4 7 8 6.46 2.58 3.88 ;5 9 10 6.48 3.75 2.73 ; . . . PARAMETERS ZONES=2999 ; establishes a split factor based on the new zone geography ; the split factor is the ratio of the area of the new zone to the area ; of its parent. This set up assumes all input zones are split into two output zones ; and that the total area of the new zones is equal to the area of the parent zone. SPLIT1=100*(ZI.1.Z1_AREA/ZI.1.Z_AREA) SPLIT2=100-SPLIT1 ; writes the split factors to the PRN file PRINT LIST=SPLIT1,SPLIT2
; write the zonal equivalency file PRINT LIST=I,ZI.1.NEW_Z1,SPLIT1, FILE = EQUIV_1.DAT" PRINT LIST=I,ZI.1.NEW_Z2,SPLIT2, FILE = EQUIV_1.DAT" ; data structure of EQUIV_1.DAT is : ; 1.00 1.00 34.69 ; 1.00 2.00 65.31 ; 2.00 3.00 49.53 ; 2.00 4.00 50.47 ; 3.00 5.00 58.70 ; 3.00 6.00 41.30 ; 4.00 7.00 39.94 ; 4.00 8.00 60.06 ; 5.00 9.00 57.87 ; 5.00 10.00 42.13 ; . . . ENDRUN ;STEP 2 split input trip table to new zonal system RUN PGM=MATRIX FILEO MATO[1] = TRIPS2.MAT, MO=1-2, NAME=AUTO, TRANSIT FILEI MATI[1] = TRIPS1.MAT mw[1]=mi.1.1 ; fill work matrix 1 with AUTO trips from input matrix 1 mw[2]=mi.1.2 ; fill work matrix 2 with TRANSIT trips from input matrix 2 RENUMBER, FILE = EQUIV_1.DAT ; the zonal equivalency file has the fields IPZONE, OPZONE and ROWPCT ; the default when no COLPCT is specified is to set the COLPCT=ROWPCT. ; if different COLPCT factors are desired they would need to be specified in the ; fourth column of the file. ENDRUN
REPORT
Program: Matrix
Request reports and establish tracing MARGINS TRACE MARGINREC (CFORM FORM LIST FILE (PRINT))
ZDAT (DEC) MATSTAT

REPORT keywords
Keyword MARGINREC Subkeyword |K?| Description Switch that indicates that MARGIN summary records for each zone are to be written to the standard output and/or a designated file. It differs from the function of the MARGINS keyword. The keywords that are subordinate to MARGINREC are a subset of those available on a standard Cube Voyager PRINT control statement as shown below. Variable values are formatted to the zonal record; normally, the variables are row and column values obtained from the accumulation of margin values for work matrices, but any variable or literal string can be specified. Format to use for any character data items that appear after this keyword. Specifies a file where the formatted list is to be written. Only one FILE value is allowed per each MARGINREC switch. A separate file is written for each MARGINREC FILE value. If names conflict, the earlier files will be overwritten. Format to use for any numeric data items that appear after this keyword.
MARGINREC MARGINREC
CFORM FILE
|S| |F|
MARGINREC
FORM
|S|

Keyword MARGINREC Subkeyword LIST |KSV| Description Specifies the items (variables and/or strings) that are to be formatted to the print line. If it is desired to have an explicit format for any item in the list, there may be a format appended to the it. Such a format is surrounded by (); the format applies to only that item. Example:
J ITEM1(6) ITEM2(8C) 'abcde' 'i='(8R) K(L)
The variables are normally a character (R, C, or I) followed by a number. R1 indicates the row total for work matrix one; C2 indicates the column total for work matrix two, and I4 is the intrazonal value for work matrix four. Variables can be formed by concatenating R, C, and I names with an underscore '_' acting as the concatenating character. Example: R1_C1 is the sum of the row value and the column value for the zone. I1_I2_I3 is the sum of the intrazonal values for matrices one, two, and three. Other variables can be inserted into the record, but the most meaningful one would be J. A record is written for each zone (J=1,Zones), and J is the zone variable that is used. MARGINREC MARGINS PRINT |?| |KIP| Switch that indicates that the FILE record is to also be written to the standard printed output. Requests that row and column totals be accumulated and reported for the specified MWs (work matrices). If, for some reason, there is insufficient RAM to accumulate all the totals, the program will delete (and notify) some, or all, of the requests as required. Each MW report is listed in telephone book style with empty zones being omitted. NOTE: MARGINS and MARGINREC cause the program to accumulate margin values for each zone for each of the included matrices. If there is insufficient RAM, margin accumulation could be canceled for certain matrices. MATSTAT |S3| Specifies desired matrices for which statistical summaries will be formatted and reported in the run print file. Valid values are: MI, MO, and MW to generate reports for input matrices, output matrices and working matrices.

Keyword TRACE Subkeyword |K?| Description Controls the listing of the stack statements as they are processed (can be quite voluminous, so be careful). Trace can be turned on and off at any time, thus controlling the amount of output as desired. If a COMP is traced, only the first five J values will be reported. Switch that indicates that the zonal data arrays generated by any FILEI ZDATI keywords are to be formatted and reported. Sets the maximum number of decimal places to be printed for any variable. This one value applies to all variables on all ZDATI statements.
ZDAT
|?|
ZDAT
DEC
|I|
Example
These statements illustrate REPORT.

REPORT MARGINS=1-3,8 ; request margins summaries REPORT TRACE=y ; turn stack tracing on REPORT TRACE=n ; turn stack tracing off MARGINREC=y LIST=J,R1,C1,R2,C2,R3_R4_C3_C4,R5_C5 MARGINREC=y LIST=J,' sum intras for 1-3=', I1_I2_I3, FILE=r:\intras,print=y REPORT MATSTAT=MW ; request statistical summaries for working matrices
Example MATSTAT REPORT:

Table 1 - Matrix Summary (625 cells) ----------- Sum ----------- ---- Cnt --- ----------- Ave ---------ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 16,455.14 16,455.14 -- 256 -- 26.32822 64.27789 -MW[2] 9,923.04 9,923.04 -- 256 -- 15.87686 38.76187 -MW[3] 978.99 978.99 -- 256 -- 1.56638 3.82418 -MW[4] 27,357.17 27,357.17 -- 256 -- 43.77147 106.86395 -Table 2 - Matrix Min/Max (625 cells) ---------- Minimum -------------- ------------ Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 2.5450 3-16 -- --- 1,007.71 13-13 -- --MW[2] 3.1050 3-16 -- --- 370.64 13-13 -- --MW[3] 0.1015 13-12 -- --- 39.65 1-1 -- --MW[4] 6.0145 3-16 -- --- 1,378.97 13-13 -- --Table 3 - Matrix Intrazonal Summary (625 cells) ---------- Sum ---------- ---- Cnt --- ----------- Ave ----------
ALL >0 <0 >0 <0 ALL >0 <0 MW[1] 3,059.99 3,059.99 -- 16 -- 4.895984 191.24937 -MW[2] 1,629.70 1,629.70 -- 16 -- 2.607520 101.85625 -MW[3] 178.27 178.27 -- 16 -- 0.285232 11.14187 -MW[4] 4,867.96 4,867.96 -- 16 -- 7.788736 304.24750 -Table 4 - Matrix Intrazonal Min/Max (625 cells) ---------- Minimum ------------- ------------ Maximum ------------->0 @I-J <0 @I-J >0 @I-J <0 @I-J MW[1] 4.82 3-3 -- --- 1,007.71 13-13 -- --MW[2] 6.09 12-12 -- --- 370.64 13-13 -- --MW[3] 0.12 5-5 -- --- 39.65 1-1 -- --MW[4] 18.74 7-7 -- --- 1,378.97 13-13 -- ---
SET
Stores numeric values into one, or more, variables. VAL VARS Use SET to set any number of variables to some value. All variables are set to zero at the beginning of the I loop, and are then changed only by the user. Most changes are the result of COMP statements. A COMP statement can accomplish all that SET does, but it is not as efficient, and is somewhat wordier.
SET keywords
Keyword VAL |R| Description Numeric value that the VARS that follow will be set to. VAL is initialized to zero when the statement is started, and then reset as this keyword is encountered. If there is no VAL, the coded VARS are all set to zero. List of variables that are to be set to the more recent value of VAL obtained from this statement. If a named VARS is an array allocated by an ARRAY statement, the entire array is set to the value of VAL.
VARS
|S|
Example
SET VAL=0, VARS=TOT1,TOT2,COUNTER COMP TOT1=0 TOT2=0 COUNTER=0 ; is the same as previous statement SET VARS=TOT1 TOT2 COUNTER ; is also the same (VAL defaults to 0)
SET VAL=123 VARS=C123, VARS=TOT1, TOT2, TOT3 ; sets all to 123 ARRAY SUMS=50 SET VAL=100, VARS=SUMS ; sets all 50 cells of SUMS to 100 SET VARS=SUMS ; sets all 50 cells of SUMS to 0
SORT
Sort user-defined arrays. ARRAY NUMRECS See SORT on page 72 for details about the standard Cube Voyager statement.
Example
ARRAY ZONENO=ZONES, HH=ZONES, INCOME=ZONES . . ZONENO[I] = I HH[I] = ZI.1.HH[I] INCOME[I] = ZI.1.INCOME[I] . . SORT ARRAY=-INCOME,-HH,ZONENO, NUMRECS=ZONES LIST= Zone Income HHs JLOOP PRINT FORM=8, LIST=ZONENO[J], INCOME[J], HH[J] ENDJLOOP
WRITE
Output record data files to DBF format RECO
Use WRITE to specify the record files that are to be written at the end of each I zone.
WRITE keyword
Keyword RECO |I| Description Number of the FILEO RECO[#] DBF file where you want to direct this print output.
Matrix Program Examples
Examples
This section contains examples that demonstrate the Matrix program: Example 1 Example 2 Example 3 Example 4
Example 1
RUN PGM=MATRIX /* Sample problem to generate a zonal data file from input files The resulting zonal file will contain combined data from the input zonal data and a summary of trips to the zones that are in the cbd */ mati[1]=tripfile.mat zdati[1]=socoecon.dat,z=#1, pop=#2, area=#3, income=#4, hh1=#5, hh2=#6, hh3=#7 zdati[2]=employ.dat, z=#1, gov=#2, retail=#3, other=#4 ARRAY pop=10, area=10 totemp=10, tothh=10 ; this is a 10 zone problem area[i]=zi.1.area totemp[i]=zi.2.gov + zi.2.retail + zi.2.other tothh[i]=zi.1.hh1 + zi.1.hh2 + zi.1.hh3 jloop include=1-5,38,56-100,145-150 ;cbd zones cbdtrips[j] = cbdtrips[j] + mi.1.tottrips[j] endjloop if (i==zones) ; at last zone jloop ; write a file of zonal records print file=newzdat.zda form=6 list=j(3) pop[j] area[j] totemp[j] tothh[j] cbdtrips[j] endjloop endif ENDRUN
Example 2
; Get I-J values for records with trip tours on them. /*Sample setup to use the MATRIX program to process the tours.dat file
For each leg of the tour, look up highway or transit time based on the major mode for that journey, assuming 1 is highway otherwise transit The program will read each input record from the RECI file and do calculations as specified. The MatVal function is used to random access any i-j value from any input matrix. The format is: MatVal( filenumber, tablenumber, i, j, failvalue) The failvalue is returned if lookup fails (invalid filenumber, tablenumber, i, or j) This script has been tested for validity, but has not been thoroughly tested for logical content. */ RUN PGM=MATRIX mati=hwytime.mat,trntime.mat reci=tours.dat, org=23, dst=26 ; there are 80 fields on the record, can be referenced by reci.nfield[#]. ; Field 23 can also be referenced as ri.org, and field 26 as ri.dst ; setup array to store time values with max of 8 legs on each tour array hwyt=8 trnt=8 set val=0, vars=hwyt trnt ; initialize output variables ; trips from org to dst from=ri.org leg=1 loop stops=32,42,5 ; flds 32,37,42 if (reci.nfield[stops] > 0) ; if main mode org-dst is hwy if (reci.nfield[76] = 1) ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0) endif leg=leg+1 from=reci.nfield[stops] endif endloop ; from last stop to dst if (reci.nfield[76] = 1) ; if main mode org-dst is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,ri.dst,0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,ri.dst,0) endif ; trips from dst to org
from=ri.dst leg=5 loop stops=47,57,5 if (reci.nfield[stops] > 0) if (reci.nfield[77] = 1) ; if main mode dst-org is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,reci.nfield[stops],0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,reci.nfield[stops],0) endif leg=leg+1 from=reci.nfield[stops] endif endloop ; from last stop to org if (reci.nfield[77] = 1) ; if main mode dst-org is hwy ; from file 1 table 1 hwyt[leg]=MatVal(1,1,from,ri.org,0) else ; from file 2 table 1 trnt[leg]=MatVal(2,1,from,ri.org,0) endif ; write out I/P record(RECI) and append highway and transit time values print file=tourtime.dat, form=5 list=reci, hwyt[1],hwyt[2],hwyt[3],hwyt[4],hwyt[5],hwyt[6],hwyt[7],hwyt[8], trnt[1],trnt[2],trnt[3],trnt[4],trnt[5],trnt[6],trnt[7],trnt[8] ; compute totals of highway and transit time arrays hwyt_tot=arraysum(hwyt) trnt_tot=arraysum(trnt) ENDRUN
Example 3
/* This is an example of using RECI/RECO processing of DBF data files */ RUN PGM=MATRIX FILEI RECI = ZONES_2002.DBF FILEO RECO[1] = ZONES_2002_NEW.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), EXCLUDERECI=HOUSEHOLDS FILEO RECO[2] = ZONES_2010.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(4.2),
EXCLUDERECI=HOUSEHOLDS FILEO RECO[3] = ZONES_2020.DBF, FIELDS=RECI.ALLFIELDS, HH_2002(8.0), HHsiz_2002(4.2), Pden_2002(6.2), POP_2010(8.0), HH_2010(8.0), HHsiz_2010(4.2), Pden_2010(6.2), POP_2020(8.0), HH_2020(8.0), HHsiz_2020(4.2), Pden_2020(6.2), EXCLUDERECI=HOUSEHOLDS ; compute regional base year statistics TotalHH=TotalHH+RECI.NFIELD[5] TotalPop=TotalPop+RECI.NFIELD[6] avgHHsize=TotalPop/TotalHH ; print regional base year statistics if (I=0) ; check for end of file PRINT LIST='Total Households = ',TotalHH PRINT LIST='Total Population = ',TotalPop PRINT LIST='Average Household size = ',avgHHsize endif ; rename RECI field RO.HH_2002=ri.HOUSEHOLDS ; calculate zonal average household size for base year RO.HHsiz_2002=ri.POP_2002/HH_2002 ; calculate zonal population density per/acre for base year RO.Pden_2002=ri.POP_2002/(ri.AREA/43560) ; factor base year data for 2010 RO.HH_2010=HH_2002*1.2 RO.POP_2010=RECI.NFIELD[6]*1.4 RO.HHsiz_2010=POP_2010/HH_2010 RO.Pden_2010=POP_2010/(ri.AREA/43560) ; factor base year data for 2020 RO.HH_2020=HH_2002*1.5 RO.POP_2020=RECI.NFIELD[6]*1.8 RO.HHsiz_2020=POP_2020/HH_2020 RO.Pden_2020=POP_2020/(ri.AREA/43560) ; write data to defined output files WRITE RECO=1,2,3 ENDRUN
Example 4
/* Example of using the CHOICE command in MATRIX to estimate a singly constrained gravity model constrained on Production trip ends */ RUN PGM=MATRIX FILEO MATO[1] = "C:\CUBETOWN\MODEL\MODELS\SINGLEPRODDIST.MAT" MO=1 NAME=HBW
FILEI ZDATI[1] = "{SCENARIO_DIR}\TRIPENDS.DBF" FILEI MATI[1] = "{SCENARIO_DIR}\CURRENTCOSTS.MAT" ;The general approach for a singly constrained in Voyager is to use the MATRIX ;program and the CHOICE command to implement a destination choice model. ;If you require a gamma curve deterrence function rather than the negative exponential, ;you need to specify the appropriate calculations yourself. ;This example gives a destination choice model constrained on production trip ends. CHOICE ALTERNATIVES=all1, DEMAND=ZI.1.P1, COSTS=mi.1.1, ODEMAND=1, STARTMW=99, DESTSPLIT = TOTAL 0.2 all1 ;To apply singly constrained on attractions; ;- transpose the cost matrix, saving it to output file ;- run MATRIX, reading the transposed costs, reversing your use of the ; production and attraction data (i.e., TOTAL=ZI.1.A[1] etc) ; to implement a destination choice, with attraction totals as the single constraint. ;- transpose the resulting matrix to correct orientation. ENDRUN
Example 5
/* Example of DBI processing to combined two fields from different tables stored in a MDB file to a new table in the MDB file using the JOINTTODBI functionality. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta2", FIELDS=ZONE_ ALFA BETA FILEI DBI[2] = "DBI_Examples.mdb\BETA", SORT=ZONE_ JOINTODBI=1 JOINTOFIELDS=ZONE_ FILEI DBI[1] = "DBI_Examples.mdb\ALFA" ZONES=1 LOOP k=1,DBI.1.NUMRECORDS x=DBIReadRecord(1,k) RO.ZONE_=DI.1.ZONE_ RO.ALFA=DI.1.ALFA RO.BETA=DI.2.BETA WRITE RECO=1
ENDLOOP ENDRUN
Example 6
/* The same process as Example 5 but using AUTOARRAY functionality to accomplish the same task. */ RUN PGM=MATRIX FILEO RECO[1] = "DBI_Examples.mdb\AlfaBeta3", FIELDS = ZONE_ ALFA(10.4) BETA(10.4) FILEI DBI[2] = "DBI_Examples.mdb\BETA", AUTOARRAY=BETA FILEI DBI[1] = "DBI_Examples.mdb\ALFA", AUTOARRAY=ALFA ZONES = 1 LOOP L3=1,DBI.1.NUMRECORDS,1 RO.ZONE_ = L3 RO.ALFA = DBA.1.ALFA[L3] RO.BETA = DBA.2.BETA[L3] WRITE RECO = 1 ENDLOOP ENDRUN
10
Distribution Program
This chapter discusses the trip distribution process. Topics include: Introduction to the Distribution program Control statements Examples
10
Distribution Program Introduction to the Distribution program
Introduction to the Distribution program

This section introduces you to the Distribution program. Topics include: Overview Convergence: Iteration control Multiple purposes Referencing productions and attractions Travel function values: Friction factors
Overview
Trip distribution is the process of estimating the number trips that will travel between all the zones in the system. Usually the process uses the number of trip ends in each zone as the starting point. These margin totals are distributed to the rows and column of a generated matrix. Usually, additional information about some measure of travel between each zone pair should be included in the process. The most commonly used distribution process is the gravity model, but other processes are also employed. Cube Voyager does not have any automatic, or default, trip distribution process. The Matrix program provides a framework that allows the user to perform distribution in a variety of ways. In some cases, the Matrix program does have some built-in functions that aid in the implementation of the more popular distribution processes. A gravity model distribution can be easily implemented within Matrix, but it does need some help, and the user has to follow certain guidelines for proper implementation. A brief illustration of a typical gravity distribution follows. The gravity model equation is: TRIPi-j = Pi * Aj * func(Ti-j) / Sz=1..n (A * func(T)). where: P = the number of trip productions for a zone.
10
A = the number of trip attractions for a zone. T = the travel impedance factor between zones. i = the production zone. j = the attraction zone. z = any zone. n = the number of zones. In simple terms this states that the trip productions in zone I will be distributed to each zone J according to the relative attractiveness of zone J. Each Js attractiveness is determined by the product of its attractions and some function of the spatial separation between I and J. The sum of the these products for all Js (relative to I) is obtained and often referred to as the accessibility index for I. Each J will then be given a prorata share of the productions for I based upon its attractiveness relative to the accessibility index for I. The function of spatial separation (func(T)) is the indefinite portion of the equation. It is believed to be best described by an expression of the form of e^bT, where b is the curve factor, and T is the travel time. Experience has shown that often a single curve does not suffice, and it difficult to estimate what b should be used. To facilitate application, most gravity model processes use a lookup function to obtain empirical values for the function based upon the impedance. These curves are usually called friction factor curves. Numerous applications have shown that friction factor curves tend to follow the same patterns for similar conditions. Many agencies share the same curves when their regions are similar in nature. To implement the gravity model in Matrix, several guidelines must be followed: There must be a set of Ps and As for each purpose to be estimated. They are established by the presence of a SETPA control statement.
10
A mechanism must be established to obtain the travel function. Usually, a level-of-service matrix is used to obtain the zone-tozone impedance for I-J, and the travel function value (friction factor) is obtained by finding the impedance in a LOOKUP table. The gravity model equations must be executed in a specific order. At least three expressions are required. One to compute attractiveness for each J, one to sum them to form the accessibility index for I, and one to distribute the productions based upon the values and the accessibility index. Obviously, these expressions must be executed in the proper order.
As an alternative to complete user definition of the gravity formulation, the GRAVITY control statements can be used to perform a built in process for a doubly constrained GRAVITY model. This process is more efficient than complete formulation. A singly constrained gravity model can be formulated as a destinationchoice model with the CHOICE control statement in Matrix. See Examples on page 534 under the Matrix program for an example of a singly constrained gravity model.
Example 1
/* given: The impedances are in the first matrix of file: IMP.MAT The productions and attractions are in file: PA.ZDA The friction factors are in file: FF.DAT */ FILEI MATI[1] = IMP.MAT, ZDATI[1] = PA.ZDA,Z=#1,P1=#2,A1=#3 FILEO MATO[1] = OUT.MAT, MO=1 LOOKUP NAME=FF,LOOKUP[1]=#2,RESULT=#1, FILE=FF.DAT, INTERPOLATE=Y SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1 MW[1] = A[1] * FF(1,MI.1.1), PAF=P[1]/ROWSUM(1), MW[1]=PAF * MW[1] GRAVITY PURPOSE=1, LOS=MI.1.1, FFACTORS=FF ; faster process
10
Convergence: Iteration control

The gravity model equation ensures that the correct number of trips will be distributed for each I zone; the row (production zone) totals for each will always match the number Ps for the zone. There is no method to guarantee that the correct column totals (number of attractions) will be obtained for each J zone. In all likelihood, the estimated column values will not match the desired number of As input for each zone. This problem is alleviated by iterating the model. An iteration is a complete pass for all I zones. At the end of each iteration, the estimated column totals are compared to the input As, and, based upon the comparison, the process is repeated with an adjustment in the data. The adjustment is based upon the closeness for each zone. The iteration process is repeated until it is decided that the results are close enough, or that a maximum number of iterations have been performed. Following is small example of this process: Prior to the first iteration the desired totals are:
Zone 1 2 3 Total 1 -- -- -- 100 2 -- -- -- 200 3 -- -- -- 300 Total 240 200 160 600
There really is no matrix yet. The totals are the values as obtained from the SETPA control statements. The model goal is to fill in the matrix with values so that the totals will match the totals shown. The row totals shown are the Desired Ps for each zone, and the column totals are the Desired As. A set of A values internally named Used are set equal to the Desired values. An iteration is performed and the Estimated results appear as: After Iteration 1:
Zone 1 2 3 1 57 24 19 2 64 106 30 3 102 61 137 Total 223 191 186 Use2 258 210 138 Total 100 200 300 600
10
As dictated by the formulation, the row totals are correct. But, the Estimated column totals do not quite match the Desired. The As for each zone are adjusted by a factor that is computed as: Desired * Used / Estimated. Another iteration is performed, and the results appear as: After Iteration 2:
Zone 1 2 3 1 60 24 16 2 67 108 25 3 113 66 121 Total 240 198 162 Use3 258 212 136 Total 100 200 300 600
The Estimated column totals are still not exactly what is desired, so adjustments are made to the used As, and another iteration is performed. After Iteration 3:
Zone 1 2 3 Total 1 60 24 16 100 2 66 109 25 200 3 114 67 119 300 Total 240 200 160 600
Now the Estimated totals and the Desired totals match for all zones. The model is completed. Further iterations would be useless; nothing would change. In the real world, with many zones, it is not likely that all the Estimated totals would match exactly with the Desired totals. As a matter of fact, in this simple three zone problem, the totals did not match exactly (there were some slight differences in the decimal places). But, the floating point values were close enough to be accepted as having matched. How does the program decide when it should stop? There are two parameters that can be used for controlling cutoff: MAXITERS and MAXRMSE. MAXITERS specifies that no more than a specified number of iterations are to be performed. The default is MAXITERS=3; this is usually sufficient for most gravity model applications. Additionally,
10
the program computes the root mean square error of the differences in Estimated vs. Desired attractions (sqrt (Sum(diff^2) / (n-1)). If the computed RMSE is less than MAXRMSE, a completion flag is set. The default is MAXRMSE=10, but that may not always be a good choice for certain applications. In the sample three zone problem the RMSEs for each iteration were computed as: 22.78, 2.08, and 0.26. The final value of 0.26 indicates that there were still some slight differences in the Estimated and Desired, but as noted above, they were insignificant. If the default MAXRMSE value had been used, the process would have cutoff after two iterations.
Multiple purposes
Usually a given application will consist of more than one purpose. Traditionally, at least three internal purposes are estimated, with the most commonly used purposes being: Home Based Work (HBW), Home Based Other (HBO), and Non Home Based (NHB). There are other popular purpose stratification, but these are the most commonly used. Often Internal-External and External-Internal and truck and taxi purposes are also estimated; some analysts prefer to estimate them in a separate application, and some prefer to do them all at once. With the Cube Voyager process, all the purposes can be estimated in one application because the user has the ability to specify different gravity equations for each of the purposes. Each purpose can have its own impedance matrix and different formulation (functions, expressions, friction factors, etc.). The Ps and As and lookup functions can be obtained from different sources. There is one caveat: If convergence has not been reached for any purpose, and MAXITERS has not been reached, another iteration will be processed with adjusted As for all purposes. That is no concern; the results will not get worse. The MAXRMSE parameter applies to the highest RMSE of all purposes. MATO files are written only on the last iteration. If the iteration number is equal to the PARAMETERS MAXITERS value, the program knows when the last iteration is being processed. But, convergence could be obtained at some lower iteration. In that case the program will perform another iteration, similar to the one just completed, but this time writing
10
the MATO files. In other words, if convergence is reached before MAXITERS, an additional iteration will be performed in order to obtain the matrices. The use of PARAMETERS MATOEVERY will preclude an additional iteration, but at the cost of additional time to write matrices during each iteration. The number of purposes is determined by the highest P[] or A[] index established via the SETPA control statement. The program assumes that there will be purposes from one, monotonically, through that highest index. Other COMP MW[]= statements may be specified, but they will not be involved in any internal purpose editing. If the estimates follow the same formulation, the set up is only slightly different from what is depicted, above. Example 2 illustrates a typical setup for a three purpose application.
Example 2: Three purpose - same P/A and FF file for all purposes
LOOKUP FILE=FF.DAT, INTERPOLATE=Y, NAME=FF, LOOKUP[1]=1,RESULT=2, LOOKUP[2]=1,RESULT=3, LOOKUP[3]=1,RESULT=4 SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1, P[2]=ZI.1.P2, A[2]=ZI.1.A2, P[3]=ZI.1.P3, A[3]=ZI.1.A3 LOOP PURP=1,3 MW[PURP] = A[PURP] * FF(PURP,MI.1.1) PAF=P[PURP]/ROWSUM(PURP) MW[PURP]=PAF*MW[PURP] ENDLOOP
In Example 3, purposes 1-3 are the same as in Example 2, and two internal-external purposes (with entirely different formulation) are to also be included. Purpose 4 uses an equation for distribution, and purpose 5 uses a simple lookup curve, with only three points in it.
Example 3
LOOKUP FILE=FF.DAT, INTERPOLATE=Y, FAIL=12000,1,0, NAME=FF, LOOKUP[1]=1,RESULT=2, LOOKUP[2]=1,RESULT=3, LOOKUP[3]=1,RESULT=4
10
LOOKUP NAME=XIFF, FAIL=500,100, R= '500 1-20', ; read the data directly '400 20-30', '300 30-40', '200 40-50' SETPA P[1]=ZI.1.P1, A[1]=ZI.1.A1, P[2]=ZI.1.P2, A[2]=ZI.1.A2, P[3]=ZI.1.P3, A[3]=ZI.1.A3 SETPA P[4]=ZI.2.PI, A[4]=ZI.3.STACNT_OB, P[5]=ZI.2.AI, A[5]=ZI.3.STACNT_IB LOOP PURP=1,3 IF (PURP <= 3) MW[PURP] = A[PURP] * FF(PURP,MI.1.1) ELSEIF (PURP==4) JLOOP INCLUDE=1-500 IMP = MI.2.IMPEDNACE IF (MI.2.DISTANCE < 3) IMP = MI.2.SHORTIMP MW[4] = A[4]*EXP(-B * IMP) ENDJLOOP ELSE MW[5] = A[5] * XIFF(MI.2.IMPEDANCE) INCLUDE=501-535 ENDIF PAF=P[PURP] / ROWSUM(PURP), MW[PURP]=PAF*MW[PURP] ENDLOOP
Of course, there are different ways that this distribution could have been written. Most likely, the purpose 4 and 5 Ps and As would not sum to the same total because they were derived from separate sources. If there is a difference in the totals for a purpose, the program issues a message and adjusts the As to match the P total. Differences in the totals would preclude convergence via RMSE calculations because there would always be differences.
Referencing productions and attractions

Productions and attractions are referenced by using array notation for P and A. P and A are doubly dimensioned arrays, where the first index references the purpose number, and the second index references the zone number. Since most users may not wish to always code a zone index (it is more intuitive to reference the arrays with just purpose number), the zone index need not be supplied; it will be automatically provided. However, the zone index has
10
different meanings for P and A. For P, the default zone index is I and for A, it is J. If a different index is required, it may be explicitly provided. Most times an invalid index will cause a fatal termination. Purpose 0 and Zone 0 are valid, but may not always be predictable. Zone 0 should always contain the total for the purpose. The lower bounds for both indices are zero, and the upper bounds are number of purposes and zones, respectively. P and A are protected variables; they may not be the result of COMP expressions, except on SETPA statements.
Travel function values: Friction factors

If friction factors are to be used in the distribution process, they are normally input to the program from an external lookup file. The lookup file is usually formatted as a series of curves one curve for each trip purpose. The curves are organized vertically on the records of the file. A typical file would appear as:
1 9000 8000 7000 2 8000 7000 6000 3 7000 6300 5200 : : 50 1 1 1 51 0 0 0
This file would be described with a LOOKUP statement such as:

LOOKUP FILE=FF_FILE, NAME=FF, LOOKUP[1]=1, RESULT=2, LOOKUP[2]=1. RESULT=3, LOOKUP[3]=1, RESULT=4
This statement indicates that the first four values from each record will be used. Field 1 will be the travel time value, and fields 2, 3, and 4 are the values for purpose 1, 2, and 3, respectively. The friction factor for purpose 1 for 1 minute would be 9000, and the friction factor for purpose 2 would be 8000. The friction factor for purpose 1 for a time value of 1.5 could be either 9000 or 8500, depending upon the options specified on the LOOKUP statement. If
10
SETUPPER=T is specified, the friction factor will be 9000, and if SETUPPER=F and INTERPOLATE=T, the friction will be 8500. This capability allows for compatibility with other model systems. In this example, a time value of 0.5 will result in the value 9000, because there is no explicit FAIL[1] specified. The friction for any value greater than 51 will be 0; no distribution. If the record for 51 were not in the file, the friction factor for any time greater than 50 would be 1. However, if FAIL[2]=0 were used, any time greater than 50 would be 0. It is recommended that a final value of 0 be used to preclude distribution to zones where the I-J time exceeds a certain value. This can also be controlled by use of the LOSRANGE keyword on the GRAVITY statement.
10
Distribution Program Control statements
Control statements
Most of the standard Matrix program statements are valid in the Distribution program, and a few additional ones are available. Since the Distribution program is a subset of the Matrix program, it is assumed that the user is familiar with the Matrix-program control statement set. Only the differences between the Matrix and Distribution control statements are included in this section. For descriptions of other control statements see Control statements on page 436 under the Matrix program. Matrix program statements not allowed in the Distribution program:
RENUMBER
Distribution program statements not in the Matrix program:

SETPA GRAVITY
Distribution program keywords not in the Matrix program:

PARAMETERS MAXITERS= MAXRMSE= REPORT ACOMP=
GRAVITY
Performs a standard gravity model. PURPOSE LOS FFACTORS KFACTORS LOSRANGE
10
This statement is used to have the program compute a distribution based upon traditional gravity model formulation for a single purpose. It is more efficient than using multiple COMP statements to formulate the same process.
GRAVITY keywords
Keyword FFACTORS |SN| Description Specifies the expression that results in the friction factor that a gravity equation expects. Normally, this would be the name of the lookup table that contains the friction factors that correspond to the values that are to be extracted from LOS. In this statement, no arguments should be used with the lookup name. The lookup table is expected to be in the form shown in the Examples. The lookup arguments will be automatically set to the value from the LOS matrix and the PURPOSE number. See LOOKUP on page 51 for hints about using Lookups to obtain friction factors. Specifies the matrix that contains the K-factor values for each I-J distribution. The value MUST be either a MW[#] or an MI.#.name/#. Specifies the matrix that contains the level-of-service values for each I-J distribution. The value MUST be either a MW[#] or an MI.#.name/#. Optional. Specifies the range of LOS values that are valid for use in the distribution process. If an I-J values is less than the first value or greater than the second value, there will be no distribution between for I-J. This keyword must be followed by a pair of numbers separated by a dash. The first number must be 0, or greater, and the second value must be greater than the first. Default range is 0 - 999999. Specifies which purpose this is calculation to: the results will be stored in MW[PURPOSE].
KFACTORS
|S|
LOS
|S|
LOSRANGE
[R]
PURPOSE
|I|
PURPOSE, LOS, and FFACTORS must be specified. Example

lookup fail=12000,1,0, list=n, file=tstff1, name=ff, lookup[1]=1,result=2, lookup[2]=1,result=3, lookup[3]=1,result=4,
10
lookup[4]=1,result=5, lookup[5]=1,result=6, interpolate=y,setupper=n gravity purpose=1, los=mw[11], gravity purpose=2, los=mw[11], gravity purpose=3, los=mw[11], gravity purpose=4, los=mw[11], gravity purpose=5, los=mw[11],
ffactors=ff ffactors=ff, losrange=11-48 ffactors=ff ffactors=ff ffactors=ff, Kfactors=MI.1.K5
PARAMETERS
Sets general parameters. MATOEVERY MAXITERS MAXRMSE ZONES In addition to the standard Matrix-program parameters, the parameters described here may also be specified.
PARAMETERS keyword
Keyword MATOEVERY |K?| Description Switch that can be used to force the program to write output matrices for every iteration, instead of waiting until the last iteration. This causes the program to run somewhat longer for each iteration, but may preclude the program from having to run another iteration to obtain the output matrices once convergence is reached. Since the program does not know that a particular iteration will be the final one until after it completes the iteration, it normally does not write matrices for the iteration. This saves a considerable amount of computer time for larger systems. But, it does force another processing iteration to write the matrices once it has determined that this is the last iteration. If it is anticipated that there will be many iterations to reach convergence, it is probably better to set this switch false. If it is anticipated that the process will involve only a few iterations, it is probably better to set this switch true.
10
PARAMETERS keyword (continued)

Keyword MAXITERS |KI| Description Specifies the maximum number of iterations to perform. If the MAXRMSE criterion is met, the number of iterations actually performed could be less than this value. The default is 3, and the max is 99. If the model converges in fewer iterations, one more iteration will be run (with the same values as the converging iteration) so that the MATO matrices will be written. Specifies the cutoff criteria. If the highest RMSE (for any purpose) exceeds this value, automatic cutoff is not triggered. Conversely, if all the purpose RMSEs are less than this value, automatic cutoff is triggered. The default is 10, and the minimum is 0.0001. Specifies the highest zone number to process. If the number of zones can not be ascertained from the project file or from any binary input matrices, ZONES must be provided, or the value will default to 100. If present, this value controls the application. Normally, there will be an input matrix file, so this keyword should not be required.
MAXRMSE
|KR|
ZONES
|KI|
REPORT
Specifies Matrix program reports.
10
ACOMP (ITERATIONS)
REPORT keywords
Keyword ACOMP |KIP| Description Requests that the comparison of Estimated vs. Desired attractions be reported for the specified purposes. The report is in a format that is similar the MARGINS report. The values are reported as nearest integers (without decimal places). Only the purposes specified by the keyword are reported. If the values for ACOMP are followed by ITERATIONS, then those ACOMP purposes will be printed only during the iterations specified. If there are no ITERATIONS specified, the report will be printed for every iteration (could be quite voluminous). In ACOMP reports, zero values are printed with and a printed value of 0 means there is a fractional value present for the cell (the fractions are not printed in the report). Specifies the iterations for which the prior ACOMP purposes reports are to be printed. If no ITERATIONS follow ACOMP values, the reports will be printed for all iterations. If at least one value is equal to, or exceeds, the PARAMETERS MAXITERS, the reports will be printed for the last iteration (no matter how it is determined: parameter or convergence).
ITERATIONS
|IP|
Example
REPORT ACOMP=1-3,5 ITERATIONS=5,10,99 ; specified purposes and iterations REPORT ACOMP=6 ; for all iterations
SETPA
Establishes base productions and attractions. P A INCLUDE EXCLUDE The SETPA statement is required; if it is not included, the program will fatally terminate. The statement defines to the program how the desired productions and attractions are to be obtained, and how many purposes are to be processed. There should be a P[]= and A[]= expression for every
10
purpose beginning with 1 and continuing, monotonically, until all purposes are defined. The highest index encountered establishes the number of purposes. If there are any holes in the purpose scheme, the program will issue a warning statement. The total of the As should match the total of the Ps for each purpose. If the totals differ by more than five percent of the P total, a message is issued. If the totals differ by any amount, the As are scaled so that the A total will match the P total. The Ps and As are computed from the expressions that are supplied. In most cases, the expression will simply point to a ZDATI file variable. Complex expressions are allowed, but the use of any variables in the expression could cause unpredictable results. In a purpose where the Ps and As are the same for each zone, (NonHomeBased is a typical example), it is acceptable to set the Ps, and then set the As equal to the Ps. The SETPA expressions are computed in the order in which they appear in the control stream, and they are computed only one time -- prior to the first iteration. For each array, the expression is solved in a loop of J=1-Zones, and the results are stored in the A[n][J] or P[n][J] cells. A and P may not have a zone index in the SETPA statement. If the same purpose is referenced more than one time (this is acceptable), the subsequent values will replace the prior values. Duplication of purposes might be helpful if values for different zones for a purpose are to be obtained from different sources, or if different INCLUDE/EXCLUDE filters are to be used (separate SETPA statements must be used for different filters).
SETPA keywords
Keyword A EXCLUDE |NV| |IP| Description Expression that is solved to set the attractions for the indexed purpose. Processed the same as EXCLUDE on COMP statements. If it is used, the loop will not be processed for any zones in the list. EXCLUDE filtering follows any INCLUDE filtering. Processed the same as INCLUDE on COMP statements. If it is used, the loop will not be processed for any zones not in the list. INCLUDE filtering precedes any EXCLUDE zones.
INCLUDE
|IP|
10
SETPA keywords (continued)

Keyword P |NV| Description Expression that is solved to set the productions for the indexed purpose.
Example
SETPA INCLUDE=1-500, ; internal zone data only P[1]=zi.1.p1, A[1]=zi.1.a1, P[2]=zi.1.p2, A[2]=zi.1.a2, P[3]=zi.1.nhb, A[3]=P[3], P[4]=zi.2.cnt, A[4]=10 ; equal attraction for all zones SETPA EXCLUDE=1-500, ; get only external data P[1]=zi.1.p1, A[1]=zi.2.cnt, ; merges with prior SETPA P[5]=sqrt(A[3]), A[5]=A[1]+A[2]+A[3] ; weird, but will work
Distribution Program Examples
10
Examples
This section contains examples of the Distribution program: Distribution example 1 Distribution example 2 Distribution example 3
Distribution example 1
RUN PGM=DISTRIBUTION REPORT ZDAT=Y ZDATI[1] = TSTPA1,Z=#1,P1=2,P2=3,P3=4,P4=5,P5=6,A1=7,A2=8,A3=9,A4=10,A5=11 MATI = IMPEDE.MAT MATO = GMTRIPS, MO=1-5, NAME=HBW, HBO, NHB, IX, XI LOOKUP FAIL=12000,1,0, LIST=N, FILE=TSTFF1, NAME=FF, LOOKUP[1]=1, RESULT=2, LOOKUP[2]=1, RESULT=3, LOOKUP[3]=1, RESULT=4, LOOKUP[4]=1, RESULT=5, LOOKUP[5]=1, RESULT=6, INTERPOLATE=N, SETUPPER=Y MAXITERS=3 MAXRMSE=10 SETPA P[1]=ZI.1.P1 P[2]=ZI.1.P2 P[3]=ZI.1.P3 P[4]=ZI.1.P4 P[5]=ZI.1.P5 SETPA A[1]=ZI.1.A1 A[2]=ZI.1.A2 A[3]=ZI.1.A3 A[4]=ZI.1.A4 A[5]=ZI.1.A5 LOOP PURP=1,5 ;DO PURPOSES 1-5 MW[PURP] = A[PURP][J] * FF(PURP,MI.1.1) SUMAF = ROWSUM(PURP) IF (SUMAF > 0) MW[PURP] = P[PURP]/SUMAF * MW[PURP] ENDLOOP ENDRUN
/* Gravity Application illustrating several ways to do gravity model */ RUN PGM=DISTRIBUTION REPORT ZDAT=Y ZDATI[1]=TSTPA1,Z=#1, P1=2, P2=3, P3=4, P4=5, P5=6, A1=7, A2=8, A3=9, A4=10, A5=11 MATI[1]=C:\DEMO\DEMO11.DAT
10
SETPA P[1]=P1 P[2]=P2 P[3]=P3 P[4]=P4 P[5]=P5 SETPA A[1]=A1 A[2]=A2 A[3]=A3 A[4]=A4 A[5]=A5 LOOKUP FAIL=12000,1,0, LIST=N, FILE=TSTFF1, NAME=FF, LOOKUP[1]=1, RESULT=2, LOOKUP[2]=1, RESULT=3, LOOKUP[3]=1, RESULT=4, LOOKUP[4]=1, RESULT=5, LOOKUP[5]=1, RESULT=6, INTERPOLATE=Y, SETUPPER=N MAXITERS=20 MAXRMSE=35 MW[11]=MI.1.1 LOOP PURP=1,5 ; distribute with user equation (Results in MW[6-10]) PP = PURP+5 MW[PP] = A[PURP][J]*FF(PURP,MW[11]) SUMAF = P[PURP]/ROWSUM(PP) MW[PP] = SUMAF*MW[PP] ENDLOOP /* Now do same distribution with gravity statements(more efficient) */ GRAVITY PURPOSE=1, LOS=MW[11], FFACTORS=FF GRAVITY PURPOSE=2, LOS=MW[11], FFACTORS=FF GRAVITY PURPOSE=3, LOS=MW[11], FFACTORS=FF GRAVITY PURPOSE=4, LOS=MW[11], FFACTORS=FF GRAVITY PURPOSE=5, LOS=MW[11], FFACTORS=FF ENDRUN
/* Gravity Application illustrating use of GAMMA Impedance function */ ;-----------------------------------------------------; HBW GRAVITY MODEL USING GAMMA IMPEDANCES ;-----------------------------------------------------; This script reads the composite time skim table created ; from the AM peak period highway and transit skims. ; ; This script then performs the gravity model using the ; estimated friction factors along with the P's & A's ; in order to generate a trip table. ; Finally, a trip length frequency is performed for the ; new trip table. ; run pgm=tripdist zdati[1]=hbwpa.txt,z=#1,p1=2,p2=3,p3=4,p4=5,a1=6,a2=7,a3=8,a4=9 mati=SKIM.MAT mato=hbwgm.mat, mo=1-4, name=Income1,Income2,Income3,Income4 PAR maxiters=20 maxrmse=10
10
setpa p[1]=zi.1.p1 p[2]=zi.1.p2, p[3]=zi.1.p3 p[4]=zi.1.p4, a[1]=zi.1.a1 a[2]=zi.1.a2, a[3]=zi.1.a3 a[4]=zi.1.a4 ; Set P and A Fields ; ======================LOOKUP FUNCTION===================== LOOKUP NAME=_FFParms,; Gamma Function Parameters LOOKUP[1]=1, RESULT=2, ; ALPHA VALUE LOOKUP[2]=1, RESULT=3, ; BETA VALUE INTERPOLATE=N, ; No Interpolation needed on income class R=' 1 -0.020 -0.123', ; Income Class 1, Alpha, Beta ' 2 -0.020 -0.123', ; Income Class 2, Alpha, Beta ' 3 -0.020 -0.123', ; Income Class 3, Alpha, Beta ' 4 -0.020 -0.123' ; Income Class 4, Alpha, Beta ; ==============Put TIME VALUES IN WORKING MATRICES=========== mw[11]=mi.1.1 ; time for income class 1 mw[12]=mi.1.2 ; time for income class 2 mw[13]=mi.1.3 ; time for income class 3 mw[14]=mi.1.4 ; time for income class 4 ; ======CREATE GAMMA VALUE MATRICES FOR EACH INCOME CLASS===== LOOP Inc=1,4 _b=_FFParms(1,Inc) _c=_FFParms(2,Inc) TSKIM=INC+10 ; Input Time Skim to MW[11] to MW[14] GSKIM=INC+20 ; Output Gamma Skim ; PUT GAMMA MATRICES IN MW[21]-MW[24] mw[GSKIM]=(mw[TSKIM]^_b)*exp(_c*mw[TSKIM]) ENDLOOP ; =================PERFORM TRIP DISTRIBUTION================= LOOP PURP=1,4 ; creates MW[1] to MW[4] PAF=0 MW[PURP] = A[PURP] * MW[PURP+20] ATTRSUM=ROWSUM(PURP) IF (ATTRSUM>0) PAF=P[PURP]/ATTRSUM MW[PURP]=PAF * MW[PURP] ENDLOOP ; ========GENERATE FREQUENCY REPORTS BASED ON TIME============ FREQUENCY VALUEMW=1 BASEMW=11, RANGE=1-140, TITLE='** HBW Income Class 1 Travel Time Frequency **' FREQUENCY VALUEMW=2 BASEMW=12, RANGE=1-140, TITLE='** HBW Income Class 2 Travel Time Frequency **' FREQUENCY VALUEMW=3 BASEMW=13, RANGE=1-140, TITLE='** HBW Income Class 3 Travel Time Frequency **' FREQUENCY VALUEMW=4 BASEMW=14, RANGE=1-140, TITLE='** HBW Income Class 4 Travel Time Frequency **' endrun
10
11
Generation Program
This chapter discusses the Generation program. Topics include: Introduction to Generation program Control statements Examples
11
Generation Program Introduction to Generation program
Introduction to Generation program

The Generation program processes zonal data according to specified expressions, and generates arrays of productions and attractions for up to twenty purposes. There are no default processes; it is your responsibility to specify what is to be accomplished. Usually, you use the Generation program to produce trip end data files (productions and attractions) for use in a trip distribution model. Generation is a direct application of Matrix. There are a few control statements and keywords in the Matrix control set that are not valid in a Generation application. It is the users responsibility to program the logic, computations, and output; very little is assumed by the program. However, the capability is nearly open-ended. There may be up to twenty trip purposes estimated in a single application. The program processes within an overall origin zone loop controlled by the variable named I. To make things a little more meaningful to some users, I may alternatively be referenced as Z. (A companion variable Z is set to I every time I is changed internally; I and Z can not be revised by the user). The Generation program has two processing phases and stacks: the normal stack (ILOOP) that begins with the first stack statement, and an optional ADJUST stack, which begins with the statements following the PHASE=ADJUST statement. The I loop processes only the normal stack statements; it does not proceed beyond the PHASE=ADJUST statement. The ADJUST stack is processed one time only -- after the I loop is completed. Its purpose is to provide capabilities to adjust and/or balance final production and attraction totals. Productions and attractions are to be computed for each zone; they are referred to as P and A, respectively. There may be up to twenty Ps and twenty As for each zone. The computed Ps and As are stored into arrays and must be referenced with array notation. The arrays are doubly dimensioned. Only the first index (purpose) is required; the second index (zone) is optional. The zonal index will be set to I if it is not specified. There is very little need to use a JLOOP, but if one is used, it is suggested that P and A references within the JLOOP
Generation Program Introduction to Generation program
11
contain both indices. Any attempt to use an invalid index will result in a fatal message. The lower limit for each index is 0; the upper limits are MAXPURPS and ZONES. P[1]=ZI.1.POP indicates that the productions for purpose 1 for the current I zone are to be obtained from the ZDATI[1] array named POP. A more detailed expression would be P[1][I] = ZI.1.POP[I], but such detail is not necessary. When the ILOOP phase is completed, the program fills in the [0] row and [0] columns for the P and A arrays; row and column 0 cells are set to the marginal values. The statements in the ADJUST stack can reference index [0] to obtain row and/or column totals. The COMP functions, PTOT(#) and ATOT(#) can also be used at any time to compute the totals for purpose #. There is a significant difference when referencing P and A in COMP statements in the ADJUST stack. In ILOOP, COMP P and A is processed for a single zone index (I); in ADJUST, a COMP P and A causes processing for all zones in that P or A. This is to simplify the final adjusting process. However, double indexing on the right side of the equal sign can set the process to compute for only that specific zone. It should be noted that IF/ENDIF, LOOP/ENDLOOP, and JLOOP/ENDJOOP blocks and any GOTOs may not span a PHASE. The program will treat such conditions as errors.
Example
A[1] = 1 ; sets only 1 cell P[1] = A[1] ; sets only 1 cell /* Adjustment Phase Set A[1] to total to P[1] total Move A[1] to P[1] (maybe NHB) fac = ptot(1) / atot(1) a[1]=fac * a[1] ; would be the same */ PHASE=ADJUST A[1] = P[1][0] / A[1][0] * A[1] P[1] = A[1]
The FILEO PAO keyword is used to write the computed P and A values to file records.
11
Generation Program Control statements
Control statements
Most of the standard Matrix program statements are valid in the Generation program, and a few additional ones are available. Since the Generation program is a subset of the Matrix program, it is assumed that the user is familiar with the Matrix control statement set. Only the differences between the Matrix and Generation control statements are included in this section. For descriptions of other control statements see Control statements on page 436. Matrix statements not allowed in Generation:
FREQUENCY PRINTROW RENUMBER
Matrix keywords not allowed in Generation:

FILEI MATI= FILEO MATO= COMP MW= PARAMETERS MAXMW= REPORT MARGINS= MARGINREC=
Generation statements not in Matrix:

PROCESS ... ENDPROCESS PHASE= BALANCE A2P= P2A= NHB=
Generation keywords not in Matrix:

FILEO PAO= COMP A= P= PARAMETERS MAXPURPS= REPORT PC= AC= P= A=
11
BALANCE
This statement is used to specify how the trip ends are to be adjusted in the Phase=Adjust process. P2A=list A2P=list NHB=list This statement makes the adjustment process much simpler. Typically, most users adjust the Attraction totals to match the Production Totals.
BALANCE keywords
Keyword A2P P2A NHB |IP| |IP| |IP| Description Specifies the purposes whose attraction totals are to be set to the production totals for that purpose. Specifies the purposes whose production totals are to be set to the attraction totals for that purpose. Specifies the purposes whose attraction totals are to be set to the production totals for that purpose, and then the productions are set equal to the attractions for each zone.
Example
BALANCE A2P=1,2,4-7 NHB=3
COMP
Computes a variable, P/A row, or P/A row element VAR=expression P/A[]=expression INCLUDE EXCLUDE The COMP statement is probably the most important of all the statements in the program. It is used to compute variable and P and A array values. The reader is advised to read Introduction to Generation program on page 564 for information concerning the differences in array computation within the ILOOP and ADJUST phases. The major difference between the Generation and Matrix programs for COMP statements is in the use of P/A[] and MW[]. First
11
of all, MW[] is not valid in the Generation program. Secondly, COMP P[]=, A[]=, and MW[]= expressions automatically imply a loop based upon J from 1 to zones in the Matrix program. While in the Generation program, when P[]= or A[]= is specified in the ILOOP phase, the J loops from I to I (a single iteration). Within the ADJUST phase, the J loops from 1 to zones. See COMP on page 460 for details of COMP statements. The COMP statement may contain INCLUDE and EXCLUDE to cause selective processing.
COMP keywords
Keyword A[n][I] |N| Description Causes the program to solve the expression for each value of J. The result is stored in A[n][I]. If the second [] is not specified, it will default to I. Causes the program to solve the expression for each value of J. The result is stored in P[n][I]. If the second [] is not specified, it will default to I.
P[n][I]
|N|
Expressions may contain the functions ATOT(#) and PTOT(#), which return the attraction and production totals for purpose #.
Example
COMP P[1]= ZI.1.P1 COMP A[2]=0.90*ahbo IF (I=38-49) P[1]=ZI.4.SPECIAL
FILEO
Generates trip-end records. PAO (FORM CFORM LIST PRINT DBF (NAMES)) The PAO keyword is used to request that a file containing trip end records be written at the end of all stack processing. There may be multiple PAO specifications; each one should reference a different file. They will be processed in the order in which they appear in the input stream. The flexibility of the statement can allow records to be written in almost any format that other software systems might
11
require. Within Cube Voyager, the most likely place where this data would be read would be in any program that accepts ZDATI files; usually it should be written in a format such that the Distribution process can read it as the distribution trip ends. Although other data can be placed on these records, normally, the records should contain only the zone number (I), and the various trip ends such as P[1], a[1], etc. For consistency, the PAO processing uses the Cube Voyager General PRINT control statement processor. The PRINT processor is called one time for each zone in a loop where Z=1-Zones. The major difference between PAO and PRINT statement is that PAO specifies the output file by definition, and the FILE keyword is not allowed. Full documentation about the sub-keywords can be found in PRINT on page 62. PAO can be optionally written as a DBF by setting DBF=T or to an MDB by designating the output MDB file name followed by a backslash and the element name.
FILEO keywords
Keyword PAO PAO CFORM Subkeyword |KF10| |S| Description Name of a file where the formatted records are to be written. Format for following string list items. Normally, text variables will not be written to a PAO file. Indicates if the output records are to written as a DBF file. This is off, unless turned on. If DBF=T is specified, the user may optionally name the variables to be written to the DBF records with the NAMES subkeyword. A maximum of 100 variables may be designated for single DBF. If the PAO keyword specifies an MDB file for the output, then DBF subkeyword should either not be specified or set to T. If DBF=F and PAO specifies an MDB file the program will fail.
PAO
DBF
|?|
11

Keyword PAO Subkeyword FORM |S| Description Format for following numerical list items. FORM=20.2SLR is recommended if the Distribution program is going to read the file. List of items to be formatted into the output buffer. P and A must be indexed; the zone index is automatically supplied as Z. In most cases, the only variables in the list will be Z, and expressions of P[n] and A[n] values. If any expressions are used, they should be enclosed within parenthesis, and should not contain any spaces or commas. Names to be assigned to the DBF variables. The names are positional (their indices refer to the positional location of the variables in the LIST). For example:
LIST=z,p1,p2,p3,a1,a2,a3, DBF=T,NAMES=TAZ, WORKPROD, OTHERPROD,NHBPROD
PAO
LIST
|S|
PAO
NAMES
|S|
would set the names in the DBF for z,p1,p2,p3, respectively. Likewise:
NAMES[5]=WORKATTR, OTHERATTR, NHBATTR
would set the names for a1,a2,a3. A name may not exceed 10 characters; it will be truncated, if designated as longer than 10. The routine does not check for duplicate names. Extraneous NAMES (that is, NAMES[11] in this example), are ignored. If there is no name specified for a variable, the program will use the variable name directly. If the LIST field is an expression, the program will use the first 10 alphanumeric digits, ignoring other characters. For example (VAR1+VAR2+VAR3) will be named VAR1VAR2VA.
11

Keyword PAO Subkeyword PRINT |?| Description Indicates if the output records are to also be listed to the standard output. This is off, unless turned on.
Example
PAO = OUTPUT.DAT, FORM=8.0, LIST = Z(2) P[1] P[2] P[3] P[4] P[5] A[1] A[2] A[3] A[4] A[5] PRINT=N PAO[2] = OUTPUT2.DAT, FORM=SL, Z P[1] A[1] P[2] A[2] (P[3]+P[4]) (A[3]+A[4])
PARAMETERS
Set general parameters. ZONES MAXPURPS
PARAMETERS keywords
Keyword ZONES |I| Description Establishes the number of zones to process. If ZONES is not specified, and the program has no other way to identify the appropriate number of zones, it will be set to 100. Sets the number of P and A arrays to be allocated, and establishes an index boundary for P and A in COMP statements. The maximum value is 20, which the program defaults to, if the keyword is not specified. Setting this to a more realistic value will cause a less drain on computer memory.
MAXPURPS
|I|
Example
ZONES=3000 MAXPURPS=5

Establishes phase blocks. PHASE ENDPHASE
11
A user process phase stack is defined by a PROCESS statement that designates its beginning and an ENDPROCESS statement that designates its ending. To simplify coding, the PROCESS control word is not necessary; PHASE=name may be used directly. And, to further simplify coding, the ENDPROCESS statement is not necessary; the occurrence of another PROCESS statement acts as the ENDPROCESS statement. If ENDPROCESS is used, it may be coded as either ENDPROCESS or ENDPHASE. In the Generation program, normally, only the PHASE=ADJUST statement is all that is needed to differentiate between the normal ILOOP statements and the ADJUST statements that are used to balance the final Ps and As.
PROCESS keywords
Keyword PHASE |KS| Description Names the phase stack. The control statements that follow it, until an ENDPROCESS statement or another PROCESS statement is encountered, will be executed when the phase is internally executed. Exception: Static statements, such as PARAMETERS, FILEI, FILEO, LOOKUP, are not processed as stack statements, even if they are located within a phase block. The following PHASE names may be specified: ENDPHASE |K| ILOOP ADJUST
Defines the end of the user control statements for a stack.
Example
RUN PGM=GENERATION . P[1]=. . . PHASE=ADJUST ; the following statements are used to balance Ps and As RUN PGM=GENERATION . PHASE=ILOOP P[1]=. . PHASE=ADJUST ; the following statements are used to balance Ps and As
11
REPORT
Requests reports and establishes tracing. A P AC PC TRACE
REPORT keywords
Keyword AC A PC P TRACE |?| |?| |?| |?| |K?| Description Requests that the computed attractions be reported. This report precedes ADJUST processing. Requests that the final attractions be reported. This report follows any ADJUST processing. Requests that the computed productions be reported. This report precedes ADJUST processing. Requests that the final productions be reported. This report follows any ADJUST processing. Controls the listing of the stack statements as they are processed.
Example
REPORT AC=y A=y P=y
11
Generation Program Examples
Examples
This section contains examples of the Generation program: Generation example 1 Generation example 2
Generation example 1
RUN PGM=GENERATION ID=DEMO TRIP GENERATION pagewidth=80 zones=19 zdati[1]=c:\demo\demo08.dat,z=#2,select=1-1, hh1=#3,hh2=#4,hh3=#5,hh4=#6,hh5=#7,hh6=#8,hh7=#9, hh8=10,hh9=11,hh10=12,hh11=#13,hh12=#14,hh13=#15 zdati[2]=c:\demo\demo08.dat,z=#2, select=2-1, emp1=3,emp2=4 zdati[3]=c:\demo\demo08.dat,z=2-4,select=3-1, p3a=21-25,p4a=31-35 zdati[4]=c:\demo\demo08.dat,z=2-4,select=4-1, xicnt=6-10,ixcnt=11-15 report zdat=y tothh = zi.1.hh1 + zi.1.hh2 + zi.1.hh3 + zi.1.hh4 + zi.1.hh5 + zi.1.hh6 + zi.1.hh7 + zi.1.hh8 + zi.1.hh9 + zi.1.hh10 + zi.1.hh11 + zi.1.hh12 + zi.1.hh13 totemp = zi.2.emp1 + zi.2.emp2 phbw = .21 * 4.5 * zi.1.hh1 + .21 * 6.8 * zi.1.hh2 + .18 * 8.4 * zi.1.hh3 + .18 * 10.2 * zi.1.hh4 + .18 * 11.9 * zi.1.hh5 + .16 * 13.2 * zi.1.hh6 + .16 * 14.4 * zi.1.hh7 + .16 * 15.1 * zi.1.hh8 + .15 * 16.4 * zi.1.hh9 + .14 * 17.7 * zi.1.hh10 + .13 * 18.0 * zi.1.hh11 + .13 * 19.0 * zi.1.hh12 + .13 * 19.2 * zi.1.hh13 phbo = .57 * 4.5 * zi.1.hh1 + .57 * 6.8 * zi.1.hh2 + .57 * 8.4 * zi.1.hh3 + .59 * 10.2 * zi.1.hh4 + .59 * 11.9 * zi.1.hh5 + .61 * 13.2 * zi.1.hh6 + .61 * 14.4 * zi.1.hh7 + .68 * 15.1 * zi.1.hh8 + .62 * 16.4 * zi.1.hh9 + .62 * 17.7 * zi.1.hh10 + .62 * 18.0 * zi.1.hh11 + .62 * 19.0 * zi.1.hh12 + .62 * 19.2 * zi.1.hh13 pnhb = .22 * 4.5 * zi.1.hh1 + .22 * 6.8 * zi.1.hh2 + .22 * 8.4 * zi.1.hh3 + .23 * 10.2 * zi.1.hh4 + .23 * 11.9 * zi.1.hh5 + .23 * 13.2 * zi.1.hh6 + .23 * 14.4 * zi.1.hh7 + .23 * 15.1 * zi.1.hh8 + .23 * 16.4 * zi.1.hh9 + .24 * 17.7 * zi.1.hh10 +
11
.25 * 18.0 * zi.1.hh11 + .25 * 19.0 * zi.1.hh12 + .25 * 19.2 * zi.1.hh13 pix = 0.03 * 1.03 * (phbw+phbo+pnhb) pxi = zi.4.xicnt ahbw = 1.81 * ( 1.7 * totemp) ahbo = 1.90 * (10.0 * zi.2.emp1 + 0.5 * zi.2.emp2 + tothh) anhb = 1.49 * ( 2.0 * zi.2.emp1 + 2.5 * zi.2.emp2 + 0.5*tothh) axi = 0.08*ahbw + 0.10*ahbo + 0.03*anhb aix = zi.4.ixcnt p[1]=phbw, p[2]=phbo, p[3]=pnhb, p[4]=pix, p[5]=pxi a[1]=0.92*ahbw a[2]=0.90*ahbo a[3]=0.97*anhb a[4]=aix, a[5]=axi phase=adjust a[1] = p[1][0] / a[1][0] * a[1] a[2] = p[2][0] / a[2][0] * a[2] a[3] = p[3][0] / a[3][0] * a[3] p[3] = a[3] a[4] = p[4][0] / a[4][0] * a[4] p[5] = a[5][0] / p[5][0] * p[5] pao=out.dat,form=8.0 list=z(2),p[1],p[2],p[3],p[4],p[5],a[1],a[2],a[3],a[4],a[5] ENDRUN
Generation example 2
RUN PGM=GENERATION FILEI ZDATI[1]=zonedata.dbf ; dbf data structure is Z, V1, V2,...., V254 FILEI ZDATI[2]=zonedata.dbf ; External PA file. dbf data structure is Z, ; Xprod1,Xprod2,Xprod3,Xattr1,Xattr2,Xattr3 for example ; These fields could also be fields on your zone data file ; ZDATI[1] as well. FILEO PAO[1] = "TRIPENDS.DBF", FORM=6.0, DBF=T, LIST=Z, P[1] P[2] P[3] A[1] A[2] A[3] ; lets say system has 1000 zones with 901-1000 being the externals ; and we have 3 trip purposes PARAMETERS ZONES=1000 PROCESS PHASE=ILOOP ; define trip rates by purposes ; purpose = home based hbp_p = 0.2 ; production trip rate per person (population) per day hbp_ia = 0.5 ; production trip rate per industry/agricultural worker per day hbp_s = 0.6 ; production trip rate per service worker per day
11
hbp_r = 40.0 ; production trip rate per retail worker per day (incl shoppers) hbp_sc = 0.1 ; production trip rate per pupil/student per day hba_p = 1.8 ; attraction trip rate per person (population) per day hba_ia = 0.6 ; attraction trip rate per industry/agricultural worker day hba_s = 0.6 ; attraction trip rate per service worker per day hba_r = 45.0 ; attraction trip rate per retail worker per day (incl shoppers) hba_sc = 0.1 ; attraction trip rate per pupil/student per day ; purpose = non-home based nhbp_p = 1.5 ; production trip rate per person (population) per day nhbp_ia = 0.3 ; production trip rate per industry/agricultural worker day nhbp_s = 0.25 ; production trip rate per service worker per day nhbp_r = 12 ; production trip rate per retail worker per day (incl shoppers) nhbp_sc = 0.1 ; production trip rate per pupil/student per day nhba_p = 1.3 ; attraction trip rate per person (population) per day nhba_ia = 0.3 ; attraction trip rate per industry/agricultural worker day nhba_s = 0.3 ; attraction trip rate per service worker per day nhba_r = 14.0 ; attraction trip rate per retail worker per day (incl shoppers) nhba_sc = 0.1 ; attraction trip rate per pupil/student per day ; purpose = school schp_p = 0.15 ; production trip rate per person (population) per day schp_ia = 0 ; production trip rate per industry/agricultural worker day schp_s = 0.005 ; production trip rate per service worker per day schp_r = 0.005 ; production trip rate per retail worker per day schp_sc = 0.95 ; production trip rate per pupil/student per day scha_p = 0.15 ; attraction trip rate per person (population) per day scha_ia = 0 ; attraction trip rate per industry/agricultural worker day scha_s = 0.005 ; attraction trip rate per service worker per day scha_r = 0.005 ; attraction trip rate per retail worker per day scha_sc = 0.95 ; attraction trip rate per pupil/student per day IF (I<=900) ; define P/A functions for internal zones ; ----- calculate productions per day by purpose ; zi.1.vnames are just the filed names in the dbf file P[1] = (hbp_p*zi.1.pop_2002 + hbp_ia*zi.1.inag_2002 + hbp_s*zi.1.serv_2002 + hbp_r*zi.1.ret_2002 + hbp_sc*zi.1.sch_2002) P[2] = (nhbp_p*zi.1.pop_2002+ nhbp_ia*zi.1.inag_2002+ nhbp_s*zi.1.serv_2002+
per
per
per
per
per
11
nhbp_r*zi.1.ret_2002+ nhbp_sc*zi.1.sch_2002) P[3] = (schp_p*zi.1.pop_2002+ schp_ia*zi.1.inag_2002+ schp_s*zi.1.serv_2002+ schp_r*zi.1.ret_2002+ schp_sc*zi.1.sch_2002) ; ----- calculate attractions per day by purpose ; zi.1.vnames are just the filed names in the dbf file A[1] = (hba_p*zi.1.pop_2002 + hba_ia*zi.1.inag_2002 + hba_s*zi.1.serv_2002 + hba_r*zi.1.ret_2002 + hba_sc*zi.1.sch_2002) A[2] = (nhba_p*zi.1.pop_2002+ nhba_ia*zi.1.inag_2002+ nhba_s*zi.1.serv_2002+ nhba_r*zi.1.ret_2002+ nhba_sc*zi.1.sch_2002) A[3] = (scha_p*zi.1.pop_2002+ scha_ia*zi.1.inag_2002+ scha_s*zi.1.serv_2002+ scha_r*zi.1.ret_2002+ scha_sc*zi.1.sch_2002) ELSE ; define P/A for external zones P[1]=zi.2.Xprod1 P[2]=zi.2.Xprod2 P[3]=zi.2.Xprod3 A[1]=zi.2.Xattr1 A[2]=zi.2.Xattr2 A[3]=zi.2.Xattr3 ENDIF PROCESS PHASE=ADJUST ; adjust zonal attractions so total attractions match total productions BALANCE A2P=1,3 NHB=2 ; balance attrs to prods for purposes 1, 3 ; prods set to attrs for purpose 2 ENDPHASE ENDRUN
11
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
12
Public Transport Program Overview
Overview
The Public Transport program is the Cube Voyager program that lets you prepare public transport data and model public transport systems. This section provides an overview of the Public Transport program, listing the programs primary capabilities, required inputs and generated outputs, and discussing how you can use the program to prepare data and model public transport systems. This section also discusses terminology used within this document. Topics include: Summary of facts Preparing data Modeling Terminology
Summary of facts
The Public Transport program offers: User control over all aspects of the Public Transport model True multirouting between zone pairs, or alternatively single best-path routes may be used Demand stratification by user class with variations in the behavior of classes represented by different cost functions Comprehensive fares modeling Preparation of a public transport network for Public Transports modeling functionality Generation of the nontransit element of the public transport network (that is, access, egress, transfer and park and ride legs) Skimming, network-wide and mode specific, composite and average travel costs, and components of costs
12
Two methods (service-frequency and service-frequency-andcost) for loading demand on to transit choices at stops Analyses of loaded tripstransfers between modes, operators, lines, a variety of stop-to-stop movements, select-link/line outputs Reporting of input data, model infrastructure, multiple routes with probability of use, line and link loads, secondary analyses
The Public Transport program requires as input: A highway or public transport network Public transport system data Line data Fare data Nontransit legs (developed externally or by Public Transport) Generalized cost information Demand
The Public Transport program produces: Nontransit legs Enumerated routes Skim and select-link matrices Loaded lines and nontransit legs Transfer matricesresults of loading analyses A variety of reports of input data and model results A public transport network that can be displayed by Cube and used as an input network for further modeling
12
Preparing data
You can use the Public Transport program to prepare data that supports public transport modeling. You can prepare: A network, produced by Network or Public Transport, containing characteristics of zones, nodes and links (that is, node coordinates, walk and transit link times, distance, and so forth), over which the public transport system operates. System information used to describe the characteristics of the public transport system such as modes, operators and wait curves. Service or line data, defining the characteristics of the lines and nodes traversed. Nontransit legs, presenting opportunities to access the public transport system, egress from it and transfer between services during the course of a trip. Nontransit legs may be determined externally and/or generated by Public Transport under user control. Control information for route enumeration and evaluation.
Modeling
You can use the Public Transport program to model public transport. The model has several parts: Route enumeration and evaluation Skimming (levels of service matrices) Loading (assignment) Reporting
Route enumeration and evaluation

During route enumeration and evaluation, the Public Transport model finds reasonable or attractive multiple discrete routes between zones, considering:
12
Number of transfers Spread the margin of cost over the minimum cost route Nontransit and in-vehicle costs Boarding and transfer penalties by mode Waiting time, derived from the combined frequency of services at stop nodes Fares (considered only for evaluation)
Skimming (levels of service matrices)

During skimming, the Public Transport model skims (extracts) the costsand the components of costsof journeys between zones. These costs are suitable for model validation, demand modeling, scheme evaluation, loading demand on the network and producing operational statistics like passenger miles, hours and revenue. The model can extract the following skims: Composite costs Value of choice Average, perceived, and actual trip costs and components (that is, nontransit, in-vehicle and wait times, boarding and transfer penalties, fares) Best trip cost
The model can extract network-wide trip costs, or the model can stratify them, where appropriate, by modes.
Loading (assignment)
During loading, the Public Transport model loads demand, in the form of trips between zone pairs. The model uses a series of models at the different decision points in a trip: The walk-choice model allocates trips between attractive choices at access, egress, and transfer points. Where walk and transit choices are available, it also determines the transit share.
12
The service-frequency or the service-frequency-and-cost model allocates the transit share at a stop between the attractive services available at that stop. The alternative-alighting model apportions the share of a service to the attractive alternative alighting points of that service.
(Strictly, these models determine the probability of use of the alternative routes; trips are then loaded on the routes based upon these probabilities.) Two forms of loading are supported, multirouting and best-path. The best-path method does not use walk or alighting choice models, and loads demand using the service-frequency model.
Reporting
During reporting, the Public Transport model produces reports you can use to analyze different aspects of passenger loadings: Passenger transfers between all modes Passenger transfers between public transport modes Passenger transfers between operators A variety of stop-to-stop movements
Terminology
This document uses the following sets of terms interchangeably: transit and public transport. In particular, transit is used in this document to describe a type of link over which a public transport service can run, namely transit link as opposed to nontransit link. lines and services transfers and interchanges skims and levels of service
12
generalized cost and generalized time origin-destination pairs, zone pairs, OD pairs, and IJ pairs nontransit time and walk time loading and assignment volume, load, flow, and passenger flow
12
Public Transport Program Processes
Processes
The Public Transport program performs the following processes: Network development Route enumeration Route evaluation Skimming (level of service) Loading Select link Loading analyses Crowd modeling
Some processes have associated phases which allow you to augment the task with additional context-sensitive computations.
12
You control the main processes and their associated phases, within a prescribed hierarchy.
Public Transport program processes and associated phases
(With multiple user classes, processes in the blue boxes are performed separately for each class.) See Phases on page 620 for a description of the phases in the Public Transport program. You configure the Public Transport program to run through a specific combination of control statements and phases. Control statements are either static or dynamic. Static statements may be present anywhere in the job stream; the program evaluates them once. Dynamic statements may be present only within phases; the program evaluates them as encountered, during the execution of the phases.
12
Only context-sensitive dynamic control statements are available to the phases; the description of each phase lists valid control statements (see Phases on page 620). Only code phases that contain control statements; do not code empty phases.
Network development
During network development, the Public Transport program: Reads in the input network from FILEI NETI Processes public transport system data in FILEI SYSTEMI Processes the LINE control statements in FILEI LINEI Processes the FACTORS control statements in FILEI FACTORI Processes the PARAMETERS control statements in the script file Generates and/or reads nontransit legs with the GENERATE statements Develops a comprehensive public transport network from the basic network, public transport system data, lines, nontransit leg, and control information. This includes stringent validation and consistency checks to ensure that the different components of the public transport network are compatible.
The DATAPREP phase is mandatory for public transport network development. The phase provides the control statements for nontransit leg generation and/or input. Either the Network program or the Public Transport program can produce the input network. However, only zone, node, and link information are taken from networks produce by the Network program; you must provide public transport system, line, and control data.
12
The components of the public transport network are common to all user classes, except for route-enumeration and route-evaluation control information, which may be provided separately for each class. See Public transport network development on page 849 for examples of this task.
Inputs required for Public Transport network development
A network, produced by Network or Public Transport, input with NETI Public transport system data, input with SYSTEMI One or more lines files, input with LINEI[#] Control information for route enumeration and route evaluation, input with FACTORI (For multiple user classes: control information input with FACTORI[#]) Global parameters input with the PARAMETERS statement One or more GENERATE statements and, optionally, nontransit legs input with NTLEGI[#]
Outputs produced by Public Transport network development

A public transport network, which may be saved with NETO. A table of links and their attributes, in DBF format, which may be saved with LINKO. Nontransit legs (generated and input), which may be saved with NTLEGO. The legs are in the format specified by the NT control statement. A text version of the lines in the public transport system, which may be saved with LINEO. The lines are in the format specified by the LINE control statement.
The Public Transport network is made available to any other processes in the job stream that require it. If trips are loaded in the run creating the public transport network, all output files can optionally contain the results of the loading. The saved Public Transport network may be used in subsequent runs of the Public Transport program for route enumeration, route evaluation, skimming, loading and loading analyses. It contains all
12
information required for these processes apart from fares data which may optionally be read later, so allowing it to vary between program runs. You can use Cube to display but not edit the Public Transport network.
Associated phases
DATAPREP (mandatory)
Route enumeration
During route enumeration, the Public Transport program identifies sets of discrete routes between zone pairs, which have some probability of being used by passengers to travel between the zones. Route enumeration is a heuristic process, which you control with the FACTORS statement. This set of discrete routes may be pruned at the route-evaluation stage, in compliance with further user specified controls. A ROUTEO file in the job stream invokes route enumeration. You can save an enumerated routes file and input the file to a subsequent run with ROUTEI. When modeling multiple user classes, provide separate FACTORS statements for each class to produce enumerated route files for each class. By default, Public Transport enumerates routes for all zone pairs. However, you can use ROUTEI and ROUTEO statements to select zone pairs separately for route enumeration and reporting.
12
See Route-enumeration process on page 793 for theory about route enumeration.
Inputs required for Public Transport route enumeration
A public transport network file, produced either by the current run of the Public Transport program, or produced previously and input with NETI.
Outputs produced by Public Transport route enumeration

An enumerated routes file, ROUTEO. For multiple user classes, enumerated routes files, ROUTEO[#].
NOTE: Vast quantities of data can be required to define a public
transport system. To improve performance of the main algorithms and minimize memory and temporary disk storage, the data is organized in a highly compressed form for processing and storing routes. The line data is converted into transit legs and the network data into nontransit legs. The simplified network, which is described in Network simplification on page 782, can be examined through a series of reports specified on the REREPORT statement.
Associated phases
None
Route evaluation
During route evaluation, the Public Transport program: Examines enumerated routes Eliminates any illogical ones that have crept in due to network simplification Disaggregates bundled routes, where appropriate Identifies routes that have, at the minimum, a user specified probability of use or more, at every decision point along the route
12
The route-evaluation process is a prerequisite for the skimming, select-link, loading, and loading-analyses processes. Selecting one or more of these processes automatically invokes the routeevaluation process. This is because only enumerated routes are saved; they are evaluated as required. (Enumerated routes produced by an earlier run may be input with ROUTEI for evaluation or generated by specifying a filename with ROUTEO.) Evaluated routes may be reported with ROUTEI and ROUTEO. See Route-evaluation process on page 799 for the theory supporting route evaluation.
Inputs required for Public Transport route evaluation
A public transport network file, produced either by the current run of the Public Transport program, or produced previously and input with NETI. A route file, produced either by the current run of the Public Transport program, or produced previously and input with ROUTEI. (For multiple user classes, enumerated routes files input with ROUTEI[#]). Fares data may be read directly into a route-evaluation run.
NOTE: Any previously built NETI and ROUTEI files that you input
must be compatible.
Outputs produced by Public Transport route evaluation1
One or more sets of attractive or reasonable route bundles Their probabilities of use The cost of using the routes 1. Produced for each zone pair. Can be reported by zone pair, but not saved.
The skimming, select-link, loading, and loading-analyses processes are performed on the fly. Indeed, these are by-products of the route-evaluation process, but described separately, as they report on different aspects of the Public Transport model.
12
Associated phases
MATI SELECTIJ
Skimming (level of service)

This section describes skimming in detail; see Skimming Quick reference on page 604 for a quick reference to the skimming functions. The skimming process produces skim (level of service) matrices of total trip costs and their components, from the information generated by route evaluation. When modeling multiple user classes, you can produce skims for each class from the individual enumerated route files. Skimming is also described in Skimming process on page 812. See Public transport skimming on page 854 for examples of this process.
NOTE: All skim matrices have their intrazonal cells on the diagonal,
and the cells for unconnected IJ pairs, set to zero. These can be reset to large values, either in the MATO phase or outside the Public Transport program, for modeling demand. Topics in this section include: Overview Wait-time skim functions Travel-time skim functions Penalty skim functions Fare skim functions Other skim functions
12
Overview
Inputs required for Public Transport skimming
A public transport network file, either produced by the current run of the Public Transport program, or produced previously and input with NETI. A route file, produced either by the current run of the Public Transport program, or produced previously and input with ROUTEI (for multiple user classes, enumerated routes files input with ROUTEI[#]).
NOTE: If previously built files are input with NETI and ROUTEI, the
files must be compatible.

Outputs produced by Public Transport skimming
A matrix file, MATO (for multiple user classes, matrix files, MATO[#]). A table of links and their attributes, in DBF format, which may be saved in the file designated by LINKO.
Associated phases
SKIMIJ (mandatory) MATO
Skimming functions
Skims can be produced for all O-D pairs or a selection and are extracted through a series of functions or predefined processes. A skim function is accessed once for each zone pair and returns a numeric value which would generally be saved in a row of a working matrix. Each skim function has a name and one, two or no arguments, and is specified as follows: SkimName(Arg1) SkimName(Arg1, Arg2) SkimName
where:
12
SkimName includes an explicit prefix, or a default, that denotes its type: COMP for composite skims CWD for crowded skims BEST for best skims All other skims are average skims
Arg1 is the route set number and can range from 0 to the number of route sets. If Arg1=0, the attribute skimmed is the total for the zone pair; if Arg1>0, the extracted skim is for the specified route set.
Example 1: Shows how skims requiring one argument are
invoked.
MW[2]=COMPCOST(0) MW[3]=ValOfChoice(0) MW[4]=IWAITA(0)
Currently only one route set is produced. Therefore, setting Arg1 to zero or one will produce the same result, the skim for the route set which is also the overall skim for the OD pair (route set). Arg2 is a list of modes for which the skim is required. For example, Arg2= 3 would provide a skim for mode 3 while Arg2=1,2,3,4,5 would produce one skim for modes 1 through 5. This could also be written as 1,-5. Note that range specification for skim functions is different from the standard specification for Cube Voyager. The arguments in skim functions are evaluated as expressions. So, the standard way of specifying ranges, Arg2=1-5 would result in Arg2=-4. Combinations such as 1,3,-5,7,9,-12 are valid.
Example 2: Shows how skim functions requiring two arguments are invoked. The second argument is a single number or a list of single numbers and pairs specifying ranges. MW[7] will contain a DIST skim for mode 1, MW[8] will contain a TIMEA skim for
12
modes 1,7,8,9,11,31,32,and 33, MW[9] for modes 1,7,8,9,11 which happen to be the transit modes in the system and MW[10] for modes 31,32,33 which are nontransit modes.
MW[7] = DIST(0,1) MW[8] = TIMEA(0,1,7,-9,11,31,-33) MW[9] = TIMEA(0,1,7,-9,11) MW[10] = TIMEA(0,31,-33)
If skims are required for all, transit or nontransit modes, an alternative way to specify Arg2 is ALLMODES, TMODES or NTMODES (case insensitive).
Example 3: Shows an alternative method for invoking skim functions requiring two arguments. Here, Arg2 is text rather than a list; MW[8] will contain a TIMEA skim for all modes, MW[9] for transit modes and MW[10] for nontransit modes.
MW[11] = TIMEP(0,ALLMODES) MW[12] = TIMEP(0,TMODES) MW[13] = TIMEP(0,NTMODES)
Where a skim requires no arguments, the parenthesis () should not be coded.

Example 4: Shows how a skim function requiring no arguments
is invoked.
MW[14] = BESTJRNY
Subsequent sections describe the types of skims that can be extracted and their contents.
Wait-time skim functions

This section describes wait-time skim functions: Actual crowding wait time Actual initial wait time Actual transfer wait time Perceived crowding wait time Perceived initial wait time
12
Perceived transfer wait time
Actual crowding wait time

CWDWAITA(RouteSet)
Computes the average additional wait time due to crowding effects incurred at the transfer points of all attractive routes between zones. The additional wait time occurs when unable to board a service (so needing to wait for the next one) and at the end of modeled period (where demand exceeds capacity causing a bottleneck).
Actual initial wait time
IWAITA(RouteSet)
Computes the average actual wait time incurred at the start of the trip for all attractive routes between zones. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement, assigned to nodes by IWAITCURVE keyword, or, for nodes that have not been assigned one, from a default wait curve.
Actual transfer wait time
XWAITA(RouteSet)
Computes the average actual wait time incurred at the transfer points of all attractive routes between zones. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement, assigned to nodes by the XWAITCURVE keyword, or, for nodes that have not been assigned one, from a default wait curve.
Perceived crowding wait time
CWDWAITP(RouteSet)
Computes the average additional wait time due to crowding effects incurred at the transfer points of all attractive routes between zones, weighted by the WAITFACTOR keyword.
12
The additional wait time occurs when unable to board a service (so needing to wait for the next one) and at the end of modeled period (where demand exceeds capacity causing a bottleneck).
Perceived initial wait time
IWAITP(RouteSet)
Computes the average actual time incurred at the start of the trip for all attractive routes between zones, weighted by WAITFACTOR. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement, assigned to nodes by IWAITCURVE, or, for nodes that have not been assigned one, from a default wait curve.
Perceived transfer wait time
XWAITP(RouteSet)
Computes the average actual time incurred at the transfer points of all attractive routes between zones, weighted by WAITFACTOR. It is calculated either from one or more wait curves supplied by the WAITCRVDEF control statement, assigned to nodes by XWAITCURVE, or, for nodes that have not been assigned one, from a default wait curve.
Travel-time skim functions

This section describes travel-time skim functions: Actual travel time Perceived crowded link travel time Perceived travel time
Actual travel time

TIMEA(RouteSet, Mode)
For transit modes, this skim computes the average in-vehicle run time for all attractive routes between zones. It is taken from the network link data, factored by any line specific factors.
12
For nontransit modes, this skim computes the average nontransit time (access, egress and transfer) for all attractive routes between zones. It is taken from the nontransit legs generated or read in by the GENERATE statements.
Perceived crowded link travel time
CWDCOSTP(RouteSet, Mode)
For transit modes, this skim extracts the average additional invehicle run time for all attractive routes between zones. This is the run time that is above the basic calculated in-vehicle time and arises due to crowding effects and crowd factors greater than 1.0. As a perceived data skim, it is taken from the network link data and factored by any line specific factors, and RUNFACTOR. This component of cost is included in the perceived travel time skim, TIMEP, so care should be taken to avoid double-counting.
Perceived travel time
TIMEP(RouteSet, Mode)
For transit modes, this skim extracts the average in-vehicle run time for all attractive routes between zones. It is taken from the network link data and factored by any line specific factors, RUNFACTOR and crowding factor. For nontransit modes, this skim extracts the average nontransit time (access, egress and transfer) for all attractive routes between zones. It is taken from the nontransit legs generated or read in by the GENERATE statements and factored by RUNFACTOR.
Penalty skim functions

This section describes penalty skim functions: Actual transfer penalty Perceived boarding penalty Perceived transfer penalty
12
Actual transfer penalty

XFERPENA(RouteSet, Mode)
Extracts the average actual transfer penalty for all attractive routes between zones. It is taken from XFERPEN.
Perceived boarding penalty
BRDPEN(RouteSet, Mode)
Counts the boarding penalties associated with transit legs of the trip.
Perceived transfer penalty
XFERPENP(RouteSet, Mode)
This skim is the average perceived transfer penalty for all attractive routes between zones. It is the actual penalty as coded in XFERPEN, weighted by XFERFACTOR with XFERCONST added.
Fare skim functions

This section describes fare skim functions: Monetary units Generalized cost units
Monetary units
FAREA(RouteSet, Mode)
Extracts the average fare, in monetary units, for all attractive routes between zones. It is calculated from the fare systems used by the attractive routes. Fares are calculated either by transit leg or for a sequence of legs; in the latter case the fare is apportioned to the legs in proportion to leg distance.
Generalized cost units
FAREP(RouteSet, Mode)
12
Extracts is the average fare, in generalized cost units, for all attractive routes between zones. The fare is calculated as for skim FAREA, from the fare systems used by the attractive routes, and converted into generalized cost units with mode specific VALUEOFTIME. Fares are calculated either by transit leg or for a sequence of legs; in the latter case the fare is apportioned to the legs in proportion to leg distance.
Other skim functions

This section describes other available skim functions: Best trip time Boardings Composite cost Distance Excess demand Excess demand as a proportion Value of choice
Best trip time

BESTJRNY
Extracts the best actual trip time for zone pairs (that is, at each decision point, the best choice is taken). The trip time comprises: Walk time taken from input or generated nontransit legs Average wait time actual In-vehicle time actual Boarding penalties
12
Transfer penalties actual
NOTE: The route followed by this best actual trip may differ from that found using BESTPATHONLY as the latter route is selected on
cheapest perceived travel cost.

Boardings
BRDINGS(RouteSet, Mode)
Extracts the average number of boardings used by the attractive routes between zone pairs.
Composite cost
COMPCOST(RouteSet)
Measures the perceived costs of travelling between zone pairs using all attractive routes. It takes into account all choices available at decision points (for example, walk or alighting), and is appropriate for use in demand modeling and the evaluation of schemes. It comprises: Walk time Wait time (including any crowding wait time) Boarding time Transfer time In-vehicle time (including any link-crowding effects)
Distance
DIST(RouteSet, Mode)
Extracts the average distance travelled by the attractive routes between zone pairs. It is taken directly from the network link data.
12
Excess demand
EXCESSDEMAND
Extracts the number of trips (from the demand matrix) which are unable to readily reach their destination due to bottleneck points in the network where demand exceeds capacity, and no viable alternative route is available. It is only available when crowd modeling is performed, and wait time adjustments are used. It highlights where the public transport system is unable to satisfy the demand flows which are being loaded.
Excess demand as a proportion
EXCESSPROP
Extracts the proportion of trips for each origin-destination pair which are unable to readily reach their destination due to bottleneck points in the network where demand exceeds capacity, and no viable alternative route is available. These trips would need to wait till beyond the modeled period before being able to board their next transit leg. This skim is only available when crowd modeling is performed, and wait time adjustments are used. The EXCESSDEMAND skim only gives cell values where demand exists and bottlenecks prevent it reaching the destination. The EXCESSPROP skim highlights movements where the public transport system could well have difficulty in meeting demand (whether or not any demand exists in the loaded matrices).
Value of choice
ValOfChoice(RouteSet)
Indicates level of choice available in the public transport system by computing average travel cost skim minus the composite travel cost skim.
12
Sample calculation: ValOfChoice(0) = ((IWAITP(0)+ XWAITP(0)+ TIMEP(0, ALLMODES)+ BRDPEN(0, ALLMODES)+ XFERPENP(0, ALLMODES))COMPCOST(0) Expression contains additional terms when modeling fares or crowds.
Skimming Quick reference

This section provides a quick reference to the different types of skims or levels-of-service matrices that can be extracted from the attractive routes between zones. See Skimming (level of service) on page 593 for a detailed description.
Summary of skim functions
Function BESTJRNY BRDINGS(RouteSet, Mode) BRDPEN(RouteSet, Mode) COMPCOST(RouteSet) CWDCOSTP(RouteSet) CWDWAITA(RouteSet) CWDWAITP(RouteSet) DIST(RouteSet, Mode) EXCESSDEMAND EXCESSPROP FAREA(RouteSet, Mode) FAREP(RouteSet, Mode) IWAITA(RouteSet) IWAITP(RouteSet) Description Skims best trip times Skims number of boardings Skims boarding penalty (perceived) Skims composite costs Skims crowding link travel times (perceived) Skims crowding wait times (actual) Skims crowding wait times (perceived) Skims distance Skims excess demand (where demand exceeds capacity in crowding model) Skims excess proportion (where demand exceeds capacity in crowding model) Skims fares in monetary units Skims fares in generalized time units Skims initial wait times (actual) Skims initial wait times (perceived)
12
Summary of skim functions (continued)

Function TIMEA(RouteSet, Mode) TIMEP(RouteSet, Mode) ValOfChoice(RouteSet) XFERPENA(RouteSet, Mode) XFERPENP(RouteSet, Mode) XWAITA(RouteSet) XWAITP(RouteSet) Description Skims travel time (actual) Skims travel time (perceived) Skims value of choice Skims transfer penalty (actual) Skims transfer penalty (perceived) Skims transfer wait times (actual) Skims transfer times (perceived)
Loading
During the loading process, the Public Transport program assigns passenger demand, in the form of trips, to the attractive routes between zone pairs. These routes have their probability of use determined by the route evaluation process with a series of models: Walk-choice model Service-frequency or the service-frequency-and-cost model Alternative-alighting model
The model theory is described in Route-evaluation process on page 799 and the loading theory is described in Loading process on page 815. Demand may be stratified by user class and loaded to enumerated routes generated either by class or for the whole Public Transport network. Loading is invoked by assigning, either input or generated trip matrices to TRIPSIJ[#], or trips for individual zone pairs to the variable TRIPSIJ in the SELECTIJ phase.
12
The results of loading, passenger flows on lines, may be reported with the REPORT statement. This can be done either in the run in which loading was performed or by saving the loaded public transport network and reporting the loads in a subsequent run of the program. See Public transport loading on page 856 for an example of this function.
Inputs required for Public Transport loading
Public Transport network file, either produced by the current run of the Public Transport program, or produced previously and input with NETI. Route file, produced either by the current run of the Public Transport program, or produced previously and input with ROUTEI (for multiple user classes, enumerated routes files input with ROUTEI[#]). NOTE: If previously built NETI and ROUTEI files are input, they must be compatible. Trips for loading onto the routes These may be input as a trip matrix with MATI, or computed during the run (for multiple user classes, trip matrix files input with MATI[#]).
Outputs produced by Public Transport loading

A loaded Public Transport network with transit and nontransit loads, which may be saved in the file designated by NETO. This network may be displayed by Cube but not edited. Loaded nontransit legs, in ASCII format, which may be saved in the file designated by NTLEGO. Loaded lines, in ASCII format, which may be saved in the file designated by LINEO. A table of link and their attributes, including loads, in DBF format, which may be saved in the file designated by LINKO.
Associated phases
MATI
12
Select link
During the select-link process, the Public Transport program produces output matrices of demand matching selection criteria, and can also perform select-link loading. When you model multiple user classes, this process can produce select link outputs for each class from the individual enumerated route files. You can also use Cube Analyst to estimate Public Transport demand matrices. See INTERCEPTO and SCREENLINEO in FILEO on page 684 for more information.
Inputs required for Public Transport select link
A public transport network file, either produced by the current run of the Public Transport program, or produced previously and input with NETI. A route file, produced either by the current run of the Public Transport program, or produced previously and input with ROUTEI (for multiple user classes, enumerated routes files input with ROUTEI[#])
NOTE: If you input previously built NETI and ROUTEI files, they must
be compatible.
Outputs produced by Public Transport select link
A matrix file, MATO (for multiple user classes, matrix files, MATO[#]) Loadings, when only that demand which satisfies a select-link criterion is loaded
Associated phases
SKIMIJ (mandatory) MATO
Select-link functions
The select-link function provides a range of facilities to identify travel demand using particular links, lines, or nodes in the network. Lines may be identified explicitly or selected based on their mode
12
or operator attributes. Throughout this section the functionality is referred to by the generic term select link although in practice it offers a wider range of selection mechanisms. The select-link function outputs a matrix, containing that demand which satisfies the selection criteria. In a run, you may specify a series of selection criteria, each one being associated for output purposes with a different working matrix. You can save the resulting matrices to the FILEO MATO[n] where n is the user class being evaluated (that is, select link results are saved to the same matrix file as skim outputs). The process normally considers just transit legs using the link/line, or passing the node. However, if required nontransit legs may be considered, or for nodes the activity may be restricted to specific movements (for example, boarding a transit line). The select-link criteria are defined as expressions, which allows compound conditions (using and / or / not operations) to be specified. You may specify additional keywords in the expression to obtain either percentage or proportion of demand (rather than actual demand flow) satisfying the criteria. These allow you to obtain results when demand flows for an I-J pair are zero. The demand flows loaded onto the network may be restricted to just that demand which meets the selection criteria. This permits the display of demand and loadings which use the selected link. Where several select link functions are used in a run only one of them may contain the keyword which triggers select-link based loading. The general form of the select-link function is:
SELECTLINK (expression)
where the expression defines the selection criteria. This general form typically appears on the right hand side of a COMP (compute) statement which sets the value of cells in a particular working matrix, for example:
12
MW[MatrixNumber] = SELECTLINK (expression)
The compute command is coded as part of the SKIMIJ phase. Where no route is found for an I-J pair all select link functions will return zero values. As a general rule, working variables or results of COMP commands may not be used to specify values which form part of a selection expression. The values required by the user must be specified directly in the script, or obtained from scenario keys (by substitution into the script). This topic discusses: Selection for particular links Select line Select node Select mode Select operator Combining selection criteria together Using simultaneous selection criteria Use of the not and not equals operators Selecting particular types of movement Obtaining matrices of proportion or percentage of demand meeting a criterion Loading the select link demand
Selection for particular links
To select demand traversing a link, the expression takes the form

L = ANode-BNode
12
This identifies all demand traversing the link in the direction from the given A-node to the B-node. To identify demand in either direction along the link a * is appended to the specification:
L = ANode-BNode*
Examples:
MW[1] = SELECTLINK(L=1023-1027)
selects demand traversing the link 1023 to 1027 in that direction, whereas:
MW[2] = SELECTLINK(L=1025-1028*)
selects demand traveling along the link in either direction. The expression used may contain a list of link specifications, which are separated by commas (or alternatively spaces). If a list is defined, using any one of the links turns the selection criterion to true. For example:
MW[3] = SELECTLINK(L=101-102, 104-105*, 107-109)
selects demand if one of the links 101 to 102, 104 to 105, 105 to 104 or 107 to 109 is on the path. The use of comma between link specifications is optional, and may be replaced by a space character. Selection criteria which require the use of two or more links are described below.
Select line
To select demand using a particular line, the expression takes the form:
LINE = LineName
Use of two or more line names in a list is permitted, and when used the selection criteria is true if any one of the listed lines is used.
12
Line names may contain masks of a single trailing * or one or more trailing ?. The leading nonmasked portions will then be compared for selection purposes. Use the * for multiple columns. For example:
LINE = MUNI*
matches line names such as MUNI, MUNICENTRAL, and MUNINORTH. Use the ? for single characters. For example:
LINE = MUNI-??
would match line names MUNI-01 and MUNI-02. Examples:

MW[1] = SELECTLINK(LINE=RED1)
selects demand using the line which has name RED1.

MW[2] = SELECTLINK(LINE=A*, B*)
selects lines with names beginning with either A or B.

Select node
To select demand passing through a particular node, the expression takes the form:
N=NodeNumber
Lists of nodes may be used, and ranges of nodes may be specified using -. Examples:
MW[1] = SELECTLINK(N=107,200-208)
selects demand which passes through node 107 or any of the nodes in the range 200 to 208. The selection considers transit legs which start at, pass through, or finish at the specified node(s).
12
Select mode
To select demand which uses a particular mode, the expression takes the form:
MODE = ModeNumber
The mode number may be a transit mode (in which case demand using lines of that mode are selected) or can be a nontransit mode. Lists and ranges may be used when specifying the required modes. Tests using not equals (!= or <>) are permitted with mode conditions. For example:
MW[5] = SELECTLINK(MODE=3,5,7-9)
selects demand which uses any of modes 3,5,7,8 or 9.

Select operator
To select demand which uses lines from a particular operator, the expression takes the form:
OPERATOR = Number
Lists and ranges of numbers may be used when specifying the required operators. Tests using not equals (!= or <>) are permitted with operator conditions. Example:
MW[7] = SELECTLINK(OPERATOR=3)
selects all demand on lines run by the operator having an identification number of 3.
Combining selection criteria together
You can combine two or more select-link criteria to form compound conditions. Use the and operator (& or &&) and or operator (| or ||) to combine simple conditions. The use of | (or) operators may sometimes be avoided when the same data type is referred to in both tests. The example:
12
MW[5] = SELECTLINK(L=401-402 | L=421-422)
gives exactly the same results as:

MW[5] = SELECTLINK(L=401-402, 421-422)
Two tests based on link-selection criteria may readily be combined using the and operator. For example:
MW[3] = SELECTLINK(L=101-103 & L=108-109)
selects demand which travels along both link 101 to 103 and 108 to 109. In evaluating this test it does not matter which of the links is traversed first; it is use of both of them which sets the selection to on. In a similar manner:
MW[4] = SELECTLINK(LINE=RED2 & LINE=BLUE7)
selects demand which uses both line RED2 and also line BLUE7. Again, which is used first does not matter. When combining tests using two data types it is also necessary to consider how the conditions interrelate. As an example, consider how you might combine a test on a link with a test on a line. You might wish to specify that the link was used (somewhere in the trip) and that the line was also used (at some point in the trip). These conditions are independent of each other. Alternatively the requirement may be that the line was used to traverse the specified link; this is a simultaneous condition where two or more conditions must all apply at one point in the trip, and such conditions are considered in the following section. Where the selection criteria are independent, use of the and operator is appropriate. For example:
MW[6] = SELECTLINK(L=211-234 & LINE=GREEN)
treats the two conditions as independent tests, so that demand is selected if the link 211 to 234 is traversed and also (but not necessarily at the same time) the GREEN line is used.
12
Using simultaneous selection criteria
Where two conditions apply simultaneously the operator, use + to combine them. Such simultaneous conditions are combined together before any & and | operators are evaluated. For example:
MW[2] = SELECTLINK((L=101-102 + LINE=RED) & (L=201-202 + LINE=BLACK))
selects demand which uses line RED on link 101 to 102 and also uses line BLACK on link 201 to 202. The use of brackets around each simultaneous condition is optional; brackets ease reading of the condition groups, and may be omitted without affecting the results. The + operator is typically used to combine: Link conditions with line, mode, or operator conditions Node conditions with line, mode, or operator conditions Any condition with criteria determining type of movement or leg considered (as described below)
Use of the not and not equals operators
Use care with negated conditions. The not equals operator (!= or <>) is not permitted in link or node expressions (that is, L or N expressions). When using negated tests with line conditions, it is often appropriate to use an expression of the form !(LINE=RED) which means did not use line RED. Use of not equals may give results which do not exactly match your intentions. For example, the condition LINE != RED means used lines other than RED. If considering a two-leg trip where line RED used on the first leg, then this condition would be true as some line other than RED is used on the second leg.
12
Selecting particular types of movement
The normal operation of select link considers transit legs (passing along a link or at a node), unless mode selection criteria have been specified. You can amend this default behavior, allowing the selection criteria to consider particular types of movement. These are specified in the select link expression by a TYPE keyword (which is usually part of a simultaneous condition, linked by + operator to the associated link or node condition). For conditions using link selection (that is, L= conditions) the TYPE keyword can take either of the following values. NTINCLUDED To consider transit and nontransit legs traversing the link NTONLY To select just nontransit legs
The link specification will select nontransit legs which either traverse the specified link (if XN values are available in NTLEG data for intermediate nodes), or when no XN data is available the start and end points of the nontransit leg correspond to the link specification. The TYPE keyword may not be followed by a notequals (!= or <>) operator. For conditions using node selection (that is, N= conditions) the TYPE keyword can take the following values THRU To consider transit legs passing through the node BOARD To consider transit legs boarded at the node ALIGHT To consider transit legs alighted from at the node NTTHRU To consider nontransit legs passing through the node. The nontransit legs selected will be those which have the specified node in their list of XN values.
The condition may use a list of two or more of these settings to select movements where any of the listed types apply. The TYPE keyword may not be followed by a not-equals (!+ or <>) operator. The following examples illustrate use of the TYPE keyword:
12
MW[1] = SELECTLINK(L=101-102 + TYPE = NTINCLUDED)
Selects all journeys travelling along link 101 to 102, whether using a transit line or nontransit (for example, walking).
MW[2] = SELECTLINK((N=123 + TYPE=ALIGHT) & (N=123 + TYPE=BOARD))
Selects all journeys which both alight and board at node 123 (that is, they make an interchange between lines at that node).
MW[2] = SELECTLINK(N=123 + TYPE=ALIGHT)
Selects all journeys which alight at node 123; following that they may board another line there, walk to another node to board a line, or egress from the public transport system to reach a destination zone.
MW[2] = SELECTLINK (N=123 + LINE = X + TYPE = BOARD)
Selects just the demand boarding line X at node 123.

MW[5] = SELECTLINK(N=579 + TYPE = THRU,ALIGHT)
Selects all transit demand arriving at node 579 (whether they alight or continue on the line).
Obtaining matrices of proportion or percentage of demand meeting a criterion
The select process typically returns the demand for an I-J pair which satisfies a selection criterion. The proportion of demand meeting the criterion may be obtained by including the PROBABILITY keyword in the expression (that is, PROBABILITY=T ). Similarly, percentages may be obtained by using the PERCENT keyword (that is, PERCENT=T ). As an example:
MW[3] = SELECTLINK(LINE=TRAM1, PERCENT=T)
Returns percentage values for each I-J pair which use the line TRAM1.
12
Loading the select link demand
The select-link process may load the portion of total demand meeting a select link criterion, rather than loading the entire demand as specified by the parameter TRIPSIJ. This is invoked by including the keyword and setting LOAD=T in the select link expression. As an example:
MW[2] = SELECTLINK(L=303-307*, LOAD=T)
Although a program run may include several SELECTLINK functions, only one of these may be used to trigger select-link loading. Where crowding is modeled, the restriction using selection criteria applies to the last iteration, so the crowding is based on complete loadings. If skims are obtained when performing select-link loading, then the skims are obtained for all evaluated routes (that is, they are not restricted to the subset of routes which match the select link criteria).
Loading analyses
During the loading-analyses process, the Public Transport program presents further reports of transit and nontransit passenger loadings than those performed during the loading process. Any request for loading analyses automatically invokes a loading process. As with the loading process, demand stratified by user class produces loading analyses for each class. Loading analyses are associated with the MATI phase. The analyses currently available are: Transfers between modes Transfers between operators Stop-to-stop movements
12
Transfers between modes
Reports produced if loading is performed and output to the main print file: Passenger transfers between transit and nontransit modes Passenger transfers between transit modes
Transfers between operators
Report produced if loading is performed and output to the main print file: Passenger transfers between transit and nontransit modes
Stop-to-stop movements
Several types of stop-to-stop movements may be extracted, either for a selection of stops, or groups of stops: First entry/last exit Adjacent All on/off combinations
The first two can be obtained by mode or for all modes. You can save this analysis to a DBF file with FILEO STOP2STOPO.
Crowd modeling
During the crowd-modeling process, the Public Transport program iteratively balances loaded demand against capacity. At each iteration, the program completes the route-evaluation and loading processes, which are repeated for all user classes, and then adjusts the costs in the model to reflect the assigned loads. The iterative process may use either, or both, of the crowd modeling procedures: Link travel time adjustment Wait time adjustment
12
See Crowding on page 830 for information about the theory of crowding models. When crowd modeling is performed, the results obtained from the last iteration (in the form of loaded flows, printed reports, and skims) provide the model outputs.
12
Public Transport Program Phases
Phases
The Public Transport program executes its main processesdata processing and modelingwithin a series of phases. You control all the phases and can initiate additional, context-sensitive computations within them. The phases, presented in the order they would normally be implemented, are: NODEREAD Computes node based variables. LINKREAD Computes link based variables. DATAPREP Prepares the public transport network for modeling. MATI Computes trips for loading. SELECTIJ SKIMIJ Extracts skims and select link results, saving them, generally in working matrices. MATO Manipulates and reports skim, select-link, and loading-analyses matrices.
The NODEREAD, LINKREAD, MATI, and MATO phases provide data manipulation facilities, and are secondary to the main functions of the Public Transport program. They are optional. You specify the exact configuration for the Public Transport program to run through a combination of phases and control statements. Control statements provide information and instructions to the program. In the Public Transport program, control statements are either static or dynamic. Static statements may be present anywhere in the job stream; the program evaluates them once. Dynamic statements may be present only within phases; the program evaluates them as encountered, during the execution of the phases.
12
Only context-sensitive dynamic control statements are available to the phases; a list of valid statements is provided with the description of each phase. See Control statements on page 632 for more information. You only must code phases that contain control statements; you need not code empty or null phases. Specify phases in a script as follows:
PHASE=DATAPREP ;Generate access/egress legs GENERATE ... ... ;End of GENERATE ENDPHASE
Regardless of the functionality selected for any run of the Public Transport program, a requirement is that a network, basic or public transport, is always input. This is read and set up at the start of each run; no user intervention is required.
12
A diagram showing how the phases would be used in a typical public transport model follows:
Processing phases in a public transport model
12
NODEREAD
In the NODEREAD phase, you can compute node-based information from the input networks node attributes with NETI. This information is for use primarily in the DATAPREP phase but is available in later phases if the DATAPREP phase is active. The control statements within the NODEREAD phase are executed once per node. Only one NODEREAD phase is permitted per run. The computed variables may be scalars or vectored by node. The use of a vectored variable produces an array containing a computed value for each node. Vectored variables have the case insensitive prefix nw. The evaluated expression may contain any valid variables, numeric or string, and node based variables from the input network. Input node variable names must have the case insensitive prefix ni. An example of a computed node variable is:
NW.XplusY = NI.X + NI.Y
Computed variables are available for the duration of the run but not saved back to the network. See Example 2: Preparing a public transport network from TRIPS link data on page 851 for an example of this phase.
Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO
12
IF... ELSEIF ... ELSE ... ENDIF LOOP ... ENDLOOP PRINT Public Transport variables available in this phase
ZONES
LINKREAD
In the LINKREAD phase, you can compute link-based information from the input networks link attributes with NETI. This information is for use primarily in the DATAPREP phase but is available in later phases if the DATAPREP phase is active. The control statements within the LINKREAD phase are executed once per link. Only one LINKREAD phase is permitted per run. The computed variables may be scalars or vectored by link. The use of a vectored variable produces an array containing a computed value for each link. Vectored variables have the case insensitive prefix lw. The evaluated expression may contain any valid variables, numeric or string, and node based variables from the input network. Input link variable names must have the case insensitive prefix li. An example of a computed link variable is:
LW.GCTime = LI.Time * 1.5
Computed variables are available for the duration of the run but not saved back to the network. See Example 2: Preparing a public transport network from TRIPS link data on page 851 for an example of this phase.
Control statements available in this phase ABORT
12
BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF LOOP ... ENDLOOP PRINT Public Transport variables available in this phase
ZONES LINKNO
DATAPREP
The DATAPREP phase invokes the Public Transport network development process and provides the mechanism for generating and/or reading nontransit legs. You can develop nontransit legs with one or more GENERATE control statements, or you can produce them externally to the Public Transport program and input them in this phase. You can compute data for nontransit leg generation from the input network with the COMP statement. See Public transport network development on page 849 for examples of this phase.
Control statements available in this phase ABORT BREAK
12
COMP CONTINUE EXIT GENERATE GOTO IF... ELSEIF ... ELSE ... ENDIF LINKLOOP ... ENDLINKLOOP LOOP ... ENDLOOP PRINT Public Transport variables available in this phase
ZONES
MATI
The MATI phase produces working matrices, (MW[#]), from FILEI MATI matrices (MI.#.name), although COMP statements can also compute working matrices. The MATI phase is executed for each origin zone, I, before the route evaluation, skimming, loading, and loading analyses processes are done for each zone pair, I-J. This phase provides a flexible mechanism for generating and manipulating one row of a matrix at a time. You might use this phase to: Examine the matrix input with FILEI MATI, one row at a time, and determine if there is anything specific about zone I that could affect further processing for that zone. For example, if MATI points to a highway network matrix, and the matrix indicates that there is no highway access for zone I, you might set a variable for zone I and test in the SELECTIJ phase.
12
Compute a row of trips, from an origin zone (I) to all zones (J), using the COMP statement and the built-in ROW functions, and save the trips in a working matrix, MW[#], for subsequent loading. You can also do this in the SELECTIJ phase, but for a zone pair at a time. The working matrix is designated for loading with PARAMETERS TRIPSIJ[userclass]. Input matrices external to the Public Transport program with
FILEI MATI, and then manipulate, report, and save those matrices with FILEO MATO. You can merge highway skims with
skims extracted in the Public Transport program run. The working matrix may be reported with the PRINTROW statement. With the BREAK statement, you can use the MATI phase to select zones for processing. See Public transport loading on page 856 for an example of this phase.
Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LOOP ... ENDLOOP PRINT PRINTROW
12
Public Transport variables available in this phase
ZONES USERCLASS I J
SELECTIJ
The SELECTIJ phase selects pairs of zones, I-J, for bypassing the route-evaluation process. The ROUTEI and ROUTEO subkeywords I, J, and SELECTBYMAT provide the first line of selection but they do not control specific I-J combinations. The SELECTIJ phase allows a finer selection of specific I-J combinations, although if the I-J combination is precluded by the values on the ROUTEI and ROUTEO, that I-J pair is not available to this phase. The Public Transport program executes the SELECTIJ phase prior to the route-evaluation process for the I-J pair. (Route evaluation is a time consuming process, therefore judicious use of this phase can have a significant impact on overall processing time.) Only zone pairs for evaluated routes are available for the skimming, loading, and loading analyses processes. This phase can compute the trips to be loaded for each I-J pair. For example:
PHASE=SELECTIJ if(I < 10) CONTINUE if(J > 10) BREAK TRIPSIJ=MI.1.1 * 0.75 PRINT LIST=I,J,TRIPSIJ ENDPHASE
In this fragment of code, the I-J pairs loaded range from I=10-ZONES to J=1-9. The trips to be loaded are computed from the input trip matrix and reported.
12
Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF PRINT PRINTROW Public Transport variables available in this phase
ZONES USERCLASS I J
SKIMIJ
The SKIMIJ phase extracts skims and select-link outputs with special functions described in Select-link functions on page 607, then saves them, generally in working matrices with the COMP MW[#] statement. The Public Transport program invokes SKIMIJ for each zone pair, I-J, immediately after route evaluation. See Public transport skimming on page 854 for an example of this phase.
12
MATO
In the MATO phase, the Public Transport program revises, combines, reports and writes work matrices to the FILEO MATO files. The program executes this phase once for each origin zone, I, after completing the route evaluation, skimming, loading, and loading analyses processes for all destination zones of that origin zone. Generally, you use the MATO phase with the matrices produced by the skimming and loading analyses phases, but you can also process other working matrices similarly. You can manipulate matrices with the COMP statement and a set of built-in ROW functions, and create a report with the PRINTROW statement. With the BREAK statement, you can use the MATO phase to select zones for processing. See Public transport skimming on page 854 for an example of this phase.
Control statements available in this phase ABORT BREAK COMP CONTINUE EXIT GOTO IF... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LOOP ... ENDLOOP PRINT PRINTROW
12
Public Transport variables available in this phase
ZONES USERCLASS I J
12
Public Transport Program Control statements
Control statements
Control statements provide instructions and information to the Public Transport program. The Public Transport program has two types of control statements: Static Evaluated only once, at the start of each run, regardless of their location in the script. Citilabs recommends keeping static control statements together at the beginning of the script file. Examples of static control statements include FILEI, FILEO, PARAMETERS, and REREPORT. Some static statements are provided in files, not in the job script (that is, LINE, MODE, FACTORS). Dynamic Evaluated as encountered. These may only be present in the processing phases. Phases only permit contextsensitive control statements; see each phases description in Phases on page 620 for a list of valid statements. Examples of dynamic control statements include LINKLOOP ... ENDLINKLOOP, JLOOP ... ENDJLOOP, PRINT, GENERATE.
The control statements available in the Public Transport program are listed below. Some are specific to this program while others are available throughout Cube Voyager.
Control statement ABORT BREAK COMP CONTINUE CROWDCRVDEF CROWDMODEL EXIT FACTORS FARESYSTEM FILEI FILEO Public Transport Public Transport Cube Voyager Cube Voyager Static Static Static Static Public Transport Static Availability Cube Voyager Cube Voyager Cube Voyager Cube Voyager Type Dynamic Dynamic Dynamic Dynamic
12
Control statement GENERATE GOTO IF... ELSEIF ... ELSE ... ENDIF JLOOP ... ENDJLOOP LINE LINKLOOP ... ENDLINKLOOP LOOP ... ENDLOOP MODE NT OPERATOR PARAMETERS PRINT PRINTROW REPORT REREPORT VEHICLETYPE WAITCRVDEF
Availability Public Transport Cube Voyager Cube Voyager Cube Voyager Public Transport Public Transport Cube Voyager Public Transport Public Transport Public Transport Public Transport Cube Voyager Cube Voyager Cube Voyager Public Transport Public Transport
Type Dynamic Dynamic Dynamic Dynamic Static Dynamic Dynamic Static Static Static Static Dynamic Dynamic Static Static Static
ABORT
Terminates a run.
ABORT MSG = text
ABORT keyword
Keyword MSG |S| Description Optional. Message printed when the program terminates.
12
Example
Before generating access and egress legs in the DATAPREP phase, this script checks that the speed of links that may be used for walking is between 0 and 5 km/h. If the script finds links outside this range, the script reports the links and aborts the run with an appropriate message.
PHASE=DATAPREP LnkCnt = 0 LINKLOOP if((li.a <=24 || li.b <=24) && (lw.WalkSpeed <= 0 || lw.WalkSpeed > 5.0 )) LnkCnt=LnkCnt+1 print list=li.a, li.b, lw.WalkSpeed endif ENDLINKLOOP print list= 'Number of access/egress links with invalid walk speeds = ', LnkCnt if(LnkCnt>0) abort msg = Access/Egress Links with invalid walk speeds ;Generate access legs only if walk costs coded on links GENERATE...... ENDPHASE
BREAK
Breaks out of a loop. Upon encountering BREAK, the script immediately passes control to the statement after the associated loop. If BREAK is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1). If BREAK is not within a LOOP or JLOOP block, the script terminates processing for the I zone but does not bypass output and zonal reporting statistics.
12
When used within the Public Transport programs MATI or MATO phases, BREAK bypasses any more processing for the relevant I zone, breaks out of the I-loop, and bypasses end-of-zone processing for zone I.
Example 1
Loop terminates if condition 1 is not met, regardless of the value of L1. When condition 2 is met, control passes to the following IF statement and processing for zone I ceases.
LOOP L1=1,3 IF (condition 1) statements ELSE BREAK ENDIF ENDLOOP IF (condition 2) BREAK
Example 2
MATI selects zones 1 to 19 for processing, ignoring all other zones. BREAK terminates the I-loop at zone 20 for each user class, enabling no further processing. The route-evaluation, skimming, loading, and loading-analyses processes are completed for loop J within loop I. Therefore, they would be done only for zones 1-19.
PHASE=MATI IF(I==20) BREAK MW[1] = MI.1.1 ENDPHASE
Example 3
MATO selects zones 1 to 19 for reporting, manipulating matrices, and saving matrices to file. BREAK terminates the loop at the 20th zone. Therefore, the route-evaluation, skimming, loading, and loading-analyses processes effectively stop after the 19th zone for each user class. (Because MATO follows the processes, the processes will run for zone 20 but will not save any matrices produced.)
PHASE=MATO
12
IF(I==20) BREAK MW[1] = MW[1] * 1.2 ENDPHASE
COMP
Computes a variable, matrix, or matrix element from an expression.
VAR=expression MW[n]=expression, INCLUDE=list of J zones, EXCLUDE=list of J zones
Expressions are either numeric formulas or selection criteria. See Expressions on page 30 for more details. Numeric expressions can use built-in functions that operate on numeric, string, or row data and return a value. Built-in functions must be followed by one, or more, arguments enclosed within parentheses (). The number of arguments must match the requirements of the function. Built-in functions include: Numeric functions (see Numeric functions on page 32) String functions (see Character functions on page 34) Row-based functions, which process the cells in a row (see Matrix function descriptions on page 464)
NOTE: You cannot use row-based functions within a J-loop.
12
Skimming functions, which produce skim (level of service) matrices of total trip costs and their components (see Skimming (level of service) on page 593)
COMP keywords
Keyword MW
Subkeyword |KD|
Description Optional. Value for a working matrix. You can specify this keyword in two formats: MW[n] Defines the value for row n of a working matrix. Matrices can contain up to MAXMW rows, as indexed by n. The index n may be either a constant or a variable name. The program solves the expression for all values of J (1 through Zones), filtering values indicated by any INCLUDE or EXCLUDE lists on this statement. Within a JLOOP statement, the program only solves the expression one time only, with J being the value of the loops current J. MW[n][o] Defines the value for column o in row n. The second index, o, must be between one and Zones. The program solves the expression one time only, with J being the loops J if within a JLOOP, or 1, if not.
MW
EXCLUDE
|I|
Optional. Values of J excluded when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the EXCLUDE list. If the current J is on the list, the program does not evaluate or store the expression for that J. Specified values can range from 1 to the highest zone number. Filter applies to all MW[n] values on the COMP statement. Not permitted if COMP statement within JLOOP ... ENDJLOOP block. Always processed after INCLUDE subkeyword. By default no zones are excluded.
12

Keyword MW Subkeyword INCLUDE |I| Description Optional. Values of J included when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the INCLUDE list. If the current J is not on the list, the program does not evaluate or store the expression for that J. Specified values can range from 1 to the highest zone number. Filter applies to all MW[n] values on the COMP statement. Not permitted if COMP statement within JLOOP ... ENDJLOOP block. By default all zones are included. VAR |K| Optional. Variable that stores result of an expression. The program evaluates each encountered expression (for example, each node in the NODEREAD phase or each link in the LINKREAD phase). If the result is a character string, the variable must be a character string variable. The COMP statement sets a variable type to the result of the variables first evaluated expression. Examples of variables are:
abc = '123' def = 123 abc = def ;invalid: abc has been declared a string abc = abc+'456' ;valid abc = abc+def ;messy -- do not mix types jkl = 1 ;jkl is declared numeric jkl = xyz ;invalid: xyz is declared a string (later) xyz = 'xyz' ;xyz is declared a string
The program does not always compute expressions for variables that are not used as input to some process. In the above examples, the statements with jkl= might never be executed, because jkl is never used.
12
Examples of computation statements in Public Transport
This example reports the nonzero rows of a selection of skim matrices.

Phase=MATO if (ROWSUM(2) > 0) PRINTROW MW=2 TITLE='Compcost', BASE1=T, FORM=10.2 if (ROWSUM(3) > 0) PRINTROW MW=3 TITLE='ValOfChoice', BASE1=T, FORM=10.2 if (ROWSUM(4) > 0) PRINTROW MW=4 TITLE='IWAITA', BASE1=T, FORM=10.2 if (ROWSUM(5) > 0) PRINTROW MW=5 TITLE='XWAITA', BASE1=T, FORM=10.2 if (ROWSUM(6) > 0) PRINTROW MW=6 TITLE='IWAITP', BASE1=T, FORM=10.2 Endphase
Compute average perceived trip cost skim from its components.

Phase=SKIMIJ MW[1]= IWAITP(0) MW[2]= XWAITP(0) MW[3]= TIMEP(0,ALLMODES) MW[4]= BRDPEN(0,ALLMODES) MW[5]= XFERPENA(0, ALLMODES) Endphase Phase=MATO x=ROWADD(6,1,2,3,4,5) PRINTROW MW=6 TITLE='AVJRNYCOST', BASE1=T, FORM=10.2 Endphase
Determine the highest node number in the public transport system, using standard function MAX.
HighestNodeNum = MAX(HighestNodeNum, Anode, Bnode)
CONTINUE
Jumps to the end of a loop, bypassing all intermediate statements.
12
If CONTINUE is within a LOOP ... ENDLOOP or JLOOP ... ENDJLOOP block, control passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise, processing for the I zone is terminated, but output and zonal reporting statistics will not be bypassed.
Example 1
LOOP L1=1,3 IF (!(condition 1)) CONTINUE ENDLOOP
In this user-controlled loop, control is passed to the ENDLOOP when condition 1 is not met, bypassing any statements between the IF and ENDLOOP, for that value of L1.
Example 2
IF (condition) CONTINUE
This statement is used in an explicit or implicit loop over I. If the condition is met, no more Js will be processed for the I zone, except output and zonal summaries.
Example 3
LOOP L2=K1,K2,KINC JLOOP EXCLUDE=25-50,88 IF (condition 1) CONTINUE .... ENDJLOOP LOOP L3=L2,L2+5 IF (condition 2) CONTINUE ..... ENDLOOP ENDLOOP
JLOOP processing is bypassed for the Js for which condition 1 is met; similarly, LOOP processing is bypassed for the L3s for which condition 2 is met. The outermost LOOP operates over the full
range of L2, from K1 to K2, incrementing in steps of KINC.

Example 4
PHASE=SELECTIJ
12
IF(I<403)CONTINUE IF(I>455)BREAK IF(J<403)CONTINUE IF(J>455)BREAK ENDPHASE
The SELECTIJ phase selects zone pairs, I and J, 403-455 for processing. The first CONTINUE bypasses origin (I) zones 1-402 and the second one bypasses destination (J) zones 1-403. The first BREAK stops the I-loop after zone 455 and the second stops each Jloop after zone 455.
CROWDCRVDEF
Defines crowding curves, used to compute crowded travel time for particular combinations of transit lines and user-class. Crowded travel times are behavioral measures which increase the in-vehicle time to reflect the discomfort of standing or travelling in crowded conditions. You can define up to 255 wait curves. No default curves are provided. If crowding is not applied, then either do not code line capacities, or use a flat curve (with y-value set to 1.0 at both x=0 and x=100).
12
Input CROWDCRVDEF statements must be input in the public transport system data file with SYSTEMI.
CROWDCRVDEF keywords
Keyword CURVE |R| Description Defines X-Y pairs for the crowding curves used to compute link travel times under crowded conditions. Utilization (measured as a percentage) is the curves X-axis and the crowding factor is the curves Y-axis. The values for utilization vary from 0.0 (where the crowding factor is at least 1.0) to 100.0. Specify the utilization values in ascending order; the corresponding crowding factor values must increase, or remain the same, when progressing from one point to the next. Each pair of X and Y values may be separated by a comma or a dash, while the pairs themselves must be separated by a comma. For example:
CROWDCRVDEF NUMBER=1 LONGNAME="Suburban Rail" NAME="S-Rail" , CURVE= 0,1.0, 20,1.1, 100,1.9
The following rules apply to the coding/interpreting of crowding curves: Values for the first coded Y-value may not be less than 1.0. Crowding factor (Y-axis) may not decrease as utilization (X-axis) increases. There is a linear interpolation between coded points. When the first coded X-value is greater than 0% utilization, the curve runs from the point (0-1.0) to the first coded point. When the last coded X-value is less than 100%, the curve is extrapolated beyond that point at the same gradient as applies immediately below the point.
Maximum value: 10,000. LONGNAME NAME NUMBER |S| |S| |I| Optional. Specifies a second text-string identifier for a crowding curve. It is in addition to NAME. Optional. Specifies a text-string identifier for a crowding curve. Specifies a unique numeric identifier for a crowding curve. Must be the first keyword coded on the CROWDCRVDEF control statement. Valid values range from 1 to 255.
12
Example
Defining crowd curve number 1 for rail services.

CROWDCRVDEF NUMBER=1, NAME="Medium distance Rail", CURVE= 0-1.0, 37-1.1, 100-1.9
CROWDMODEL
Specifies the crowding model used in the run of the Public Transport program.
CROWDMODEL keywords
Keyword ADJUSTLINK |?| Description Optional. When set to true, invokes link travel-time adjustment, which reflects higher behavioral costs associated with travelling in crowded conditions. Default value is false. ADJUSTWAIT |?| Optional. When set to true, invokes the calculation of additional wait time. Uses the available capacity of a service (at a particular boarding point) along with demand data to establish whether travellers may board this service, or must wait for a later service. Default value is false. APPLY |?| Optional. When set to true, runs the crowding model. When set to false, the crowding model is disabled. Default value is false. ITERATIONS PERIOD |I| |I| Specifies the number of iterations performed during a crowd-modeling run. Valid values are 1 to 99. Length of the modeled period in minutes. Any demand matrix loaded during assignment should be calculated for the model period. Valid values are 1 to 1440. Default value is 60.
Example
CROWDMODEL, APPLY = T, ADJUSTWAIT = T, ITERATIONS = 10
12
Specifies a run with 10 iterations of crowd modeling, including a wait-time adjustment.
EXIT
Terminates loops (implied or explicit). When the program encounters an EXIT statement within a loop, the program passes control to the end of the loop.
Example
LOOP iter=1,10 . IF (expression) EXIT . ENDLOOP
This loop terminates either when iter=11 or the condition specified by expression is met.
FACTORS
Specifies the generalized cost factors and control information for the route enumeration and evaluation processes.
FACTORS statements must be input in a separate file with FACTORI keywords on the FILEI control statement. Each user class that the program references must have FACTORI keywords defined on a FILEI control statement, although two or more classes may reference the same file. The index of the FACTORI keyword, #, is the number of the user class. If there is no index, the program assumes the index is 1. You define user classes with the USERCLASSES keyword in the PARAMETERS control statement.
Some FACTORS keywords are used for both the route enumeration and evaluation processes; others apply to one or the other, as noted in the keyword description.
12
The keywords on this statement are all trigger keys; you need not code the control statement name FACTORS. The values can be input in any order. For most of the keywords, the program uses the last value specified, if the keyword appears multiple times.
FACTORS keywords
Keyword ALPHA Subkeyword |RK| Description Optional. Determines the relative weights for the generalized costs of the walk leg and the remainder of the route in walk-choice model. Valid values range from 0.0 to 1.0. A value of 1 indicates that the walk and onward costs have equal weight. Lower values indicate the walk cost has more influence than the onward cost in the travelers choice. A travelers willingness to walk might relate to network familiarity. Applies only to route evaluation. Default value is 1.0. AONMAXFERS |IK| Optional. Maximum permitted number of transfers on the minimum-cost, all-or-nothing routes. The all-or-nothing path building process (which precedes route enumeration) identifies the number of transfers on the minimum-cost route from an origin to a destination. Multirouting models only enumerate the all-or-nothing route if the number of transfers exceeds MAXFERS. Only routes with AONMAXFERS (or fewer) transfers are enumerated to the routes file. When BESTPATHONLY=T, only those routes with MAXFERS or fewer transfers are enumerated (that is, AONMAXFERS is not used) Valid values are 0 to 45. Default value is 45.
12
FACTORS keywords (continued)

Keyword BESTPATHONLY Subkeyword |?K| Description Optional. When set to true, the evaluation process identifies a single best path, onto which all demand is loaded, and the enumeration process changes its mode of operation: Best paths using more then MAXFERS transfers are not enumerated, making higher MAXFERS settings appropriate. Do not set BESTPATHONLY to true if PARAMETERS keyword FARE is true or AONMETHOD has value 3. The best-path-only method cannot be used with either the crowding model or the service frequency and cost model. When using best-path modeling, the program ignores settings for the FACTORS keywords ALPHA, AONMAXFERS, CHOICECUT, LAMBDAA, LAMBDAW, REWAITMAX, and REWAITMIN. If using best-path modeling with MUSTUSEMODE set to true, the program uses the FACTORS keywords SPREADCONST, SPREADFACT, and SPREADFUNC; otherwise the keywords are ignored. The default value is false. BRDPEN |RKV999*| Optional. Mode-specific boarding penalty, in minutes. Applied in addition to the transfer penalty specified by XFERPEN. Applied only to transit modes; nonzero values specified for nontransit modes do not have any effect. For example, if BRDPEN=3,3*5,6 then the penalty for boarding any line on mode 1 is three minutes, the penalty for boarding any line on modes 2, 3, and 4 is five minutes and the penalty for boarding a line on mode 5 is six minutes. Valid values range from 0 to 9999. The default value is 0.
12

Keyword CHOICECUT Subkeyword |RK| Description Optional. Eliminates alternatives with low probabilities of use at walk or alternative-alighting decision points. If p is the proportion of the demand that takes the least-cost alternative, then the program discards alternatives taking less than p*CHOICECUT. This is equivalent to choices being eliminated if:
CHOICECUT > e
where:
( Cost i Cost Best )
Scale parameter that reflects traveler sensitivity to cost differences. It takes the value of LAMBDAW or LAMBDAA, depending upon the point in the trip at which it is applied. Cost to destination by choice i
Costi
CostBest Cost to destination by the best choice CHOICECUT applies only to route evaluation; it is not used when modeling best path routes. Valid values range from 0 to 0.2. The default value is 0.01. DELACCESSMODE |IKV999| Optional. Specifies modes that cannot be used as access connectors (from zones to transit lines) during route enumeration. For example, when modeling walk and car connectors, you can use this keyword to restrict access legs to the required mode (that is, walk or car) for a user class. Valid values range from 0 to 999. There is no default. DELEGRESSMODE |IKV999| Optional. Specifies modes that cannot be used as egress connectors (from transit lines to destination zones) during route enumeration. For example, when modeling walk and car connectors, you can use this keyword to restrict egress legs to the mode (that is, car or walk) required for a user class. Valid values range from 0 to 999. There is no default.
12

Keyword DELMODE Subkeyword |IKV999| Description Optional. Specifies modes that the program will not use during route enumeration. You can use this keyword to delete particular modes (transit or nontransit) from the model for a particular user class. Valid values range from 0 to 999. There is no default. EXTRAXFERS1 |IK| Optional. Number of transfers at which the program stops exploration of less direct routes. EXTRAXFERS1 is one of three parameters controlling the exploration of routes. EXTRAXFERS1 applies only to route enumeration. See Route generation on page 662 for more information. Valid values range from 0 to 10. The default value is 3. EXTRAXFERS2 |IK| Optional. Maximum number of transfers explored in excess of the number of transfers required by the minimum-cost route. An upper bound on the number of transfers, in excess of the minimum required, is controlled by EXTRAXFERS1 and MAXFERS (see Route generation on page 662.). EXTRAXFERS2 is one of three parameters controlling the exploration of routes. EXTRAXFERS2 applies only to route enumeration. Valid values range from 0 to 10. The default value is 2.
12

Keyword FARESYSTEM Subkeyword |IK| Description Optional. Number of the fare model that applies to the modes or operators selected with the subkeywords MODE or OPERATOR. The fare model must be one of the fare systems defined with the FARESYSTEM control statement in a FILEI FAREI file. For example, you might describe a fare model in the FAREI files as:
FARESYSTEM NUMBER=1, NAME="Flat", STRUCTURE=FLAT, IBOARDFARE=100, FAREFROMFS=0,30,40 FARESYSTEM NUMBER=2, NAME="DIST-Journ", STRUCTURE=DISTANCE, IBOARDFARE=50, UNITFARE=70, FAREFROMFS=40,0,50
In the factors file, you can apply that fare model to a selection of transit modes:
FARESYSTEM=1, MODE=1-6 FARESYSTEM=2, MODE=7-11
FARESYSTEM applies only to route evaluation. Valid values range from 1 to 1999. By default, none are specified. NOTE: The MODE and OPERATOR subkeywords are mutually exclusive, but you must code one for each FARESYSTEM. If using multiple fare models, all FARESYSTEM keywords must apply to either modes or operators. The program allocates fare systems to lines, through their modes or operators. Mixing the two could produce ambiguous allocations. FARESYSTEM MODE |IVt|1 Optional. List of transit modes that the fare model specified in FARESYSTEM applies to. Program ignores any nontransit modes in the list. Valid values range from 1 to 999. Default value is 0. FARESYSTEM OPERATOR |IVo|
2
Optional. List of operators that the fare model specified in FARESYSTEM applies to. Valid values range from 1 to 99. Default value is 0.
12

Keyword FREQBYMODE Subkeyword |?K| Description Optional. Flag that determines wait-time calculation: False Calculated at the transit-leg bundle level True Calculated at the (lower) mode level
FREQBYMODE is only applicable when BESTPATHONLY is true. The default value is true. FREQBYMODE comes into effect when a transit-leg bundle (that is, collection of lines from a boarding point to an alighting point) on a potential best route is multimodal. By default the BESTPATHONLY enhancement identifies the best path using unimodal transit-legbundles. If modes 1 and 2 form a bundle, then either you use mode 1 or you use mode 2 depending on IVT and wait times in the two cases. The wait times are based on the headway of the mode under consideration. This corresponds to traveler behavior where a traveler selects a mode of travel, and then waits for a service of that mode (ignoring any potentially useful services in the transit leg bundle of any other mode). If FREQBYMODE is false then multimodal transit leg bundles are allowed. In this case, the wait time is based on combined frequency of all lines in the transit bundle regardless of mode, and the average IVT is based on all modes. This gives lower wait times, and corresponds to traveler behavior where they select the useful service that first arrives at the boarding point, and mode does not affect that boarding pattern.
12

Keyword IWAITCURVE Subkeyword |IK| Description Optional. Wait curve used to calculate the initial wait time for trips starting at nodes specified by NODES subkeyword. For example, given IWAITCURVE=2, NODES=10002000, 2500-2600, the program uses wait curve number 2 to calculate the wait time for journeys starting at nodes 1000 through to 2000 and 2500 to 2600, inclusive. IWAITCURVE applies only to the route-evaluation process. Valid values range from 1 to the number of wait curves in the network. The default value is system generated. IWAITCURVE NODES |IV10000| List of nodes to which the wait curve number specified by IWAITCURVE, applies when they are the initial boarding points of trips. The program ignores wait curves associated with zones or nodes that are not stops. Valid values range from 1 to the systems highest node number. This keyword is required if IWAITCURVE is specified. LAMBDAA |RK| Optional. Scaling factor for the alternative-alighting node model. Determines the proportion of trips allocated to each alighting node, based on the composite cost differences between the alternatives. Applies only to the route-evaluation process. Not used when modeling best-path routes. Valid values range from 0.0001 to 99.0. The default value is the value of LAMBDAW.
12

Keyword LAMBDAW Subkeyword |RK| Description Optional. Scaling factor for the walk-choice model. This factor determines the proportion of trips allocated to each walk choice at a node, based on the composite cost differences between alternatives. When there are transit choices, the program uses the transit modes composite cost to a destination to determine the transit share. Subsequently, the service-frequency model allocates the transit share among the different transit choices. LAMBDAW applies only to the route-evaluation process; the program does not use this factor when modeling best-path routes. Valid values range from 0.0001 to 99.0. The default value is 0.2. MAXCOMPD |IK| Optional. Number of components generated during the route-enumeration process. Used to dimension arrays that store components and their attributes. The number of components generated depends upon the number of lines in the public transport system and the connectivity of the network; the default value should work for a medium-sized network of 400-500 zones. MAXCOMPD applies only to route enumeration. The program only requires MAXCOMPD when using older algorithms, triggered by the AONMETHOD keyword on the PARAMETERS control statement. Valid values range from 1000 to 1,250,000. The default value is 50,000.
12

Keyword MAXFERS Subkeyword |IK| Description Optional. Maximum number of transfers allowed in routes between origin-destination pairs with more than one enumerated route. For pairs with only one enumerated route, AONMAXFERS sets the maximum number of transfers. When an origin-destination pair has a minimum-cost route with at most MAXFERS transfers, then the program enumerates viable routes. If the transfers exceed the MAXFERS when using multirouting, then the program only enumerates the minimum-cost route (subject to any constraint imposed by the AONMAXFERS factor). When BESTPATHONLY is true, you might use higher MAXFERS values, as best routes requiring more transfers are not enumerated. When the PARAMETERS keyword AONMETHOD is set to 3, MAXFERS is the maximum number of transfers allowed in route enumeration, regardless of the number of enumerated routes (AONMAXFERS is not used). Routes with more transfers are not enumerated (which could lead to loss of connection between some origin-destination pairs which have complex journeys between them). MAXFERS works with EXTRAXFERS1 and EXTRAXFERS2 to control the number of routes generated. See Route generation on page 662. Valid values range from 0 to 10. The default value is 5. MUMEXTRACOST |RK| Optional. Additional cost allowed on enumerated routes of a required mode (a mode specified in MUSTUSEMODE). For example, if the cheapest route for an origindestination pair is 23 and MUMEXTRACOST is 30, the the program will enumerate routes on the required mode that have a cost of up to 53 (that is, 23+30). Valid values range from 0.1 to 999,999. The default value is 999,999.
12

Keyword MUSTUSEMODE Subkeyword |IKV999| Description Optional. Specifies required transit modes in a route for enumeration or evaluation. If you specify two or more values, the program enumerates the route if any of the modes are used. Specified modes must be transit modes. Valid values range from 0 to 999. REBESTPATHCOST |?K| Optional. Flag that sets method for computing transit costs in route enumeration: True Computes transit costs closer to those used in evaluation. See Generalized cost on page 771 for a description of costs. False Computes transit
Cannot be false if BESTPATHONLY is true. Must be false if program uses service frequency and cost model. By default, set to the value of BESTPATHONLY. RECOSTMAX |RK| Optional. Upper cost limit that applies during route enumeration. The program excludes more expensive routes from enumeration, and hence evaluation. Valid values range from 0.01 to 999,999. Default value is 999,999.
12

Keyword REWAITMAX Subkeyword |RK| Description Optional. Maximum weighted wait time for any leg bundle in route enumeration. The program computes a leg bundles wait time from the sum of the frequencies of the bundles legs: (60./Frequency)/2 For example, if the frequency of a leg bundle sums to 5 vehicles per hour, the wait time is 6 minutes. Setting REWAITMAX to 3.0 ensures that the maximum wait time at any transit choice point is 3 minutes regardless of the frequency of the services available at that point. Setting REWAITMAX to 0 excludes wait time from consideration during route enumeration. REWAITMAX applies only to route enumeration; it is not applicable when modeling best-path routes. Valid values range from 0.0 to 200.0. The default value is 5.0. REWAITMIN |RK| Optional. Minimum weighted wait time for a leg bundle during route enumeration. The program computes a leg bundles wait time from the sum of the frequencies in the bundles legs: (60./Frequency)/2 For example, if a leg bundles frequency sums to 60 vehicles per hour, the wait time is 0.5 minutes. Setting REWAITMIN to 1.0 ensures that a minimum wait time is incurred for all leg bundles regardless of the frequency of their services. REWAITMIN applies only to route enumeration; it is not applicable when modeling best-path routes. Valid values range from 0.0 to 30.0. The default value is 1.0.
12

Keyword RUNFACTOR Subkeyword |RKVm*|3 Description Optional. Mode-specific weighting factor applied to transit in-vehicle times and nontransit leg times. For example, if you include
RUNFACTOR=1.5,3*1.8,1.9 then the program
multiples run times for mode 1 by 1.5, run times for modes 2, 3 and 4 by 1.8 and run times for mode 5 by 1.9. Values ranging between 0.01 and 3.0 are appropriate for most modeling requirements. Valid values range from 0.01 to 10.0. The default value is 1.0. SERVICEMODEL |S| Optional. Service model to be used in routeevaluation, skimming, loading, and loading-analyses processes. Valid choices are: FREQUENCY Specifies Service-frequency model FREQUENCYCOST Specifies Servicefrequency-and-cost model
Default value is FREQUENCY. SPREADCONST |RK| Optional. Constant used in multirouting function to compute SPREAD (see SPREADFUNC on page 657). Applies only to route enumeration; not applicable when modeling best-path routes. Valid values range from 0 to 1000.0. Default value is 5.0. SPREADFACT |RK| Optional. Multiplicative factor used in multirouting function to compute SPREAD (see SPREADFUNC on page 657). Applies only to route enumeration; not applicable when modeling best-path routes. Valid values range from 0 to 10.0. Typical values range from 1.05 to 1.2, exceeding 2.0 only in rare circumstances. Default value is 1.2.
12

Keyword SPREADFUNC Subkeyword |IK| Description Optional. Integer specifying the function that computes SPREAD during route enumeration. SPREAD defines an upper cost limit for routes between an O-D pair. The lower limit is the cost of the minimum cost route between the two zones. The program computes the upper limit based on value of SPREADFUNC: SPREADFUNC=1: SPREAD = MAX(GCost(MinRoute)* SPREADFACT, GCost(MinRoute) + SPREADCONST) SPREADFUNC=2: SPREAD = GCost(MinRoute)* SPREADFACT + SPREADCONST Where: GCost(MinRoute) Generalized cost of the minimum-cost route. NOTE: This is an estimate. The generalized cost the route-evaluation process uses is more accurate. SPREADFACT Factor that the minimum generalized cost time between zone pairs may be multiplied by. SPREADCONST Time that may be added to the minimum generalized cost time between zone pairs.
The program enumerates routes with a cost less than or equal to SPREAD. NOTE: The parameter applies to each decision point (alighting/boarding node) on a route in addition to the destination. SPREADFUNC applies only to route enumeration; it is not applicable when modeling best-path routes. Default value is 1.
12

Keyword VALUEOFTIME Subkeyword |RKVt*|1 Description Optional. Transit-mode-specific value of time, in monetary units per hour. Converts monetary fares into generalized cost. Only code if using fares. Applies only to route evaluation. Does not apply to nontransit modes; ignored in such cases. Valid values range from 0.0 to 9999. WAITFACTOR |RK| Optional. Node-specific wait-time weighting factor, applied to nodes specified with NODES subkeyword. Valid values range from 0.01 to 10.0. Typically, sufficient values for most modeling range from 0.01 to 3.0. Default value is 1.0. WAITFACTOR NODES |IV10000| List of nodes that WAITFACTOR applies to. For example, consider:
WAITFACTOR=1.5, NODES=1000-2000, 30004500
The wait times for nodes 1000 through 2000 and nodes 3000 through 4000 will be multiplied by 1.5. XFERCONST |RKVt [t]|1 Optional. Transit-mode-to-transit-mode constant that can be added to the weighted transfer penalties obtained from XFERPEN. Use FROM and TO to specify the applicable modes. For example, consider:
XFERCONST=3, FROM=10, TO=25
For transfers from mode 10 to mode 25, the program will add three minutes to the transfer penalty specified by XFERPEN. Applies only to route evaluation. Valid values range from 0.0 to 5000. The default value is 0.0. XFERCONST FROM |IV100| Integer specifying the from mode for the transfer penalty specified with XFERCONST. Valid values range from 1 to the networks highest mode number. XFERCONST TO |IV100| Integer specifying the to mode for the transfer penalty specified with XFERCONST. Valid values range from 1 to the networks highest mode number.
12

Keyword XFERFACTOR Subkeyword |RKVt [t]|1 Description Optional. Transit-mode-to-transit-mode weighting factor for transfer penalties specified by XFERPEN. Use the subkeywords FROM and TO to specify the applicable modes. For example, consider:
XFERFACTOR=1.5, FROM=10, TO=25
For transfers from mode 10 to mode 25, the program multiplies the transfer penalty specified by XFERPEN by 1.5. Applies only to route evaluation. Valid values range from 0.01 to 10.0. The default value is 1.0. XFERFACTOR FROM |IV100| Integer specifying the from mode for the transfer penalty factor specified with XFERFACTOR. Valid values range from 1 to the networks highest mode number. XFERFACTOR TO |IV100| Integer specifying the to mode for the transfer penalty factor specified with XFERFACTOR. Valid values range from 1 to the networks highest mode number.
12

Keyword XFERPEN Subkeyword |RKVt [t]|1 Description Optional. Transit-mode-to-transit-mode transfer penalty, in minutes. Use the subkeywords FROM and TO to specify the applicable modes. For example, consider:
XFERPEN=5.5, FROM=10, TO=25
For transfers from mode 10 to mode 25, the program adds 5.5 minutes. Transfer penalties apply between the alighting and boarding transit modes. The program ignores any nontransit legs traversed between the two. The program applies XFERPEN in addition to BRDPEN. Transfer penalties may be negative but the sum of XFERPEN(from mode, to mode) and BRDPEN(to mode) must be greater than or equal to zero. Use negative transfer penalties in conjunction with boarding penalties to reflect the relative attractiveness of transfers between some modes compared to others. Code a high penalty to ban transfers between modes. A high penalty makes any route with such transfers unattractive to the choice models. In most cases, a penalty of 999 minutes is sufficient. XFERPEN only applies to route evaluation. Valid values range from -99 to 9,999. The default value is 0. XFERPEN FROM |IV100| Integer specifying from mode for transfer penalty specified with XFERPEN. Valid values range from 1 to the networks highest mode number. XFERPEN TO Integer specifying to mode for transfer penalty specified with XFERPEN. Valid values range from 1 to the networks highest mode number.
12

Keyword XWAITCURVE Subkeyword |IK| Description Optional. Wait-curve number used to calculate wait times for trips that involve transfers to nodes specified with NODES subkeyword. For example, consider:
XWAITCURVE=4, NODES=1000-1500
The program uses wait curve number 4 to compute the wait time at nodes 1000 through 1500, when those nodes form transfer points in a trip. XWAITCURVE applies only to route evaluation. Valid values range from 1 to the maximum number of wait curves in the network. The default is a systemgenerated wait curve. XWAITCURVE NODES |IV10000| List of nodes that the wait curve specified in XWAITCURVE applies when they are boarding stops at transfer points. The program ignores wait curves associated with zones or nodes that are not stops. Valid values range from 1 to the networks highest node number. 1. t indicates number of transit modes 2. o indicates number of transit operators 3. m indicates number of modes
Example
//Note: Keywords need not be preceded by control statement name FACTORS //They are directly recognized within context //Enumeration Controls MAXFERS=5 EXTRAXFERS1 = 2 EXTRAXFERS2 = 1 SPREADFUNC = 1 SPREADFACT = 1.1 SPREADCONST = 10.0 REWAITMIN = 5 REWAITMAX = 30 //Evaluation Controls ALPHA = 1.0 LAMBDAW = 0.3
12
LAMBDAA = 0.3 //Wait time IWAITCURVE=1, nodes=1300-1400 XWAITCURVE=2, n=150-1600 WAITFACTOR=2.25, n=25-1000 //IVT factor by mode RUNFACTOR[7] = 1.5, RUNFACTOR[8] = 2, RUNFACTOR[11] = 2.5 //Penalties BRDPEN[7] = 4*2.5 XFERPEN=3.0, from=7-10, to=8-12, XFERPEN=2.0, from=11-12, to=7-12, XFERCONST=5.0, from=7-10, to=7-12, XFERCONST=2.5, from=11-12, to=7-12, XFERFACTOR=1.5, from=7-10, to=8-12, XFERFACTOR=2.0, from=11-12, to=7-12,
Route generation MAXFERS works with EXTRAXFERS1 and EXTRAXFERS2 to control the
number of routes generated. First, the program generates minimum-cost routes for all O-D pairs and records the number of transfers required for these routes, MINXOD. Next, the program searches for attractive routes for each O-D. Attractive routes depend on the number of transfers: If the number of transfers equals MINXOD, number of transfers must be no greater than MAXFERS. If number of transfers exceeds MINXOD, number of transfers must be less than or equal to the minimum of: MINXOD+EXTRAXFERS2
EXTRAXFERS1 MAXFERS
The search for routes has two stages. First, the program determines the connections required to transfer between lines. Second, the program explores the connections and generates routes by progressing through a sequence of lines and connections. The program ensures that routes do not exceed the specified constraints.
12
The following table shows the number of transfers that the program explores for various values of EXTRAXFERS2 if MAXFERS=5 and EXTRAXFERS1=4 (the default condition).
Number of transfers explored
MINXOD 0 EXTRAFERS2 0 1 2 3 4 0 1 2 3 4 1 1 2 3 4 4 2 2 3 4 4 4 3 3 4 4 4 4 4 4 4 4 4 4 5 5 5 5 5 5
For example, suppose MAXFERS=5, EXTRAXFERS1=4 and EXTRAXFERS2=2. If O-D pairs have minimum-cost routes with 0, 1, or 2 transfers, the program will explore routes with up to 2, 3, or 4 transfers (the MINXOD+EXTRAXFERS2 constraint applies). If O-D pairs have minimum-cost routes with 3 or 4 transfers, the program explores routes with up to 4 transfers (the EXTRAXFERS1 constraint applies). Finally, for O-D pairs that have minimum-cost routes with 5 transfers, the program explores 5 transfers (the MAXFERS constraint applies). Thus, the program explores more routes for directly connected zone pairs than for less directly connected zone pairs. This is consistent with observed travel patterns: 70-80% of trips are completed within two transfers or three transit legs. The program expends more effort where travelers make a greater proportion of tips.
FARESYSTEM
Defines fare systems that the program uses to calculate trip fares. Use separate FARESYSTEM statements to define multiple fare systems in public transport network.
12
You input the FARESYSTEM statements to the Public Transport program with the FILEI FAREI file. The program uses fare systems for the evaluation, skimming, loading, and loading-analyses processes. The program does not use fares in enumeration. The program allocates fare systems to lines, either indirectly through transit modes and operators with FACTOR FARESYSTEM, or directly with the LINE control statement. When modeling fares, you must allocate all lines to fare systems; travelers incur fares when using the lines. You can code a NULL fare system to run lines effectively free. Fare systems define the cost of: Travel on lines Boarding the first line of a trip Boarding second and subsequent lines Transfers between lines with the same or different fare systems
See Fares on page 818 for a description of fares modeling.

Example 1: Distance with IBOARDFARE + UNITFARE + SAME=SEPARATE
FARESYSTEM NUMBER=4, NAME=DISTANCE, LONGNAME="WITHOUT FAREFROMFS", STRUCTURE=DISTANCE, SAME=SEPARATE, IBOARDFARE=1.35, UNITFARE=0.83
Example 2: Zone based FROMTO fare system with no FAREFROMFS

FARESYSTEM NUMBER=8, NAME="FAREZONE-FROMTO", LONGNAME="WITH FROM-TO FARES", STRUCTURE=FROMTO, SAME=CUMULATIVE, FAREFROMFS=10*0, FAREMATRIX=FMI.1.1, FAREZONES=NI.FAREZONE
12
FARESYSTEM keywords
Keyword FAREFROMFS Subkeyword |RVn|
1
Description Optional. Fare incurred when transferring from fare systems defined by other FARESYSTEM control statements to this fare system. You can also provide the cost of transferring between the same fare system, and incentives (that is, negative fares) between select fare systems. For example, consider:
FARESYSTEM NUMBER=3 FAREFROMFS=45, 70, 30
The costs of transferring from fare systems 1, 2, and 3 to fare system 3 are 45, 70, and 30 monetary units, respectively. You can include boarding fares applicable at transfers in FAREFROMFS. You must code FAREFROMFS in monetary units; the program converts to generalized cost with VALUEOFTIME. The default value is 0. FAREMATRIX |S| Optional. Name of the fare matrix for this fare system. Must be input with FILEI FAREMATI. FAREMATRIX is required for STRUCTURE=HILOW or STRUCTURE=FROMTO statements, and cannot be used for any other types. For STRUCTURE=HILOW, the row of the matrix represents the lowest fare zone traversed, and the column the highest fare zone traversed. For STRUCTURE=FROMTO, the row of the matrix represents the boarding fare zone traversed, and the column the alighting fare zone traversed. The program converts the fare, derived from FAREMATRIX, into generalized cost with VALUEOFTIME. Valid strings are standard matrix names of the type: FM.#.# or FMI.#.Name.
12
FARESYSTEM keywords (continued)

Keyword FARETABLE Subkeyword |RKV32000| Description Optional. List of X- and Y-coordinates that define the table used to compute fares for a trips length component (rather than boarding or transfer components). Other mechanisms available are UNITFARE and FAREMATRIX. You can use fare tables when STRUCTURE is DISTANCE, COUNT, or ACCUMULATE. In the coordinates, the X-axis represents trip length and the Y-axis represents the fare, in monetary units. For example, if STRUCTURE is DISTANCE, the X-axis represents distance and the Y-axis represents fare. Separate each pair of X and Y values with a comma or hyphen. Separate each pair of coordinates with a comma. For example:
FARESYSTEM NUMBER=11, NAME="FAREZONE-COUNT", LONGNAME="WITH FARE ZONES", STRUCTURE=COUNT, SAME=CUMULATIVE, FAREZONES=NI.FAREZONE, FARETABLE=1-1.00, 2-1.75, 3-2.85, 44.10, 5-5.5
or
FARETABLE=1,1.00, 2,1.75, 3,2.85, 4,4.10, 5,5.5,
When STRUCTURE is DISTANCE, the curve runs parallel to the X-axis up to the first coded point and beyond the last. Thus, if the measure of trip length is less than the first coded value of X, the fare is the first coded fare. If the measure of trip length is greater than the last coded value of X, the fare is the last coded fare. The fare, Y, must always be greater than zero, and either stay the same or increase with trip length; the fare can never decrease.
12

Keyword FARETABLE (continued) Subkeyword Description When STRUCTURE is COUNT, X values must range from 1 to the number of fare zones and increase monotonically. The fare, Y, must always be greater than zero and increase with trip length. When STRUCTURE is ACCUMULATE, X values must range from 1 to the number of fare zones and increase monotonically. The fare for each zone must be greater than zero. The program converts the fare derived from FARETABLE into generalized cost with VALUEOFTIME. FARETABLE INTERPOLATE |?| Optional. Flag that specifies interpolation between coded points in the fare table. There are two possible values: T Linear interpolation between coded points F Step function.
For example, consider:

FARESYSTEM NUMBER=2 LONGNAME="ALL" NAME="ALL" STRUCTURE="DISTANCE",SAME=SEPARATE, FARETABLE=2.5,0.50, 4.0,0.60, 10,1.2,15,1.50 INTERPOLATE=T
The fare would be 0.70 for a 5-km trip, 1.10 for a 9-km trip, and 1.32 for a 12-km trip. However, if INTERPOLATE was F, the fare would be 0.60 for both the 5-km trip and the 9-km trip, and 1.20 for the 12-km trip. INTERPOLATE only applies if STRUCTURE is DISTANCE. If STRUCTURE is COUNT or ACCUMULATE, the program assume the curve is a step function. Default value is F.
12

Keyword FAREZONES Subkeyword |S| Description Name of node variable in the input network file that contains the nodes fare zone number. Required if STRUCTURE is HILOW, COUNT, FROMTO, or ACCUMULATE. Fare zones may represent groups of nodes or single nodes. The technique for grouping nodes into fare zones depends on the fare zone system used. If STRUCTURE is HILOW, you must use an annular grouping. If STRUCTURE is COUNT, FROMTO, or ACCUMULATE, you use sequential grouping. Valid strings are standard names for node variables of the type: NI.Name. IBOARDFARE |R| Optional. Fare incurred upon boarding the first transit leg of a trip. A transit leg might take a part or the entire length of a line. The program uses the fare system of the line on which the traveler completes the first leg. You must code IBOARDFARE in monetary units. The program converts the fare into generalized cost with VALUEOFTIME. The default value is 0. LONGNAME NAME NUMBER |S| |S| |I| Optional. Second unique string identifier for a userdefined fare system. Optional. Unique string identifier for a user-defined fare system. Unique numeric identifier for a user-defined fare system. NOTE: Must be first keyword in FARESYSTEM control statement. Valid values range from 1 to 1999.
12

Keyword STRUCTURE Subkeyword |S| Description Measure unit for trip length, used to compute fares. Possible values include: FLAT Trip length is not relevant for this fare structure. Calculate fare from IBOARDFARE and FAREFROMFS. DISTANCE Trip length is in-vehicle distance, measured in user-specified units (such as miles or kilometers). HILOW Trip length is the difference between the highest and lowest fare zones crossed during the trip (an annular fare zone structure) COUNT Trip length is a measure of the number of fare zones crossed (a sequential fare zone structure). FROMTO Trip length is an attribute of the boarding and alighting fare zones. ACCUMULATE Trip length is the number of fare zones crossed. Each fare zone has an associated fare which is accumulated as the zone is traversed. This differs from COUNT, where the fare is calculated at the end of the leg or trip from the total number of fare zones traversed. FREE Defines a NULL fare system; lines with such systems give free rides. Use with caution. For this value, do not code any other FARESYSTEM keywords.
Data requirements of fare systems vary with STRUCTURE. See Fares on page 818. STRUCTURE SAME |S| Optional. String that indicates how the program calculates the fare for consecutive legs of a trip with the same fare system. Possible values: CUMULATIVE Treat consecutive legs as one leg when calculating fare SEPARATE Calculate the fare for each leg separately
The default value is CUMULATIVE.
12

Keyword UNITFARE Subkeyword |R| Description Optional. Cost per unit of the measure defined in STRUCTURE. For example, if STRUCTURE is DISTANCE, the trip cost is UNITFARE * trip distance + boarding and transfer fares. Code in monetary units. The program converts to generalized cost with VALUEOFTIME. Default value is 0. 1. n is number of fare systems
FILEI
and for important limitations when using Application Manager. Specifies files that may be input to the Public Transport program. All FILEI keywords are trigger keywords and need not be preceded by the control statement name.
NOTE: The Public Transport program allows certain types of files to have multiple files. For example LINEI can have up to 32 files. Due to
a restriction on the total number of files, fewer files than permitted for a particular file type may be active in Application Manager.
12
FILEI keywords
Keyword FACTORI Subkeyword |FKVu|
1
Description Optional. Specifies the names of the input factor files. You must code explicitly for each user class, though you can assign the same file to two or more classes. You may input up to ten input factor files, one per user class. Specify an index, [#], for each, corresponding to the classes defined by PARAMETERS USERCLASSES statement. If there is no index, the program assumes it to be 1. FACTORI is required for the route-enumeration, routeevaluation, loading, and loading-analyses processes. However, if you input a Public Transport network with NETI, do not specify FACTORI because the network contains FACTOR data. Example FACTORI for USERCLASSES=1,3-4. User class 3 and 4 use the same factors. FILEI FACTORI[1]= FACTSUC1.FAC, FACTORI[3]=FACTSUC3.FAC, FACTORI[4]=FACTSUC3.FAC See FACTORS on page 644 for a list of keywords you can use.
FACTORI
LIST
|?|
Optional. Flag that indicates whether to list the lines file as input. Y List the lines file as input N Do not list the lines file as input
Default value is N. FACTORI MAXERRS |I| Optional. Maximum number of errors allowed in the factor file before the program stops processing factors. Default value is 0. FACTORI OMITFARES |?| Optional. Flag that indicates to validate fare data in the factor file. Possible values: Y Omit validation of fare-related data in the factor file. The output network file may not be suitable for use with fares in subsequent runs of the Public Transport program. N Validate fare-related data in the factor file.
Default value is N.
12

Keyword FAREI Subkeyword |FK| Description Optional. Name of input file defining the fare systems. The file contains one or more FARESYSTEM control statements. Required if the program will consider fares during routeevaluation and skimming processes. See FARESYSTEM on page 663 for a list of keywords you can use. FAREI LIST |?| Optional. Flag that indicates whether the list the fare systems as input. Possible values: FAREMATI |FKV| Y Lists the fare systems as input N Do not list the fare systems as input
Optional. Name of the input file that contains one or more matrices used for computing fares. You may input up to 99 files. Append an index to each. If you do not specify an index, the program assumes the index is 1. Input files may contain either standard Cube Voyager binary matrices or records containing matrix data in the pattern: M,I, J, f[j],f[j+1]....f[j+n] where: M Either a name or number, depending upon how you specify FARESYSTEM FAREMATRIX. If FAREMATRIX=FMI.x.name, then M must match name. If FAREMATRIX=FMI.x.y, then M must be the table number, y (x specifies the FAREMATI index.). Row number. There must be a row for each fare zone that will use the matrix. Column number for the 1st f[j] that follows.
I J
f[j] Fare for line j, followed by the fare for line j+1 and so on. There may be multiple records for a line. Delimit files with either commas or white space.
12

Keyword LINEI Subkeyword |FKVf|2 Description Optional. Name of input file containing lines. The file can contain lines in Cube Voyager format (that is, described with the LINE control statement), or in TP+ format. You must convert any lines files in TRIPS format to Cube Voyager format. To input the lines from a Cube geodatabase stored in an MDB file, specify the file name followed by a backslash and the name of the geodatabase feature class. You may input up to 32 lines files. Append an index to each. Without an index, the program assigns an index of 1. Therefore, if inputting only one file, you need not specify an index. Indexes need not be monotonic or sequential. LINEI is required for the route-enumeration, routeevaluation, loading, and loading-analyses processes. However, if you input Public Transport network with NETI, do not specify LINEI should not be specified because the network contains line data. See LINE on page 720 for a list of keywords you can use. Valid index numbers range from 1 to 32. LINEI LIST |?| Optional. Flag that indicates whether to list the lines file as input. Possible values: LINEI MAXERRS |I| Y List the lines file as input N Do not list the lines file as input
Default value is N. Optional. Maximum number of errors permitted in lines files. When errors exceed this number, the program stops processing lines. Default value is 0. LINEI SKIPBADLINES |?| Optional. Flag that indicates whether to treat data errors as warning. Possible values: Y Downgrade data errors found when reading lines data to data warnings. The program will be able to read the entire input file without termination due to data errors. N Treat data errors as errors.
The default value is the value of PARAMETERS SKIPBADLINES.
12

Keyword LOOKUPI Subkeyword |FKV999| Description Optional. Name of file containing records for a lookup function implemented with the LOOKUP control statement. Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI. MATI |FKVf|2 Optional. Name of an input matrix file. You can define up to 10 matrix files to input. If you do not specify an index, the program assumes the index is 1. The Public Transport program only requires trip matrix files for the loading process. Because the run can compute trips, you need not input trip matrix files. Therefore, you can use the MATI keyword to input any type of matrix data into working matrices, and then manipulate, report, and output the data with MATO. Index values can range from 1 to 10. For example:
FILEI MATI[1]= TRIPSUC1.MAT, MATI[3]=TRIPSUC3.MAT, MATI[4]=TRIPSUC3.MAT
This statement names the input matrix files; the PARAMETERS TRIPSIJ statement specifies which demand matrix the Public Transport program loads for each user class.
12

Keyword NETI Subkeyword |FK| Description Name of the input network file. Files can be produced by the Network program or a previous run of the Public Transport program. Files can be a Cube binary network file or a Cube geodatabase network store in an MDB file. If specifying a Cube geodatabase network, enter the filename followed by a backslash and the name of the Cube geodatabase network. Networks produced by the Network program contain just the basic public transport infrastructure, zones, nodes, stops, and links. Networks produced by the Public Transport program are complete public transport networks. They contain, in addition to the basic infrastructure, all the components that make a public transport network: System data input with SYSTEMI Line data, input with LINEI Factor data, input with FACTORI Nontransit legs, generated with the GENERATE control statement, input with NTLEGI, or both
When produced by a Public Transport run in which trips were loaded, the public transport network may also contain nontransit and transit loads. Thus, if NETI specifies an input network produced by the Public Transport program, you need not provide SYSTEMI, FACTORI, NTLEGI and LINEI files unless you invoke the Public Transport Network Development function. In this case, the program only takes the basic network infrastructure from the NETI file; you must supply all other components.
12

Keyword NTLEGI Subkeyword |FKVf|2 Description Optional. Name of input files containing nontransit legs. To input the nontransit legs from a Cube geodatabase stored in an MDB file, specify the file name followed by a backslash and the name of the geodatabase feature class. You can define up to 32 input files. Append each keyword with an index, such as NTLEGI[5]. The GENERATE READNTLEGI statement defines valid indexes that the program will process. Indexes need not be monotonic or sequential. If you do not specify an index, the program assumes the index is 1. See NT on page 734 for a list of keywords you can use. Index values can range from 1 to 32. ROUTEI |FKVu|1 Optional. Name of the input route files. Explicitly specify a unique file for each user class. You can define up to 10 route files to input, one per user class. Append each keyword with the index of the user class. The PARAMETERS USERCLASSES statement defines user classes. If you do not specify an index, the program assumes the index is 1. When you define an input route file for a user class, the program bypasses the route-enumeration process for that user class. You can define input route files for some user classes and generate them for other user classes. Index values can range from 1 to 10 (the number of user classes). For example, consider:
FILEI ROUTEI[1]= ROUTESUC1.RTE, ROUTEI[3]=ROUTESUC3.RTE, ROUTEI[4]=ROUTESUC4.RTE
This statement defines input route files for user classes 1, 3, and 4; each user class has its own route file. ROUTEI I |IV1000| Optional. List of origin zones for the route-evaluation, skimming, loading, and loading-analyses processes. Specify origin zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. Valid values range from 1 to the networks highest zone number.
12

Keyword ROUTEI Subkeyword J |IV1000| Description Optional. List of destination zones for the routeevaluation, skimming, loading, and loading-analyses processes. Specify destination zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. Valid values range from 1 to the networks highest zone number. ROUTEI REPORTI |IV1000| Optional. List of origin zones for reporting evaluated routes. The program writes the report to file specified with REPORTO. Specify origin zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. Valid values range from 1 to the networks highest zone number. ROUTEI REPORTJ |IV1000| Optional. List of destination zones for reporting evaluated routes. Specify destination zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. Valid values range from 1 to the networks highest zone number. See Evaluated routes on page 762 for an example of this report.
12

Keyword ROUTEI Subkeyword SELECTBYMAT |S| Description Optional. Matrix used to produce I and J selections such that the program only performs the evaluation, skimming, loading, and loading-analyses processes for Is and Js that have trips from and to them. Normally, you specify the trip matrix being loaded. For example, MI.x.NAME. You can use another filter so the program performs the processes only for the I-J pairs that have trips between them:
PROCESS PHASE=SELECTIJ IF(TRIPSIJ==0)CONTINUE ENDPROCESS
You can use the I, J, and SELECTBYMAT subkeywords together. The program merges them to produce the final I and J lists. ROUTEI TRACEI |IV1000| Optional. List of origin zones for printing evaluated routes. Routes are reported in the file specified by REPORTO, using the tabular-format route report. Specify origin zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. Valid values range from 1 to the networks highest zone number. ROUTEI TRACEJ |IV1000| Optional. List of destination zones for printing evaluated routes using the tabular-format route report. Specify destination zones with single numbers or pairs of numbers separated by a dash. Use commas to delimit each number or pair. Valid values range from 1 to the networks highest zone number. SCREENLINEI |FK| Optional. Name of a screenline file that produces intercept data for Public Transport matrix estimation. You can create the file with Cube or a text-file editor. The file must use the link-count format used by Cube Analysts Matrix Estimation program; the turns-count format is not supported. The file contains the definition of the screenlines (in terms of constituent links), along with link count and confidence-interval data.
12

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

Keyword TURNPENI Subkeyword |FKV2| Description Optional. Names of one or two turn-penalty files. Usually written by the Highway program, these files contain records detailing turn penalties or prohibitions. Turn penalty movement records have the following format:
A B C Set Penalty
where: A is the entry node to the intersection B is the intersection node C is the exit node. Set is a number in the range 1-8; you select which sets the model uses. Penalty is either -1 to indicate a prohibited turn in the Highway model or the value of the junction delay, measured in minutes.
You can enter one set per record. Separate the data fields in a record with white space (either a space or a comma). NOTE: As transit vehicles follow user-defined routes (which can differ from general traffic), they ignore banned turns and only use the junction delay data. Turn penalty movement records cannot contain function specifications. Most model runs that incorporate junction delays require one turn-penalty input file. However, for forecast years, model runs require two turn-penalty input files, one with base-year delays and one with forecast-year delays. For such runs, you support an incremental approach for forecast years by controlling a lines travel times with RUNTIME RT or NNTIME.
12

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

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

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

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

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

Keyword LINKO Subkeyword BYCLASS |?| Description Optional. Flag indicating whether outputs are summed by user class in the links file. Possible values: Y Program writes the run totals, summed by user class, and the attributes used in the run for each user class. User classspecific fields have names with suffixes, like _1 and _2. N Program writes data not separated by user class
Default value is N. LINKO FMVOLS |?| Optional. Flag indicating whether outputs from a crowding run contain demand volumes or flowmetered volumes. Possible values: Y Program writes the flow-metered volumes from the crowding run. N Program writes the loaded volumes (represents the demand volumes for crowding runs).
Default value is N. LINKO LINES |?| Optional. Flag indicating whether lines data is included in the output links file. Possible choices: LINKO NTBYLINK |?| Y Include line per link data. N Do not include line data.
Default value is Y. Optional. Flag indicating treatment of nontransit legs in output file. Possible values: Y Converts records of nontransit legs to the corresponding sequence of underlying links in the network (as defined by the XN keyword in the NTLEG control statement). From the output, you can obtain true nontransit loads for walk links, and so forth. N Does not convert records of nontransit legs.
Default value is N.
12

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

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 687). Do not use ONOFFS when ONELINKREC is set to Y.
12

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

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

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

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

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 734. N Do not output nodes between the start and end nodes of nontransit legs.
Default value is Y. PRINTO |FK| Optional. Name of an output file, which you have defined in a PRINT FILE control statement. Use the PRINT control statement to format data items and write them as a single line to the standard printed output, to a file, or to both the standard output and a file. REPORTO |FK| Name of the file to which the program writes reports from the route-enumeration and routeevaluation processes. All diagnostics from these processes are output to the standard Public Transportprogram print file.
12

Keyword ROUTEO Subkeyword |FKVu|1 Description Optional. Name of output file containing enumerated routes. Explicitly specify a unique file for each user class. You can define up to 10 output files, one per user class. Append each keyword with the index of the user class. The PARAMETERS USERCLASSES statement defines user classes. If you do not specify an index, the program assumes the index is 1. The statement ROUTEO[x] invokes the routeenumeration process for user class x. You can input previously created enumerated-route files for some user classes and build files for other user classes in the same run. ROUTEO I |IV1000| Optional. List of origin zones for which the program enumerates routes and saves. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to the networks highest zone number. By default, the program enumerates and saves routes originating from all zones. ROUTEO J |IV1000| Optional. List of destination zones for which the program enumerates routes and saves. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to the networks highest zone number. By default, the program enumerates and saves routes bound for all zones.
12

Keyword ROUTEO Subkeyword REPORTI |IV1000| Description Optional. List of origin zones for which the program reports enumerated and evaluated routes. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. The program only includes route evaluations completed by the skimming, loading, or loadinganalyses processes. The program reports routes in the file specified in REPORTO. Valid values range from 1 to the networks highest zone number. ROUTEO REPORTJ |IV1000| Optional. List of destination zones for which the program reports enumerated and evaluated routes Specify the list as a set of single numbers or dashseparated pairs of numbers that specify a range. Delimit each number or pair with a comma. See Enumerated routes on page 761 and Evaluated routes on page 762 for examples of these reports. Valid values range from 1 to the networks highest zone number. ROUTEO SELECTBYMAT |S| Optional. Matrix used to produce I and J selections such that the program enumerates and saves routes only for the Is that have originating trips and the Js that have terminating trips. Normally, specify the trip matrix being loaded. For example, MI.x.NAME. For the evaluation, skimming, loading, and loadinganalyses processes, you can filter to select only those I-J pairs that have trips between them:
PROCESS PHASE=SELECTIJ IF(TRIPSIJ==0)CONTINUE ENDPROCESS
Together, all three subkeywords are merged to produce the final I and J lists.
12

Keyword ROUTEO Subkeyword TRACEI |IV1000| Description Optional. List of origin zones for which the program prints evaluated routes using the tabular-format route report. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. The program reports routes in the file specified in REPORTO. Valid values range from 1 to the networks highest zone number. ROUTEO TRACEJ |IV1000| Optional. List of destination zones for which the program prints evaluated routes using the tabularformat route report. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. See Evaluated routes on page 762 for examples of these reports. Valid values range from 1 to the networks highest zone number.
12

Keyword SCREENLINEO Subkeyword |FKV10| Description Optional. Name of the screenline file the program writes from the network data. Explicitly specify a unique file for each user class. The file contains screenline definitions and count and confidence-level data. You pass this file with an associated intercept file to a Cube Analyst run to perform matrix estimation tasks. You can define up to 10 output files, one per user class. Append each keyword with the index of the user class. The PARAMETERS USERCLASSES statement defines user classes. If you do not specify an index, the program assumes the index is 1. The program ignores this keyword if you specify the SCREENLINEI keyword. Cube Analyst will read that file instead. Use subkeywords to specify the source or value of the data fields that the program writes to the file. You can reference variables, such as li.varname or lw.varname. Alternative, you can use a subkeyword to read a variable from the input network, such as CONFAR=varname. SCREENLINEO CONFVAR |S| Optional. Name of the input networks link variable that contains confidence-level data. The confidence level is expressed as an integer value, ranging from 1 to 10000. You must define either CONFVAR or DEFCONF. Use the DEFCONF keyword when a single confidence-level value applies to all links. SCREENLINEO SCREENLINEO COUNTVAR DEFCONF |S| |I| Name of the input networks link variable that contains the link-count data. Optional. Confidence level that applies to all output links. If confidence levels vary from link to link (or screenline to screenline), use the CONFVAR subkeyword. Valid values range from 1 to 10,000.
12

Keyword SCREENLINEO Subkeyword MEUSESNT |?| Description Optional. Flag indicating whether link use is restricted to transit modes. Possible values: Y Program creates intercept data, considering link use of all modes (that is, transit and nontransit) N Program restricts link use to only transit modes.
Default value is taken from PARAMETERS MEUSESNT, if specified; otherwise Y. SCREENLINEO SCREENVAR |S| Name of the input networks link variable that contains the screenline number. This variable has a value ranging from 1 to 9999 when a link forms part of a screenline, and a zero value for all other links.
12

Keyword STOP2STOPO Subkeyword |FKV4| Description Optional. Name of file where the program saves the results of the stop-to-stop analyses. File is either DBF format or MDB format. To save results in the Cube geodatabase (in MDB format), specify the file name followed by a backslash and the name of the geodatabase feature class. You can specify up to four output files. Therefore, you can output a number of different analyses from a single run of the program. Use subkeywords to select the types of stop-to-stop movements captured. The data saved to the file can relate to a selection of stop-nodes or groups of stop-nodes. The saved file contains the following data fields: Origin zone (I) Destination zone (J) From stop group (FROMGROUP) To stop group (TOGROUP) From stop node (FROMNODE) To stop node (TONODE) Mode (MODE) Movement type (ACCUM) 1=FIRSTLAST 2=ADJACENT 3=ALLONOFFS 4=FIRSLASTBYMODE 5=ADJACENTBYMODE Number of passengers (VOL) NOTE: The file contains either FROMGROUP and TOGROUP or FROMNODE and TONODE, but not both. The two sets of data fields are mutually exclusive. See More on stop-to-stop analysis on page 705.
12

Keyword STOP2STOPO Subkeyword ACCUMULATE |S| Description Optional. Specifies types of transit movements included in the stop-to-stop analysis. Possible types include: FIRSTLAST Movements from a trips first node to last node. ADJACENT Movements for each leg of a trip. ALLONOFFS Movements for all on-off combinations. FIRSTLASTBYMODE Movements from first node to last node on a particular mode, regardless of intervening modes. Must specify MODES subkeyword. ADJACENTBYMODE Through movements from first node to last node on a particular mode. Must specify MODES subkeyword.
All movement types other than ADJACENT can contain one or more transit legs. See More on stop-to-stop analysis on page 705. Default value is FIRSTLAST. STOP2STOPO GROUPEDMODES |IV999| Optional. List of numbers the program uses to recode the modes on transit legs before completing stop-to-stop analysis on a route. (Relevant when transit movement type is ADJACENTBYMODE or FIRSTLASTBYMODE). First number is the mode number assigned during recoding; subsequent numbers are the modes recoded. Thus, any transit legs with modes listed in the second are subsequent positions are assigned to the mode listed first. For example, consider:
GROUPEDMODES = 3,6,7,8
The program recodes any transit legs using modes 6, 7, or 8 to mode 3. Valid values range from 1 to the networks highest mode number.
12

Keyword STOP2STOPO Subkeyword GROUPS |IV9999| Description List of stop-groups for which the program extracts stop-to-stop movements for the ACCUMULATE subkeyword. Identify stop-groups by number. Stop-groups are either single stop-nodes or a collection of stop-nodes, such as platforms within a station or clusters of bus stops on either side of a road. You define a nodes stop-group number on the input networks node record in the variable specified in STOPGROUP. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. If you code both GROUPS and NODES, the program outputs stop-to-stop movements for the specified groups that will include only the specified nodes. Thus, you can exclude nodes from their groups. If you do not code NODES, the program includes all nodes belonging to the specified groups in the analysis. Note that the program does not explicitly report nodes in the output file. NOTE: If you code neither NODES nor GROUPS, the program generates a fatal error. Valid values range from 1 to the networks highest stop-group. STOP2STOPO LIST |?| Optional. Flag indicating whether to list the contents of the DBF file to the printer file. Possible values: Y List contents of the DBF file to the printer file N Do not list of contents of the DBF file to the printer file
Default value is N.
12

Keyword STOP2STOPO Subkeyword MODES |IV999| Description Optional. List of modes for which the program accumulates stop-to-stop movements when ACCUMULATE is FIRSTLASTBYMODE or ADJACENTBYMODE. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to the networks highest mode. Default value is all modes. STOP2STOPO NODES |IV9999| List of stop nodes for which the program extracts stop-to-stop movements for the ACCUMULATE subkeyword. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. This subkeyword is required if GROUPS is not coded. Valid values range from 1 to the networks highest node. STOP2STOPO STOPGROUP |S| Optional. Name of the node variable that contains the stop-group number. If you code GROUPS, you must code STOPGROUP. For example, with STOPGROUP=SGNAME, then the node variable NI.SGNAME stores the stop-group numbers, used in GROUPS. When using stop groups, the program reports on intragroup movements, but cannot disaggregate those movements to the nodes in the group. 1. u represents user class
Example
Some files that may be output by the Public Transport program.

FILEO NETO = onetwork.net REPORTO = reports.prn ROUTEO = enumroute.rte, I=1,15,24, J=1,24, REPORTI=1,15,24 REPORTJ=1,9, 15,24
12
Example of SCREENLINEO & INTERCEPTO

RUN PGM=PUBLIC TRANSPORT FILEO REPORTO = "PAPTR00B.PRN" FILEO ROUTEO[1] = "PAPTR00B.RTE" FILEO SCREENLINEO = "PT ANALYST EXAMPLE\PAPTR00B.DAT", SCREENVAR=SCRLNO COUNTVAR=PTCOUNT CONFVAR=PTCONF FILEO INTERCEPTO = "PAPTR00B.ICP" FILEI NETI = "PAPTR00D.NET" ; PT network output from PT program ENDRUN
Considerations on numeric formats

Traditionally planners have maintained most transportation planning matrices in integer format. Advantages included: Integer values take less space than floating point values Matrix values usually can be represented with numbers where a fixed decimal place can be assumed.
In the past, computers could process integers much faster than floating point numbers. However, this is not necessarily true with newer computers. Single-precision floating point provides only six to seven digits of precision, and cannot always maintain the precision required for certain types of matrices. Cube Voyager processes all matrices in double-precision (16 digits) format to accommodate a wider range of values, and to not lose precision or accuracy when computing. However, writing double-precision numbers to the matrix files would generate very large files, and in most cases, only a few decimal places are required for each cell value. Therefore, the Public Transport program stores matrix values with a special packing routine that tries to minimize the files space requirements. The Public Transport program tries to convert each number to an integer starting with 0 decimal places and continues with the next power of 10 until it reaches the maximum DEC level specified. The
12
program uses the lowest level that converts to an integer with no loss of precision. If a scaled cell value is too large to fit within a 32bit integer, the program stores the cell as a double-precision value. If DEC is D or S, the program skips the integer conversion attempt and stores all cells as either 8-byte double values or 4-byte single values. If not specified, DEC defaults to 2. For example, consider a cell computed as 10/3. The result is 3.33333333.... to sixteen digits. When changed to single precision, the result is accurate to about seven digits, requiring four bytes to store. If converted to an integer while DEC is 0, the result is 3, and the cell would require only one byte to storea significant reduction. However, that might not be precise enough for the programs that read it. If DEC is 2 for that number, the resulting integer is 333, requiring two bytes to store. Upon reading, another application will automatically restore the number to 3.33. If DEC were S, the value would be stored as a 4-byte single-precision, and if DEC were D, it would be stored as an 8-byte double-precision. The S and D formats require more storage space.
More on stop-to-stop analysis

For stop-to-stop analysis, the movement type affects the output records. When the movement type is 4 or 5 (ACCUMULATE is FIRSTLASTBYMODE or ADJACENTBYMODE), the program writes output records that reflect the modes used in the routes transit legs. The program analyzes a transit route based on the values of other STOP2STOPO subkeywords, and saves the appropriate records. Use the GROUPEDMODES subkeyword to recode modes prior to transit-route analysis. With this keyword, you can group distinct modes of the route together, allowing them to appear as one mode for analysis and in subsequent data output. For example, a model might use two or more mode numbers for different types of rail travel. You might be more interested in transfer to or from rail than in changes between the different rail modes. By grouping the discrete rail modes together, you eliminate this detail from the analysis.
12
Example of ACCCUMULATE subkeyword
Suppose you have a five-leg, two-mode trip:

1. 1-2 on mode 1 2. 3-4 on mode 1 3. 5-6 on mode 2 4. 7-8 on mode 1 5. 9-10 on mode 1
Value of ACCUMULATE FIRSTLAST ADJACENT ALLONOFFS FIRSLASTBYMODE Movements analyzed 1-10 1-2, 3-4, 5-6, 7-8, 9-10 1-2, 1-4, 1-6, 1-8, 1-10, 3-4, 3-6, 3-8, 3-10, 5-6, 5-8, 5-10, 7-8, 7-10, 9-10 1-10 mode 1 5-6 mode 2 1-4 mode 1 5-6 mode 2 7-10 mode 1
ADJACENTBYMODE
GENERATE
Generates nontransit legs in the public transport network. You can generate, input, or generate and input nontransit legs. You can use one or more GENERATE control statements to generate nontransit legs, each with different criteria. Use the READNTLETI keyword to input previously generated and validated nontransit legs or externally generated ones. The Public Transport program maintains one table of nontransit legs. The program dynamically updates the table while processing GENERATE statements. The program keeps one leg for each AnodeB-node combination in the tablethe leg with the lowest EXTRACTCOST, followed by the leg with the lowest distance (DIST ),
12
and then the leg with the lowest NTLEGMODE. After processing all GENERATE statements, the program saves the legs in the table to the Public Transport network file specified by NETO and/or the file specified by NTLEGO. If you specify neither file, the program discards the legs at the end of the run. Use the necessary keywords to control the nontransit linkgenerating process produced by the GENERATE statement. With this statement, the program: Builds minimum-cost routes between each node specified with FROMNODE to each node specified with TONODE that is a transit stop. The program ignores nodes specified in TONODE that are not stop nodes. Finds transit modes at each node specified in TONODE, computes the cost to the node, and compares the cost to the modes MAXCOST. If the cost for at least one of the modes is less than the modes MAXCOST and if the specification in DIRECTLINK is satisfied, the program saves the leg. Examines each saved leg, adding acceptable legs to the legs table. The program adds the best leg for a mode, and legs that service that same mode and whose cost does not exceed the cost of the best leg for that mode plus the SLACK for that mode. If SLACK is not specified, the slack for a mode effectively becomes the difference between the best cost and the MAXCOST for the mode. MAXNTLEGS specifies the maximum number of legs the program will generate for a mode from a FROMNODE. Merges legs using any special transaction codes. For example, you might specify that the program replace a generated leg with a longer leg. See NTLEGI under FILEI on page 670.
None of the GENERATE keywords are trigger keys; you must code all keywords on a GENERATE control statement.
GENERATE statements must be in the DATAPREP phase.
12
GENERATE keywords
Keyword ACCESSLINK |R| Description Optional. One or more access links from park-and-ride facilities to stop nodes. Specify an access link as:
A-S,cost,distance
where: A Surrogate access point (integer) S Stop node (integer) cost Optional. Cost of using this access link (real). distance Optional. Distance traveled on this access link (real).
Separate each access link with a comma. If the link does not exist in the network, the program generates the link. You specify pairs of numbered sets. Paired values indicate the start of new access links. Enter paired values in the correct order to avoid generating an error. If you specify ACCESSLINK, the program ignores any TONODE keywords. The program obtains the cost from the route to the A-node. If ACCESSLINK provides numeric values for cost and distance, the program adds them to the links cost and distance. If ACCESSLINK only contains one value, the program adds that value to the links cost. Valid values for A and S are 1 to the networks highest node number.
12
GENERATE keywords (continued)

Keyword COST |N| Description Expression for computing network link costs. Used to determine the minimum-cost nontransit legs between the nodes specified in FROMNODE and TONODE (or ACCESSLINK). Enclose expressions in parentheses. The expression can contain network data items, such as link distance, time, and speed. The cost of nontransit legs may be the cost on the basis of which they are built or, you can skim the cost specified by EXTRACTCOST from the network links underlying the nontransit legs. For example, consider:
GENERATE, COST=li.Distance, EXTRACTCOST=li.Time, NTLEGMODE=32
This script fragment generates nontransit legs on the basis of minimum distance, but skims time along the minimum-distance legs and saves as the cost. To obtain the perceived nontransit cost, you can factor the nontransit leg cost, derived from COST or EXTRACTCOST, with the FACTORS RUNFACTOR control statement, which is specified by mode. The sample script fragment produces nontransit legs with a mode of 32. You can factor with RUNFACTOR[32]=x.x. The route-enumeration and evaluation processes use perceived (or factored) costs; both actual and perceived costs may be skimmed. DIRECTION |I| Optional. Integer indicating direction of the generated nontransit legs. Possible values: DIRECTLINK |I| 1 Forward direction, FROMNODE to TONODE 2 Reverse direction, TONODE to FROMNODE 3 Both directions, FROMNODE to and from TONODE
Default value is 3. Optional. Maximum number of network links a nontransit leg can traverse. By default, the program applies no limit to number of links. EXCLUDELINK |N| Optional. Expression that computes the network links to exclude from the generation of nontransit legs. Enclose expressions in parentheses. You may exclude links from the GENERATE process with network data items, such as link distance, cost, and classifiers.
12

Keyword EXTRACTCOST |N| Description Optional. Expression that computes the network link costs skimmed from nontransit legs built on the basis of COST. The skimmed costs become the costs of the nontransit legs. Enclose expressions in parentheses. The expression can use network data items, such as link distance, time, and speed, to compute the cost. If you do not specify this keyword, the program derives the cost of nontransit legs from the COST keyword. To compute perceived nontransit costs for use in the enumeration and evaluation processes, you can factor the nontransit leg-cost derived from COST or EXTRACTCOST with the FACTORS RUNFACTOR control statement. FROMNODE |S| Optional. Node or list of nodes that program generates nontransit legs from. You may specify nodes as numeric values or names of variables that store valid numeric values. For example, you might specify:
FROMNODE=1-NUMZONES
Valid values range from 1 to the networks highest node number. INCLUDELINK |N| Optional. Expression that computes network links included in the generation of nontransit legs. Enclose expressions in parentheses. The expression can use network data items, such as link distance, cost, and classifiers, to determine included links. LIST |?| Optional. Flag indicating whether to list nontransit legs. Possible values: T List each nontransit leg and the network links traversed. F Do not list nontransit legs.
Default value is F. See More on using LIST keyword on page 714.
12

Keyword MAXCOST |RVt*|1 Description Maximum cost allowed for a particular transit mode to enable generation of nontransit legs. Specify cost per mode. The program generates a leg to a TONODE serviced by a transit mode only when the cost to that node is less than the MAXCOST for that transit mode. You must specify MAXCOST for at least one mode. The default value is 0. Therefore, the program generates no trips to nodes serviced by modes without a MAXCOST specified, unless other non-zero modes service the node. When determining the maximum cost for a leg, the program uses the mode of the TONODE. However, if the TONODE specifies a zone, the program uses the mode of the FROMNODE. The value of SLACK affects the value of MAXCOST. Valid values are 0 to 500 (in the same units specified in COST). MAXNTLEGS |IVt|
1
Optional. Maximum number of nontransit legs to generate for a particular transit mode from a FROMNODE to a TONODE serviced by that mode. Valid values range from 1 to 999. Default value is 5. If both FROMNODE and TONODE are zones, the program ignores MAXNTLEGS.
MINCOST
|RVt*|1
Optional. Minimum cost allowed for a particular transit mode to enable generation of nontransit legs. Specify cost per mode. The program generates a leg to a TONODE serviced by a transit mode only when the cost to that node is more than the MINCOST for that transit mode. When determining the minimum cost for a leg, the program uses the mode of the TONODE. However, if the TONODE specifies a zone, the program uses the mode of the FROMNODE. Valid values are 0 to 500 (in the same units specified in COST). Default value is 0.
NTLEGMODE
|I|
Nontransit mode assigned to the generated nontransit legs. Valid values range from 1 to 999. You must specify a value.
ONEWAY
|?|
Optional. Flag indicating how to use one-way links when generating nontransit legs. Possible values: F Permits one-way links to be traversed in both directions T Restricts one-way links to the coded direction
Default value is T.
12

Keyword READNTLEGI |I| Description Optional. Index number of the input nontransit leg file. You must code a corresponding FILEI NTLEGI statement. When you code READNTLEGI, the program reads nontransit legs from a file and merges them into the generated links table. The NT control statement determines the format of the input records. Delimit data fields with commas or spaces. Use FROMNODE and TONODE with READNTLEGI to filter input records through the from- and to-nodes. No other keywords are valid with READNTLEGI. Use a separate GENERATE statement for each nontransit leg file input. Valid values range from 1 to 7. SLACK |RVt|
1
Optional. Amount added to the best-cost nontransit leg between the two nodes to determine the maximum cost of legs saved. Specify per mode. SLACK provides a secondary control for restricting the generation of nontransit legs. MAXCOST provides the primary control. The program generates legs from a FROMNODE to a TONODE if their costs is less than or equal to MAXCOST for the mode that services the TONODE. With SLACK specified, the program only generates legs from a FROMNODE to a TONODE if their costs is also less than or equal to the best cost between the nodes plus the SLACK for the mode that services the TONODE. For example, consider:
MAXCOST[4]=20, SLACK[4]=8
If the best leg has a generalized cost of 6 minutes, the program will save legs with a cost up to 14 minutes. If you do not specify SLACK, the program only uses MAXCOST to limit nontransit-leg generation. If SLACK is set to zero, the program only saves the best-cost legs. SLACK generally refers to the modes serviced by the TONODE. However, if the TONODE is a zone, the program obtains the mode from the FROMNODE. If both FROMNODE and TONODE are zones, the program ignores SLACK. Valid values are 0 to 500 (in the same units specified in COST). Default value for any mode is the value of MAXCOST for that mode.
12

Keyword TONODE |S| Description Optional. Node or list of nodes to which the program generates nontransit legs. Specify nodes as numeric values or names of variables that store valid numeric values. The program ignores TONODE if the GENERATE control statement contains the ACCESSLINK keyword. Valid values range from 1 to the networks highest number. By default, set to include all nodes (number of zones +1 to the networks highest node number). XFERMETHOD |I| Optional. Integer that specifies algorithm program uses to execute GENERATE control statement. Version 4.1 introduced a new algorithm that creates nontransit legs between pairs of nodes where a transit line operates. Earlier versions excluded such legs, possibly preventing valid routes. Possible values: 0 Use the latest algorithm (currently, the algorithm developed with version 4.1). Use this setting when modeling best-path routes (that is, when FACTOR BESTPATHONLY=T ). 1 Use the algorithm from version 4.0 when creating nontransit legs. 2 Supplement the version 4.0 algorithm for generating connectors with the additional connectors created with the version 4.1 algorithm. The program creates an initial set of nontransit legs using keywords such as MAXCOST, MAXNTLEGS, and SLACK as in version 4.0. Next, the program uses the version 4.1 algorithm to create additional legs, using the maximum costs from the initially-generated legs as limits. The total number of legs generated might exceed limits specified in MAXNTLEGS. This value is appropriate for models developed under version 4.0, if you wish to use newly identified connectors while not losing any previously generated connectors. 3 Use the algorithm from version 4.1 (currently the same result as setting to 0).
Default value is 0. 1. t indicates number of transit modes
12
Example
The first GENERATE statement produces access legs from zones to the public transport system and egress legs in the reverse direction. The second GENERATE statement produces transfer legs between stops.
PHASE=DATAPREP //Note: the GENERATE command must precede controls //GENERATE 1: Access and Egress links for zones 11272 GENERATE, NTLEGMODE=100, MAXCOST=20*20.0, COST=li.time, FROMNODE=1-1272, TONODE=1273-5644, DIRECTION=3, INCLUDELINK=(li.LINKTYPE=30-32), SLACK=20*5. MAXNTLEGS=20*5, DIRECLINK=5 //GENERATE 2: Transfer legs for the PT Network GENERATE, NTLEGMODE=100, MAXCOST=20*10., COST=LI.Distance*60/4.80, FROMNODE=1273-5644, TONODE=1273-5644, DIRECTION=3, INCLUDELINK=(li.LINKTYPE=1,4,8-13,20,30-32), SLACK=20*5., MAXNTLEGS=5, ENDPHASE
More on using LIST keyword

You may use one or more GENERATE statements to generate nontransit legs. While processing statements, the program adds legs to a table of nontransit legs. The table stores exactly one leg for each combination of A-node and B-nodethe one with the lowest EXTRACTCOST, followed by the one with the lowest distance (DIST ), followed by the one with the lowest NTLEGMODE.
12
If a GENERATE statement has LIST set to T, the program lists the legs in the table when that statement is processed. Though the program might list a leg during GENERATE, that leg might not be included in the final table of legs. Similarly, a GENERATE statement might list one leg, and a later GENERATE statement a different leg, if the later statement revises the leg. To view or report the final set of nontransit legs, save them to the file specified with the FILEO NTLEGO control statement. The following example illustrates this process:
LIST='GEN1' GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1, NTLEGMODE = 36, LIST=T, DIRECTION=3, FROMNODE=1, TONODE=2052 LIST='GEN2' GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1, NTLEGMODE = 36, LIST=T, DIRECTION=3, FROMNODE=1, TONODE=2052 LIST='GEN3' GENERATE COST=(li.distance), EXTRACTCOST=(lw.xcost), MAXCOST=12*1, NTLEGMODE = 35 LIST=T, DIRECTION=3, FROMNODE=1,TONODE=2052
The printed result of this will be:

GEN1 Link 1 2052 36 0.18 Link 2052 1 36 0.18 GEN2 GEN3 Link 1 2052 35 0.18 Link 2052 1 35 0.18 M(625): 2 Nontransit Legs 0.36 0.36 1 3674 1 3674
0.36 0.36
1 3674 1 3674
The final nontransit legs saved will be: 1 - 2052 - 35 (and reverse)
GOTO
GOTO label
12
Example
In this example, the GOTO statement passes control in the forward and backward directions.
GOTO hwybuild ..... ..... :hwybuild IF (expression) GOTO
:hwybuild
IF... ELSEIF ... ELSE ... ENDIF

Performs certain operations based on conditions. There are two forms of this control statement: A single statement:
IF (expression) statement
A block of statements:
IF (expression) ELSEIF (expression) ELSE (expression) ENDIF
You must predefine any expression variables in an earlier COMP VAR statement. (The program automatically defines any variables not predefined, but with a dot (.) in their name as numeric variables.) You may nest but not overlap IF... ELSEIF ... ELSE ... ENDIF blocks. They may not overlap LOOP ... ENDLOOP blocks. You may append the following control statements to a single IF statement:
BREAK
12
COMP CONTINUE EXIT GOTO PRINT
Example
Two of uses of the single IF statement.

IF (matrix.time_to_bcd > 200000) GOTO :SKIPZONE IF (expression) EXIT
One example of the IF block statement.

IF((j=3-5,6-30,57 & k=(2*j-4)) || ((J*k) = 14-20,56)) .... ELSEIF (loop_cntr > 10) .... ELSEIF (loop_cntr > 5 && diff.time < 32) .... ELSE .... ENDIF
JLOOP ... ENDJLOOP

Controls a loop over the column cells (J) of the current row (I) in a matrix. Each row represents an origin (I) zone and each column represents a destination (J) zone. Typically, you use JLOOP ... ENDJLOOP blocks for matrix computations that you cannot complete with a single COMP MW control statement.
JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks.
12
JLOOP keywords
Keyword J |I| Description Optional. List of up to three integers that define the value of the loop control variable. You may define each integer with an expression. Specify as:
J=Jbeg, Jend, Jinc
where: Jbeg defines the initial value of the loops control variable, J. Default value is 1. If you do not define Jbeg, you cannot define Jend or Jinc. In that case, Jend defaults to the number of zones in the network, and Jinc defaults to 1. Jend defines the terminal value of the loops control variable, J. Valid values range from 1 to the networks maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1. Jinc defines the increment for the loops control variable, J. If not specified, set to 1 or -1, depending on the direction from Jbeg to Jend.
Because the list of values for J can be expressions, you must separate the values with commas. Enclose expressions containing commas in parentheses.
A JLOOP block causes the program to loop between the JLOOP statement and its ENDJLOOP statement, moving J from Jbeg to Jend in increments of Jinc. The logic for JLOOP and ENDJLOOP processing is: At JLOOP: If J is specified, establish values for Jend and Jinc. Else set J=1, Jend=Zones, Jinc=1. If (J < 1 or J > Zones or Jend <1 or Jend > Zones), terminate fatally. Process statements within JLOOP. At ENDJLOOP: Add Jinc to J. If (Jinc > 0 and J <= Jend) go to statement following JLOOP. If (Jinc < 0 and J >= Jend) go to statement following JLOOP. Control passes to statement following ENDJLOOP.
12
The program processes all statements between the JLOOP and ENDJLOOP statements, including COMP MW statements, with the current value of J. The following statements are valid within a JLOOP block:
BREAK COMP CONTINUE EXIT GOTO (:label statement must be inside current JLOOP) IF... ELSEIF ... ELSE ... ENDIF PRINT
JLOOP processing varies by phase.

Phase NODEREAD and LINKREAD1 DATAPREP1 MATI and MATO JLOOP processing Program executes JLOOP for each node or link processed. Program executes JLOOP once. Program executes JLOOP once per matrix row (or origin zone). You may use J keyword to select destination zones. JLOOP is invalid (the phase is executed once per IJ pair)
SELECTIJ and SKIMIJ
1. Program performs no matrix processing during these phases. Therefore, there is no destination zone. However, JLOOP statements are valid, and will act as a zonal loop.
12
Example 1
Compute the sum of each row for two matrices.

ROWSUM1 = 0 ROWSUM3=0 JLOOP ROWSUM1 = ROWSUM1 + MW[1] ROWSUM3 = ROWSUM3 + MW[3] ENDJLOOP
Example 2
Print the first ten cells of each row.

JLOOP J=1,25 TRIPSIJ=MI.1.1 * 0.75 IF(J > 10) BREAK PRINT LIST=I, J, TRIPSIJ ENDJLOOP
LINE
Describes the attributes of public transport lines, including the nodes the line traverses and attributes of those nodes.
LINE keywords describe the lines attributes. Some are required;
some are optional. None are trigger keys; you must code all keywords on a LINE control statement. You may input lines to the Public Transport program in ASCII format, in up to seven files with FILEI LINEI, or in the Public Transport network file with FILEI NETI. The Public Transport program outputs lines to the binary Public Transport network defined by FILEO NETO and to the ASCII file defined by FILEO LINEO. When crowding is used, the Public Transport programs Loading Models append results of a crowd run to the output LINE data with the FMCAPACITY keyword.
12
Lines traverse two or more nodes, which you define with the NODES keyword. Nodes have their own attributes, defined with subkeywords (ACCESS, ACCESS_C, DELAY, DELAY_C, NNTIME, RT, SPEED, TF, TIME, and XYSPD). The Public Transport programs loading models append the results of the loading process to line nodes, using the keywords FMOFF, FMON, FMVOL, OFF, ON, and VOL. These data items form part of an output FILEO LINEO file, but the program does not read this data when processing a FILEI LINEI file. Several of the LINE keywords and NODES subkeywords adjust network link times by line. See Calculation of line/link times on page 730 for an explanation of how they interact with each other to produce the adjusted link times.
LINE keywords
Keyword NAME ALLSTOPS Subkeyword |S| |?| Description Unique string identifier for a transit line. NAME must be the first keyword in a LINE control statement. Optional. Flag indicating whether all nodes in the line are stop nodes. Possible values: CIRCULAR |?| T Program makes all the lines nodes into stop nodes, even those explicitly designated as nonstop nodes. F Program uses node designation.
Default value is F. Optional. Flag indicating whether a line is circular or linear. Possible values: T Indicates line is circular. F Indicates line is linear.
Default value is F. The first and last node of a circular line must be the same node and both boarding and alighting can take place at this node. A route can go through this node without incurring any boarding and transfer penalties or waiting time. Linear lines may also have the same first and last nodes but passengers must incur a boardingthat is, boarding and transfer penalties plus wait timefor routes passing this node.
12
LINE keywords (continued)

Keyword CROWDCURVE Subkeyword |IV10| Description Optional. Crowd curve used to adjust link travel times for a modeled user class. You may code CROWDCURVE in conjunction with the VEHICLETYPE keyword to override crowd-curve values specified on the VEHICLETYPE control statement and provide line-specific curves instead. Valid values range from 1 to 255. Default values are those specified in the VEHICLETYPE control statement. CRUSHCAP |I| Optional. Crush capacity (that is, sum of seated and maximum-standing capacities) of vehicles operating on this line. Must be greater than or equal to any specified seating capacity. You may code in conjunction with the VEHICLETYPE keyword to override the crush-capacity value specified with the VEHICLETYPE control statement and provide a linespecific capacity instead. Valid values range from 1 to 20,000. Default values are those specified in the VEHICLETYPE control statement. FARESYSTEM |I| Optional. Lines fare-system number. Overrides value provided by FACTORS FARESYSTEM control statement, and applies for all user classes. The value specified with the FACTORS control statement may vary by user class. The FARESYSTEM control statement defines fare systems (see FARESYSTEM on page 663), which form part of a FILEI FAREI file. Fare systems entered with this keyword must be defined in a FILEI FAREI file. Valid values range from 1 to 1999. FMCAPACITY |R| Optional. Lines capacity when the program runs a crowding model and writes the resulting line data file. The program does not read in or store this value when processing a FILEI LINEI file containing this data. Valid values range from 1 to 20,000.
12

Keyword HEADWAY Subkeyword |RV5| Description Interval, in minutes, between two vehicles on a line. You can code up to five different headways for a line. The program selects the headway for a run from PARAMETERS HDWAYPERIOD, which defaults to 1 or the value associated with a FILEI ROUTEI file. If coding only one headway value, you may enter either HEADWAY=x or HEADWAY[1]=x. If entering multiple headways, you must enter each index separately, such as
HEADWAY[1]=10, HEADWAY[2]=20, HEADWAY[3]=30. You cannot enter HEADWAY=10,20,30.
Valid values range from 1 to 2000. HEADWAY_R |RV5| Optional. Interval, in minutes, between two vehicles on a line in the reverse direction of a two-way line. You can code up to five different headways for a line. The program selects the headway for a run from PARAMETERS HDWAYPERIOD, which defaults to 1 or the value associated with a FILEI ROUTEI file. If coding only one headway value, you may enter either HEADWAY_R=x or HEADWAY_R[1]=x. If entering multiple headways, you must enter each index separately, such as
HEADWAY_R[1]=10, HEADWAY_R[2]=20, HEADWAY_R[3]=30. You cannot enter HEADWAY_R=10,20,30.
Valid values range from 1 to 2000. The default value is the value of HEADWAY (the value in the forward direction). LOADDISTFAC |R| Optional. Load distribution factorthe percentage of seats occupied when standing first occurs. At this seat-occupancy point, passengers begin experiencing increases in perceived travel time due to crowding. You may code in conjunction with the VEHICLETYPE keyword to override the load-distribution factor specified with the VEHICLETYPE control statement and provide a line-specific factor instead. Valid values range from 0.0 to 100.0. The default value is the value specified with the VEHICLETYPE keyword. LONGNAME MODE |S| |I| Optional. Second unique string identifier for a transit line, in addition to NAME. Integer indicating mode of the transit line. Valid values range from 1 to 999.
12

Keyword NODES or N Subkeyword |I| Description List of nodes that the transit line traverses. Use negative node numbers to indicate nonstopping nodes. You must specify at least two stop-nodes for a line. If two consecutive nodes do not map to a link in the underlying Public Transport network, the program generates a link, calculating the links distance from the node coordinates and taking the speed from XYSPEED or XYSPD. Separate node numbers with spaces, commas, or dashes. Citilabs suggests coding the NODES keyword as the lines last keyword. If you code the NODES keyword multiple times for a line, the program joins the last node of the previous node list and the first node of the next node list to form a link. If you insert a subkeyword in the list of nodes, you must enter the NODES keyword again, following the subkeyword value. To ease the coding in such cases, you may use N as an alias for NODES. Valid values range from 1 to the networks highest node number. NODES ACCESS |I| Optional. Integer indicating whether a stop node is for access only, exit only, or access and exit. Valid values are: 0 Stop for access and exit 1 Stop for access only 2 Stop for exit only
Default value is 0. The program inverts the access restriction for the lines reverse direction. NODES ACCESS_C |I| Optional. Integer indicating ACCESS value for a stop node and all subsequent stop nodes until you specify the next ACCESS or ACCESS_C keyword. When using ACCESS_C, you must check that the lines last node allows exiting (that is, that nodes value must be 0 or 2), otherwise passengers cannot ride to the end of the line. Valid values are 0, 1, or 2. Default value is 0. NODES DELAY |R| Optional. Additional time delay added to the link time. Code between the two nodes that compose the link. Valid values are any number greater than or equal to 1.
12

Keyword NODES Subkeyword DELAY_C |R| Description Optional. Additional time delay added to the link time and all subsequent link times until you specify the next DELAY_C or DELAY keyword. Valid values are any number greater than or equal to 1. NODES DWELL |I| Optional. Dwell time, in minutes, the line spends at the preceding stop node. Valid values range from 0 to 999. Default value is 0. NODES DWELL_C |I| Optional. Dwell time, in minutes, the line spends at the preceding stop node and all subsequent stop nodes until you specify another DWELL or DWELL_C subkeyword. Valid values range from 0 to 999. Default value is 0. NODES FMOFF
1
|R|
Optional. Flow-metered number of passengers alighting from the line at the preceding node. This is the result from running a crowding model, which accounts for bottlenecks in the public transport system when loading demand data (see Crowd modeling on page 618). Valid values are numbers greater than or equal to 0. Optional. Flow-metered number of passengers boarding the line at the preceding node. This is the result from running a crowding model, which accounts for bottlenecks in the public transport network when loading demand data (see Crowd modeling on page 618). Valid values are numbers greater than or equal to 0. Optional. Flow-metered number of passengers the loading models (with crowding) assign to the link connecting the preceding node and the next node. This is the result from running a crowding model, which accounts for bottlenecks in the public transport network when loading demand data (see Crowd modeling on page 618). Valid values are numbers greater than or equal to 0.
NODES
FMON
|R|
NODES
FMVOL
|R|
12

Keyword NODES Subkeyword NNTIME |R| Description Optional. Travel time, in minutes, between the most recent node and the node preceding the last NNTIME keyword. The PARAMETERS keyword TRANTIME sets the expression for computing base transit travel time for links in the highway network. The LINE keyword XYSPEED and subkeyword XYSPD set speeds for links not in the highway network. The program adjusts (that is, overrides) the computed link and delay times between the nodes to reflect the NNTIME value. Statements that set NNTIME to -1 (or to 0) start the time counter from the last node listed. The program does not set travel time between nodes to zero; the program retains the computed travel time. Statements that set NNTIME to a non-zero, positive value set the travel time between the last node listed and the previous node where the time counter started, and restart the time counter at the last node listed. The program automatically starts the time counter at a lines first node. For example:
NODES=1,2,3,4, NNTIME=10
Sets the time from node 1 to node 4 to ten minutes.

NODES=1,2,3,4, NNTIME=10, NODES=5,6,7, NNTIME=15
Sets the time from node 1 to node 4 to ten minutes, and sets the time from node 4 to node 7 to fifteen minutes.
NODES=1,2,3,4, NNTIME=-1, NODES=5,6,7, NNTIME=5
Sets the time from node 4 to node 7 to five minutes.

NODES=1,2,3,4, NNTIME=-1, NODES=5,6,7, NNTIME=5, NODES=8,9, NNTIME=10
Sets the time from node 4 to node 7 to five minutes, and the time from node 7 to node 9 to ten minutes.
NODES=1,2,3,4, NNTIME=10, NNTIME=-1, NODES=5,6,7, NNTIME=6
Sets the time from node 1 to node 4 to ten minutes, and the time from node 4 to node 7 to six minutes. In this case, the NNTIME=-1 is unnecessary. Do not use NNTIME for two-way lines; doing so produces an error.
12

Keyword NODES Subkeyword OFF
1
Description |R| Optional. Number of passengers alighting from the line at the preceding node. This is the result of a loading operation performed by the load models. Valid values are numbers greater than or equal to 0. Optional. Number of passengers boarding the line at the preceding node. This is the result of a loading operation performed by the load models. Valid values are numbers greater than or equal to 0. Optional. Intermediate run time from the lines first node to the most recently coded node. The program adjusts the accumulated time to the most recent node to match the specified value, and adjusts accumulated times to downstream nodes. If you code more than one RT subkeyword, the program makes subsequent adjustments from the node of prior adjustment. Do not code RT at the first node; the program implicitly sets to zero. If coding multiple RT subkeywords, the values must increase. RT and keyword RUNTIME are mutually exclusive. Valid values are numbers greater than or equal to 1.
NODES
ON
|R|
NODES
RT
|R|
NODES
SPEED
|R|
Optional. Speed for all subsequent links in the line, until the next SPEED or TF subkeyword. SPEED overrides the TIMEFAC keyword value. The program uses TIMEFAC for links the line traverses until encountering SPEED or TF, and then uses that value. Valid values are numbers greater than or equal to 1.
NODES
TF
|R|
Optional. Time factor applied to the current link and subsequent links until encountering another TF subkeyword or SPEED subkeyword. Overrides the value specified in TIMEFAC, and any previous TF or SPEED subkeywords. Valid values are numbers greater than or equal to 1.
12

Keyword NODES Subkeyword TIME |R| Description Optional. Time to traverse the link that connects that last node specified with the next node specified. Replaces link time computed using coordinates and XYSPD or XYSPEED. For example:
N=100,101,102, TIME=5, N=103
Sets the time for link 102-103 to five minutes. The link time is subject to adjustment by NNTIME, RT, or RUNTIME. Valid values are numbers greater than or equal to 1. NODES VOL
1
|R|
Optional. Number of passengers the loading models assign to the link from the preceding node to the next node. Valid values are numbers greater than or equal to 0. Optional. Sets the lines speed for the current link and any subsequent links not in the input network until encountering the next XYSPD subkeyword. Overrides the value of XYSPEED. Do not code XYSPD for two-way lines. Doing so produces an error. Valid values are numbers greater than or equal to 1.
NODES
XYSPD
|R|
ONEWAY
|?|
Optional. Flag indicating whether line is one way. Possible values: T Coded line is a one-way line. F Coded line is a two-way line. The reverse direction is treated as a separate line for processing.
Default value is T. OPERATOR |I| Optional. Integer indicating operator of the transit line. You can define public transit operators with the OPERATOR control statement. Valid values range from 1 to 999.
12

Keyword RUNTIME Subkeyword |R| Description Optional. Lines scheduled time, in minutes, from the first node to the last node. When you specify RUNTIME, the program adjusts the time on all of the lines links so that the time sums to this value. The program only scales the links travel time and DELAY and DELAY_C components. The program retains the original values of dwell times and intersection delays. If you set PARAMETERS EXTENDRUNTIMES to true and the total time calculated from link times, delays, dwell times, and intersection delays exceeds the specified value, then the program increases the value of RUNTIME to this total. Valid values range from 1 to 30,000 minutes. SEATCAP |I| Optional. Seating capacity of vehicles operating on this line. You may code in conjunction with the VEHICLETYPE keyword. Use the VEHICLETYPE keyword to override the seating capacity value with a line-specific capacity. Valid values range from 1 to 10,000. Defaults to value specified with VEHICLETYPE. TIMEFAC |R| Optional. Time factor applied to the travel time of all links the line traverses. The program applies this factor until encountering a NODES TF keyword or NODES SPEED keyword. Valid values are numbers greater than or equal to 1. VEHICLETYPE |I| Optional. Integer indicating vehicle type operating on this transit line. When including crowd modeling, you can code the vehicle type or its attributes in the LINE statement. If you code both the vehicle type and the attributes of the vehicle type, the program obtains default information from the vehicle type and overrides that information with attribute data. Valid values range from 1 to 255. XYSPEED |R| Optional. Speed on qualified links in this transit line. Qualified links do not exist in the input network, and both nodes in the link have valid coordinates, enabling distance computation. Valid values range from 1 to 300. 1. The Public Transport program saves the results of a loading operation to this NODES subkeyword.
12
Example
LINE NAME="GMB1-24M", MODE=7, OWNER=11, ONEWAY=T, CIRCULAR=F, HEADWAY=12, N=778, -777, 776, 773, 774, 765, 3674, 764, -763, 759, 760, -3673, -756, 752
Calculation of line/link times

You can adjust the time to lines use to traverse links with several LINE keywords and NODES subkeywords. The program uses a twopart approach to process the keywords and obtain a lines final link times:
1. Establish the base time for each link:
If the link exists in the network: Set link time to the link variable defined by PARAMETERS TRANTIME. Adjust link time using the prevailing value of TIMEFAC, SPEED, or TF.
If the link does not exist in network, but both nodes have coordinates and either XYSPEED or XYSPD is coded: Set link time to the computed X-Y distance divided by either XYSPEED or XYSPD, as appropriate. Set link time to TIME if specified. Add DELAY or DELAY_C to link time, if specified. Add turn penalties to the approach link of the modelled intersection.
2. Adjust link times based on applicable keywords: NODES NNTIME NODES RT RUNTIME
The program applies scaling to link travel time, DELAY and DELAY_C values. The program does not scale dwell times and junction delays, but retains their original settings.
12
If you set PARAMETERS EXTENDRUNTIMES to true and the total time calculated from link times, delays, dwell times, and intersection delays exceeds the specified value, then the program increases the NNTIME, RT, or RUNTIME value to this total.
LINKLOOP ... ENDLINKLOOP

Controls a loop for processing link records. You may nest LINKLOOP blocks, but do not overlap LINKLOOP blocks with IF blocks. By default, the LINKLOOP statement processes all link records with a loop increment of one. You can use LINKNO, the default loop index, to reference the current link number. The program supplies all link arrays in a LINKLOOP block with the number-of-links dimension. You can only use LINKLOOP in the DATAPREP phase.
Example
Double LW.VAR for even number zones

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

Initializes a variable, compares the variable to a constant, and branches to the statement following the LOOP block if the comparison fails.
LOOP blocks may be nested, but they may not overlap other LOOP blocks or IF blocks.
LOOP Var = Begin, End, Incr Statement set ENDLOOP
where:
12
Var is the required user-specified name of the loop-control variable. The program does not protect the value of Var during the loop; computation, program, and other LOOP statements may alter the value of Var. Begin is the constant value to which the program initializes Var. You must specify a value. End is the constant value that the program compares Var to when processing the ENDLOOP statement. You must specify a value. Incr is the constant the program adds to Var before processing the ENDLOOP statement. If the result of the comparison is true, the program branches back to the statement following the LOOP statement. If it is false, control is passed to the statement following ENDLOOP.
Processing of the ENDLOOP statement depends on the value of Incr: If Incr is positive, when the value of Var is less than or equal to End, the program goes to the statement following LOOP, otherwise the program goes to the statement following ENDLOOP. If Incr is negative, when the value of Var is greater than or equal to End, the program goes to the statement following LOOP otherwise the program goes to the statement following ENDLOOP.
The program tests the ENDLOOP condition (without incrementing the variable value) when initializing the loop-control variable. If the test fails, the program does not perform any statements within the LOOP block.
Example 1
Executes the code within the LOOP block 10 times.

LOOP iter=1,10 . . ENDLOOP
12
Example 2
A nested loop, with the innermost loop executing twice for each value of variable xyz: 10,8,6,4,2.
LOOP xyz=10,1,-2 LOOP abc=1,2 . . ENDLOOP ENDLOOP
MODE
Defines the transit and nontransit modes that the public transport system uses. All nontransit legs and transit lines belong to modes and refer to them by their numeric identifiers. The MODE statement associates descriptive names with each mode. You can include descriptive names in reports and graphics. Although not mandatory, Citilabs recommends that you define the modes in use with the MODE statement. Input MODE statements in the public transport system data file, specified with SYSTEMI.
MODE keywords
Keyword NUMBER |I| Description Unique numeric identifier for a mode. NUMBER must be the first keyword on the MODE control statement. Valid values range from 1 to 999. NAME LONGNAME |S| |S| Optional. Unique string identifier for a mode. Optional. Second unique string identifier for a mode. Use to supplement NAME.
12
NT
Specifies the format of nontransit legs in the Public Transport network. Passengers use nontransit legs to: Access the public transport system Egress from the public transport system Transfer between lines
You can generate nontransit legs with GENERATE statements or produce them with a process external to the Public Transport program. The program saves nontransit legs with the public transport network when processing a NETO statement. You can use the output for modeling, reporting, and displaying. You can feed the saved nontransit legs back to the modeling process when inputting the public transport network with a NETI statement. You can also save nontransit legs in the file specified with the NTLEGO statement. You can use this format for reviewing and editing. You can feed these saved nontransit legs back to the modeling process with a NTLEGI statement.
NT keywords
Keyword LEG |S| Description Nodes defining a nontransit leg. Specify the starting node number followed by the ending node number, separated by a hyphen. Only one leg can connect any two nodes. NOTE: LEG must be the first keyword in NT control statements.
12
NT keywords (continued)
Keyword ACTION |S| Description Optional. String that designates how the program merges input nontransit legs with generated nontransit legs. The Public Transport program maintains a single table of nontransit legs. The program merges the legs from each GENERATE statement, generated or input, into this table. The table stores only one leg, the one with the least cost, for each combination of A-node, B-node, and nontransit mode. Possible values: A Add the input leg, if it is shorter than a matching one in the table, or if it does not already exist in the table. D Delete the leg from the table, if it exists. Useful for eliminating nontransit legs from the network. R Replace an existing leg in the table with the input one, even if it is longer than the existing one. No action is taken if the leg is not already in the table. RS Replace an existing leg in the table with the input one, only if it is shorter than the existing one. No action is taken if leg is not already in the table.
Default value is A. COST DIST FMVOL |R| |R| |R| Cost, in user-specified units, to traverse the nontransit leg. Valid values are great than or equal to 0.01. Length, in user-specified units, of the nontransit leg. Valid values are great than or equal to 0.01. Optional. Directional flow-metered passenger volume (total number of flow-metered passengers that the loading models assigned to the nontransit leg). This crowd-modeling data accounts for constraints that bottlenecks impose in the public transport network. Valid values are great than or equal to 0. FMVOLT |R| Optional. Nondirectional flow-metered passenger volume (total number of flow-metered passengers that the loading models assigned to the nontransit leg in the forward and reverse directions). This crowd-model data accounts for constraints that bottlenecks impose on the public transport network. Enter the same value for FMVOLT for leg A-B and leg B-A. Valid values are great than or equal to 0.
12
NT keywords (continued)
Keyword MODE ONEWAY |I| |?| Description Mode of the nontransit leg. Valid values range from 1 to 999. Optional. Flag indicating whether nontransit leg is a one-way leg. Possible values: SPEED |R| T Nontransit leg is a one-way leg F Nontransit leg is a two-way leg
Default is T. Optional. Speed, in user-specified units per hour, that the transit vehicle traverses the nontransit leg. Valid values are great than or equal to 0.01. VOL |R| Optional. Directional passenger volume (number of passengers that the loading models assign to the nontransit leg). Valid values are great than or equal to 0. VOLT |R| Optional. Nondirectional passenger volume (total number of passengers that the loading models assign to the nontransit leg in both the forward and reverse directions). Enter the same value for VOLT for leg A-B and leg B-A. Valid values are great than or equal to 0. XN |S| Optional. List of nodes between the start and end nodes in a nontransit leg. LEG defines the start and end nodes.
Example
A selection of nontransit legs generated by the Public Transport program.

NT NT NT NT NT NT NT NT LEG=6-800 MODE=5 TIME=1.92 DIST=39.00 ONEWAY=T LEG=6-2054 MODE=5 TIME=5.40 DIST=53.00 ONEWAY=T XN=792 LEG=6-2056 MODE=5 TIME=5.92 DIST=43.00 ONEWAY=T XN=800 LEG=7-803 MODE=5 TIME=1.52 DIST=41.00 ONEWAY=T LEG=7-806 MODE=5 TIME=8.35 DIST=52.00 ONEWAY=T XN=2058 LEG=7-2058 MODE=5 TIME=4.35 DIST=29.00 ONEWAY=T LEG=8-814 MODE=5 TIME=0.88 DIST=12.00 ONEWAY=T LEG=9-812 MODE=5 TIME=1.16 DIST=29.00 ONEWAY=T
12
OPERATOR
Defines the operators in the public transport system. All lines belong to operators and refer to them by their numeric identifiers. The OPERATOR control statement associates descriptive names with operators. You can include these names in reports and graphics. Although not mandatory, Citilabs recommends that you define the operators in use with the OPERATOR statement. Input OPERATOR statements in the public transport system data file, specified with SYSTEMI.
OPERATOR keywords
Keyword NUMBER |I| Description Unique number that identifies a transit operator. Must be the first keyword coded with the OPERATOR control statement. Valid values range from 1 to 999. NAME LONGNAME |S| |S| Optional. Unique string that identifies a transit operator. Optional. Unique secondary string that identifies a transit operator. Supplements NAME.
PARAMETERS
Specifies global parameters for the Public Transport run.
PARAMETERS keywords
Keyword AONMETHOD |IK| Description Optional. Integer specifying all-or-nothing path-building algorithm to use. Possible values: 0 Use latest available algorithm 3 Use algorithm from version 3.2 4 Use algorithm from version 4.0
Default value is 0.
12

Keyword CHANGEATLASTSTOP |?K| Description Optional. Flag that indicates how transfers between routes occur. Possible values: T Method from version 3.2 and earlier releases: When two routes share a common sequence of stopping nodes, transfers occur at the last stopping node in the sequence. Citilabs recommends this setting only when required for consistency with earlier runs. F When two routes share a common sequence of stopping nodes, transfers may occur at any of the nodes.
Default value is F. EXTENDREPORT |?| Optional. Flag that specifies whether to print messages for excessive calculated travel times. Possible values: T Program prints messages when a lines calculated travel time exceeds the values specified by RUNTIME, NODES NNTIME, or NODES RT. F Program does not print messages for excessive calculated travel times.
Default value is F. The program determines run times along transit lines from junction delays and link travel time, using data in keywords such as TRANTIME, DELAY, DELAY_C, DWELL, DWELL_C. When calculated travel times exceed the travel time limits imposed by the RUNTIME, NNTIME, or RT keywords and subkeywords in the LINE control statement, you might edit the LINE statement or extend the lines run time with the EXTENDRUNTIMES keyword.
12

Keyword EXTENDRUNTIMES |?| Description Optional. Flag that indicates whether the program automatically extends travel time along a line when it exceeds control values. Possible values: T When calculated travel times along a line exceed control values, the program increases the control values and travel times to reflect the prevailing network conditions F When calculated travel times along a line exceed control values, the program scales calculated values to match control values.
Default value is F. The program calculates run times along transit lines from junction delays and link travel time, using data in keywords such as TRANTIME, DELAY, DELAY_C, DWELL, DWELL_C. The LINE control statement and its RUNTIME, NNTIME, or RT keywords and subkeywords set control values for travel time. Only set EXTENDRUNTIMES to T when reading LINEI files. If the program reads line data from a network file, then link travel times have already been calculated and cannot be amended. FARE |?K| Optional. Flag indicating whether fares are included in generalized cost during the route-evaluation process. Possible values: T Program includes fares as part of the generalized cost during the route-evaluation process. Input descriptions of fare systems with FILEI FAREI. If required, input descriptions of fare matrices with FILEI FAREMATI. F Program does not include fares as part of the generalized cost during the route-evaluation process.
Default value is F. FARE does not impact the selection of fare skims chosen with the skimming functions FAREA and FAREP. Fare data is required only for the route-evaluation and skimming processes. The program only validates fare data if you select one of these processes. You do not need to provide fare data for the DATAPREP phase.
12

Keyword FAREMSG |IK| Description Optional. Integer indicating how the program treats message 770. Possible values: 0 Treat as message 1 Treat as warning 2 Treat as error
Default value is 2. Message 770 describes missing or inconsistent data in the FILEI FAREI. The program only validates this data if fares are included in the route-evaluation or skimming processes. HDWAYPERIOD |IK| Optional. Integer indicating which HEADWAY and HEADWAY_R fields to use from the LINE control statement, if more than one such field is coded. You can code up to five headways for each line. If you do not specify HDWAYPERIOD, the default is 1 (HEADWAY[1]). Valid values range from 1 to 5. MAPSCALE |RK| Optional. Factor indicating coordinate units divided by distance unite. The program uses this value in conjunction with LINE XYSPEED. If not specified, the program estimates a value from the link data. MAXMW |IK| Optional. Maximum index for work matrices (MWs). Valid values range from 1 to 999. Default value is 999. Normally, you do not specify this keyword and override default value. Optional. Flag indicating whether program considers link use of nontransit modes. Possible values: Y Program considers link use of all modes when creating intercept data. N Program considers only link use of transit modes when creating intercept data.
MEUSESNT
|?|
You can override this default setting with keywords in the FILEO SCREENLINEO statement. Default value is Y.
12

Keyword NOROUTEERRS |IK| Description Optional. Number of zone pairs that the program can process with trips between them but no valid routes. When the number of zone pairs with trips but without valid routes exceeds this value, the program terminates. Generally, all zones in a public transport network are connected. This keyword permits you to accommodate unconnected zones, if necessary. NOROUTEERRS applies to all user classes. Valid values are greater than or equal to 0. Default value is 10. NOROUTEMSGS |IK| Optional. Number of messages the program reports for loaded zone pairs that have trips between them but no valid routes. The program terminates when the number of such zone pairs exceeds NOROUTEERRS. NOROUTEMSGS applies across all user classes. Valid values are greater than or equal to 0. Default value is 5. SKIPBADLINES |?| Optional. Flag indicating whether to treat data errors when reading transit line data as warning. Possible values: Y Downgrade data errors to warnings when reading transit line data. This setting allows the program to read an entire input file without termination due to data errors. N Treat data errors as errors, leading to program termination.
Default value is N. You may override this global setting with the FILEI LINEI control statement.
12

Keyword TRANTIME |NKVt|1 Description Expression specifying how to compute base transit time for links that transit lines traverse. May vary per mode. You can refine this time with the LINE control statement and the NODES keyword. You might specify: Name of an input-network link-based variable that contains link transit times. Denote input-network link variables as LI.name. Name of a link work array that you computed in the LINKREAD phase. Denote these arrays as LW.name. Expression involving one or more link variables. Include only input-network link variables (LI.name) or link work arrays (LW.name). You must enclose expressions in parentheses.
NOTE: If you set TRANTIME to any other variables, the results are unpredictable. Examples:
TRANTIME TRANTIME computed TRANTIME = LI.name = LW.TRANTIME; LW.TRANTIME was in the LINKREAD phase. = (LI.DISTANCE*60/LI.SPEED)
The settings in these examples apply to all modes. You can override these settings with a mode-specific expressions. For example, if mode 3 uses a different formula, you might define:
TRANTIME[3] = (1.14*LI.DISTANCE*60/LI.SPEED)
12

Keyword TRIPSIJ |NVu|2 Description Optional. Numeric expression used to compute trips loaded for a particular user class. You might assign an input or generated trip matrix. You must provide a value for all user classes, unless using the SELECTIJ phase. The index is defined by USERCLASSES. If USERCLASSES=1, you need not code the index. TRIPSIJ applies to all I-J pairs; the program can compute trips for individual or sets of I-J pairs in the SELECTIJ phase. Examples
FILEI MATI[1]=TRIPS.MAT PARAMETERS TRIPSIJ[1] = MI.1.1
Loads the cells of an input trip matrix.

FILEI MATI[1]=TRIPS.MAT PARAMETERS TRIPSIJ[1] = MI.1.1 * 0.7, TRIPSIJ[2] = MI.1.1 * 0.3
Loads 70% of the input trip matrix to user class 1 and 30% to user class 2. USERCLASSES |IK| Optional. List of modeled user classes. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. Delimit each number or pair with a comma. User classes need not be monotonic or sequential. For example:
USERCLASSES=1,3-5,7
Valid user classes range from 1 to 10. By default, all ten user classes are available in the Public Transport network. For more information, see More on user classes on page 744. V4ROUTEFORMAT |?K| Optional. Flag indicating formatting of route file. Possible values: T Program writes older, version 4-compatible route file format with FILEO ROUTEO F Program writes current route file format
Default value is F.
12

Keyword ZONEMSG |IK| Description Optional. Frequency with which the program writes zonal timing messages to the run monitor or console. Value corresponds to number of zones. For example, with a value of 1, the program writes a message for every zone. With a value of 10, the program writes a message for every 10 zones. With a value of 0, the program writes no zonal messages. Specify a larger value to reduce run times. Program writes to the run monitor when initiated through Application Manager or voyager.exe. The program writes to the console when initiated through runtpp.exe. Valid values are greater than or equal to zero. Default value is 1. 1. t represents number of transit modes 2. u represent number of user classes
Example
Parameters for the data-preparation, route-evaluation, and loading processes. Note most PARAMETERS keywords, other than TRIPSIJ, are trigger keywords and need not be preceded by the control statement name.
PARAMETERS USERCLASSES=1,2 PARAMETERS TRIPSIJ[1] =MI.1.1 PARAMETERS TRIPSIJ[2] =MI.1.2 NOPATHMSGS=10 NOPATHERRS=25
More on user classes

You can use user classes for multiple purposes. For example, you can use user classes to stratify demand, such as by purpose or fare type. Similarly, each user class might have different behavior patterns, which you model with user-class-specific cost functions. The Public Transport network contains several components that are common to all user classes: Basic network infrastructure (such as zones, nodes/stops, and links) produced by the Network program
12
System data input with SYSTEMI Demand data, input with MATI Nontransit legs, generated with the GENERATE control statement, input with NTLEGI, or both Line data, input with LINEI
Other data and processes vary by user class: Factor data, input with FACTORI, specifies cost functions that can vary by user class. Skim data, output with MATO, specifies level-of-service data that can vary by user class. Routes are enumerated and evaluated by user class. Routes are input with ROUTEI, and output with ROUTEO.
You must specify FACTORI files by user class. However, if there are no differences between the behavior for some user classes, you can point those user classes to the same files. For example, suppose you want to define input files for user classes 1, 3, and 4. User class 3 and 4 use the same factors and enumerated route files. You might create the following control statements:
FILEI FACTORI[1]= FACTSUC1.FAC, FACTORI[3]=FACTSUC3.FAC, FACTORI[4]=FACTSUC3.FAC FILEI ROUTEI[1]=ENROUTEUC1.RTE, ROUTEI[3]=ENROUTEUC3.RTE, ROUTEI[4]=ENROUTEUC3.RTE
The Public Transport program outputs a public transport network that contains the four components that are common to all user classes (network infrastructure, system data, nontransit legs, and line data) and that contains the factors for all user classes. The program outputs user-class-specific enumerated routes files (ROUTEO), matrices (MATO), and skims and select link analyses. If two or more user classes have the same cost function, the program might produce the enumerated route file for one user class and reuse the file for the other user classes.
12
You define input and output files for user classes with the FILEI and FILEO control statements.
PRINT
Specifies the format for data items output in a single line to the standard printed output, a file, or both. The program prints one line for each PRINT statement. The length of the printed line is determined by the formatting of each listed item. See PRINT on page 62 for details about the standard Cube Voyager control statement.
PRINTROW
Specifies format for reporting work matrices to the main print file. See PRINTROW on page 69 for details about the standard Cube Voyager control statement.
Example
Print two skim matrices, ten columns per line.

PRINTROW MW=2 FORM 10.2 TITLE='COMPCOST' PRINTROW MW=2 FORM 10.2 TITLE='TIMEA''
REPORT
Generates two reports: Summary of line attributes including passenger distance and hours Passenger loadings on lines
The program generates a third report, which shows passenger transfers between modes and operators, when running the loading process.
12
REPORT keywords
Keyword LINES Subkeyword |?| Description Optional. Flag indicating whether to generate summary report of line attributes, showing attributes like number of stops, route time, and distance. Possible values: T Produce summary report of line attributes. Summary includes passenger distance and hours if line loads are available. F Do not produce summary report.
Default value is F. More than one LINES report may be selected in a run. See Transit line summary on page 767 for an example of this report. LINES DEC |I| Optional. Number of decimal places to include in the Pass and PassDist columns in the summary report produced by LINES. Valid values range from 0 to 5. Default is 2. LINES SKIP0 |?| Optional. Flag indicating whether to omit lines without loads in the summary report produced by LINES. Possible values: LINES SORT |S| T Omit lines without loads F Include lines without loads
Default value is F. Optional. String specifying field that the summary report uses to sort lines. Possible values: NAME MODE OPERATOR
By default, report does not sort lines, but displays in order of input.
12

Keyword LINEVOLS Subkeyword |?| Description Optional. Flag indicating whether to report passenger 8loadings (boardings, alightings, and flows) by line. Possible values: T Report passenger loadings by line. By default, program generates single report summed over all user classes. You can produce reports for individual user classes with subkeyword USERCLASSES. F Do not report passenger loadings.
Default value is F. See Transit line loadings on page 768 for an example of this report. LINEVOLS DEC |I| Optional. Number of decimal places in passenger loading fields. Valid values range from 0 to 5. Default is 2. LINEVOLS SKIP0 |?| Optional. Flag indicating whether to include only stop nodes with flows. Possible values: T Produce passenger loadings report only for stop nodes with nonzero flows; ignore nonstopping nodes and nodes that have no passenger activity. F Include all nodes in report.
LINEVOLS STOPSONLY |?|
Default value is F. Optional. Flag indicating whether to include stop nodes only. Possible values: T Produce passenger loadings report for stop nodes only; do not include nonstopping nodes. F Include all nodes in report.
Default value is F.
12

Keyword LINEVOLS Subkeyword USERCLASSES |IV10| Description Optional. List of user classes that require individual passenger loadings reports. Specify the list as a set of single numbers or dashseparated pairs of numbers that give a range. Delimit each number or pair with a comma. Valid values range from 1 to 10. You may specify up to ten user classes. By default, none are included, and the program produces a single report, summed over all user classes.
REREPORT
Produces reports showing the input simplified public transport network and allied data structures that the route enumeration process uses. These basic reports help you understand the network-simplification and route-enumeration processes. For examples, see Network simplification on page 782. A run can have multiple REREPORT statements. A statements selections apply to the reports generated by that statement. The statement outputs reports to the file specified with REPORTO. None of the REREPORT keywords are trigger keys; you must code all on a REREPORT statement.
REREPORT keywords
Keyword ACCESSLEGS |?| Description Optional. Flag indicating whether to produce an access-leg report. Possible choices: T Produce a report showing access legs in the public transport network. Access legs connect zones to serviced boarding nodes. GENERATE control statements generate or input access legs. Specify included nodes with N. F Do not produce this report. Default value is F.
12
REREPORT keywords (continued)

Keyword EGRESSLEGS |?| Description Optional. Flag indicating whether to produce an egress-leg report. Possible values: T Produce a report showing egress legs in the public transport network. Egress legs connect zones to serviced alighting nodes. GENERATE control statements produce or input egress legs. Specify included nodes with N. LINE |S| F Do not produce this report. Default value is F. Optional. List of lines included in the reports produced by LINES, TRNLEGS3, and TRNLEGS4. The list can contain up to 1000 comma-separated items. You can mask names with * and ? to specify multiple lines. The program compares nonmasked portions of a lines name when selecting lines. * applies to any number of characters, while ? applies to single characters. For example, LINE=MUNI* selects all lines that have names beginning with MUNI, such as MUNICENTRAL and MUNINORTH, while LINE=MUNI-?? selects lines that have names beginning with MUNI- and any two additional characters, such as MUNI-01 and MUNI-02. Default value is all lines. LINES |?| Optional. Flag indicating whether to produce a line-attribute report. Possible values: T Produce a report showing transit-line attributes and the nodes the lines traverse. Specify included lines with LINE. F Do not produce this report. Default value is F.
12

Keyword LINELINELEG |?| Description Optional. Flag indicating whether to produce a line-to-line transfer-leg report. Possible values: T Produce a report showing the line-to-line transfer legs, in line order. This report expands upon the direct-andnontransit-transfer-leg report, produced with XFERLEGS. You might use this report to improve performance of the route-enumeration process. GENERATE control statements generate or input nontransit transfer legs. LINEZONLEG1 |?| F Do not produce this report. Default value is F. Optional. Flag indicating whether to produce a line-ordered lineto-zone nontransit-leg report. Possible values: T Produce a report showing line-to-zone nontransit legs, in line order. This report expands on the access-leg and egress-leg reports produced with ACCESSLEGS and EGRESSLEGS. You might use this report to improve performance of the route-enumeration process. LINEZONLEG2 |?| F Do not produce this report. Default value is F. Optional. Flag indicating whether to produce a zone-ordered line-to-zone nontransit-leg report. Possible values: T Produce a report showing line-to-zone nontransit legs, in zone order. This report expands on the access-leg and egress-leg reports produced with ACCESSLEGS and EGRESSLEGS. You might use this report to improve performance of the route-enumeration process. Specify included nodes with N. F Do no produce this report. Default value is F.
12

Keyword N |IV1000| Description Optional. List of nodes included in the reports produced by ACCESSLEGS, EGRESSLEGS, LINEZONLEG2, TRNLEGS1, TRNLEGS2, and XFERLEGS. Specify the list as a set of single numbers or dash-separated pairs of numbers that give a range. Delimit each number or pair with a comma. The list can contain up to 1000 comma-separated items. For example, if REREPORT ACCESSLEGS=T,
EGRESSLEGS=T, N=1000-2000, 3000-4500, then the
selected reports will include nodes 1000 through 2000 and nodes 3000 through 4500. Default is to include all nodes. STOPNODES |?| Optional. Flag indicating whether to produce a stop-node report. Possible values: T Produce a report showing all nodes in the public transport network where transit lines stop for transfer, access, or egress. F Do not produce this report.
TRNLEGS1 |?|
Default value is F. Optional. Flag indicating whether to produce a node-ordered transit-leg report that shows perceived costs (including BRDPEN) during route enumeration. Possible values: T Produce a report showing all transit legs in the public transport network, sorted by node. Specify included nodes with N. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. The report calculates perceived in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] F Do not produce this report. Default value is F.
12

Keyword TRNLEGS2 |?| Description Optional. Flag indicating whether to produce a node-ordered transit-leg-bundle report that shows the perceived costs (including BRDPEN) during route enumeration for all legs and that identifies a bundles fastest line and shows that legs estimated waiting time. Possible values: T Produce a report showing transit-leg bundles in the public transport network, sorted by node. Specify included nodes with N. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. The report calculates in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] The perceived time for the bundles top leg also includes the estimated wait time for the bundle. TRNLEGS3 |?| F Do not produce this report. Default value is F. Optional. Flag indicating whether to produce a line-ordered transit-leg report that shows perceived costs (including BRDPEN) during route enumeration. Possible values: T Produce a report showing transit legs and attributes, sorted by line. Specify included lines with LINE. This report shows actual and perceived in-vehicle time that the route-enumeration process uses. The report calculates perceived in-vehicle time as: Actual in-vehicle time*RUNFACTOR[mode] + BRDPEN[mode] F Do not produce this report. Default value is F.
12

Keyword TRNLEGS4 |?| Description Optional. Flag indicating whether to produce a line-ordered transit-leg report that shows perceived costs used for route evaluation. Possible values: T Produce a report showing transit legs and attributes, sorted by line. Specify included lines with LINE. This report shows actual and perceived in-vehicle time that the route-evaluation process uses. The report calculates perceived in-vehicle time as: Actual in-vehicle cost * RUNFACTOR[mode] NOTE: The report TRNLEGS3 produces includes BRDPEN. USERCLASS |IPa| F Do not produce this report. Default value is F. Optional. List of user classes included in the reports produced by the REREPORT statement. You define valid user classes with USERCLASSES. By default, reports produced for each defined user class. XFERLEGS |?| Optional. Flag indicating whether to produce a direct-andnontransit-transfer-leg report. Possible values: T Produce a report showing direct and nontransit transfer legs in the public transport network. Specify included nodes with N. GENERATE control statements generate or input nontransit transfer legs. F Do not produce this report. Default value is F.
Example
In the REREPORT statement below, all reports are for user class 1. Node-based reports only apply to nodes 250-450, and line-based reports apply to lines with line names beginning with MUNI.
12
//The REREPORT control statement name must be coded at the beginning of the statement REREPORT, ACCESSLEGS=T, EGRESSLEGS=T, LINES=T, TRNLEGS1=T, TRNLEGS2=T, TRNLEGS3=T, TRNLEGS4=T, XFERLEGS=T, LINEZONLEG1=T, LINEZONLEG2=T, STOPNODES=T, N=250-450, LINE='MUNI*', USERCLASS=1
VEHICLETYPE
Defines the main vehicle types used by the transit lines operating public transit services. A vehicle can be any form of transport that provides public transit service over fixed routes, such as a bus, tram, train, ferry, or hovercraft. The vehicle definitions provide a template that you can associate with one or more transit lines. You can amend vehicle attributes on a line-by-line basis when needed. You may define up to 255 vehicle types. The program includes no default vehicle types. When transit lines operate with particular vehicle types, you may specify the vehicle type in the LINE statement. You must input VEHICLETYPE statements in the Public Transport system data file, specified with SYSTEMI.
VEHICLETYPE keywords
Keyword NUMBER |I| Description Unique numeric identifier for a vehicle type. NOTE: Number must be the first keyword coded on the VEHICLETYPE control statement. Valid values range from 1 to 255. CROWDCURVE |IV10| Optional. Crowd curve used to adjust link travel times for a particular user class. Specify per user class. Required to adjust link travel time. Valid values range from 1 to 255. By default, none is used.
12
VEHICLETYPE keywords (continued)

Keyword CRUSHCAP |I| Description Vehicles crush capacity (the sum of seated capacity and maximum standing capacity). Must be greater than or equal to the value of SEATCAP. Valid values range from 1 to 20,000. LOADDISTFAC |R| Optional. Percentage of seats occupied when standing first occurs. Represents load factor at which passengers begin experiencing additional perceived travel time due to crowding. Required for adjusting link travel time. Valid values range from 0.0 to 100.0. By default, model does not consider crowding and load factors. LONGNAME NAME SEATCAP |S| |S| |I| Optional. Second unique string that identifies the vehicle type (in addition to NAME). Optional. Unique string that identifies the vehicle type. Optional. Vehicles seated capacity. Required for adjustment to link travel time. Valid values range from 1 to 10,000. By default, vehicle has unlimited seating capacity.
Example
Define vehicle type number 1 for a single-deck bus.

VEHICLETYPE NUMBER=1, NAME="Bus single deck", SEATCAP= 40, CRUSHCAP=55, LOADDISTFAC=0.9, CROWDCURVE=1
WAITCRVDEF
Defines wait curves used to compute initial and transfer wait times at stop nodes based on the frequency of services. See Generalized cost on page 771 for a description of the wait-time calculation. You may define up to 255 wait curves. You may allocate two wait curves to each stop node with IWAITCURVE and XWAITCURVE. Use IWAITCURVE when the node is a trips first boarding point and use
12
XWAITCURVE at transfer points. Use the mode-specific WAITFACTOR to weight the wait time. You must input WAITCRVDEF statements in the Public Transport system data file, specified with SYSTEMI.
The program provides default wait curves for initial boarding and transfers at stop nodes where you do not assign wait curves. See More on wait curves on page 758 for details about wait curves.
WAITCRVDEF keywords
Keyword NUMBER |I| Description Unique number that identifies a wait curve. NOTE: Must be the first keyword coded in a WAITCRVDEF control statement. Valid values range from 1 to 255. NAME LONGNAME CURVE |S| |S| |RKV10000| Optional. Unique string that identifies a wait curve. Optional. Second unique string the identifies the wait curve (in addition to NAME). List of pairs of X-Y coordinates that define wait curve. The X-axis shows headway and the Y-axis shows wait time. Separate X and Y values in a pair by a comma or a dash. Separate each pair with a comma. For example:
WAITCRVDEF NUMBER=1 LONGNAME="InitialWait" NAME="InitWait", CURVE=1,0.5, 16,8, 27,12, 48,15, 160,20 WAITCRVDEF NUMBER=2 LONGNAME="TransferWait" NAME="XferWait", CURVE=1-0.5, 4-2, 12-6, 20-8, 40-15, 60-20
See More on wait curves on page 758 for information about default wait curves.
12
Example
Defining wait curve number 1 for stops in the central business area.
WAITCRVDEF NUMBER=1, NAME="CENTRAL-AREA" CURVE= 1-0.5, 15-7.5, 100-12.0
More on wait curves

The Public Transport program calculates wait times at a stop as a function of the frequency of transit services at the stop. At each stop node, you may assign two wait curves: IWAITCURVE, used when the node is the trips first boarding point, and XWAITCURVE, used at transfer points in the trip.
Default wait curves
The program uses default wait curves at nodes where you do not assign wait curves. The following diagram shows the default wait curve at the first boarding point.
Default wait curve for initial boarding
12
For transit services with a frequency of 60 vehicles per hour or more, the default wait time is set to half a minute. The default curve uses a constant wait time in this case because services with very small headways tend to have irregularly arriving vehicles, causing the relationship between wait time and headway to break down. The default wait curve for transfer points is half the headway of all services visiting the stop.
Rules for defining wait curves
The following rules apply to the coding/interpreting of wait curves: The first coded X-Y pair must have a minimum X-value of 1 and minimum Y-value of 0.5. Wait time (Y-axis) may not decrease as headway (X-axis) increases. Linear interpolation applies between coded points. The curve runs from the point (1- 0.5) to the first coded point. Wait time is fixed at 0.5 minutes for headways less than one minute. Extrapolation beyond the last coded point occurs at the same gradient as immediately below that point.
Only the route-evaluation process uses wait curves.
12
Public Transport Program Reports
Reports
This section describes the reports that the Public Transport program produces. You select reports using a variety of control statements. The program writes the reports to the main Cube Voyager print file unless otherwise stated. The program can produce the following reports: Enumerated routes Evaluated routes Fare matrices Transit line summary (including passenger hours and distance if loads are present) Transit line loadings Transfers between modes (transit and nontransit) Transfers between operators
The REREPORT control statement produces a series of basic reports that let you examine and understand the network-simplification and route-enumeration processes. See Network simplification on page 782 for examples of these reports.
12
Enumerated routes
You can produce a report of enumerated routes with the ROUTEO keyword and its subkeywords, REPORTI and REPORTJ. The program writes the report to the file specified by REPORTO.
Sample enumerated-route report
REnum Route(s) from Origin 1 to Destination 9 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 812 -> 9 lines PLB129A Cost=16.649 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 796 -> 796 lines PLB1-113A PLB129A 796 -> 799 -> 799 lines GMB1-39MB PLB144B PLB129A 799 -> 812 -> 9 lines PLB129A Cost=19.896 1 -> 773 773 -> 771 -> 771 lines GMB1-36A 771 -> 799 -> 799 lines GMB1-39MB 799 -> 812 -> 9 lines PLB129A Cost=17.364 1 -> 2052 2052 -> 2058 -> 806 lines ISL-UP 806 -> 812 -> 9 lines PLB129A Cost=19.896 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 806 -> 806 lines PLB127B PLB129A 806 -> 812 -> 9 lines PLB129A Cost=20.737 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 812 -> 9 lines PLB129A Cost=19.737
This example shows routes from zone 1 to zone 9. The first line for each route shows the access leg from the origin zone to the first boarding point. Subsequent lines for a route show pairs of transit and nontransit legs with the names of the transit lines running on the transit legs. The shown cost is used for selecting potential routes; it is not the cost used for evaluating routes.
12
The program will discard some of these routes for various reasons, such as a probability of use less than a user-specified minimum, or alighting and reboarding the same line. The Evaluated Routes report (Evaluated routes on page 762) lists routes that are actually used between the zones. In this example, the program finds five (potential) physical routes between zones 1 and 9. Some offer more than one combination of services.
Evaluated routes
You can produce a report of evaluated routes using either the ROUTEI or the ROUTEO keyword and the corresponding subkeywords REPORTI and TRACEI. The program writes the report to the file specified by REPORTO. Reports produced with REPORTI list routes taken; reports produced with TRACEI give a tabular output detailing component costs and summaries for each mode. When using multirouting, the report lists all routes used and the probability of taking each of them. Specify the required origin zones with the REPORTI or TRACEI subkeywords and the required destination zones with the REPORTJ or TRACEJ subkeywords. The following topics show: Example produced with REPORTI Example produced with TRACEI
12
Example produced with REPORTI

Sample evaluated-route report produced with REPORTI
REval Route(s) from Origin 1 to Destination 9 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 796 -> 796 lines PLB129A 796 -> 799 -> 799 lines PLB144B 799 -> 812 -> 9 lines PLB129A Cost= 17.249 Probability=0.0848007 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 796 -> 796 lines PLB1-113A 796 -> 799 -> 799 lines GMB1-39MB 799 -> 812 -> 9 lines PLB129A Cost= 17.096 Probability=0.0468973 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 812 -> 9 lines PLB129A Cost= 17.937 Probability=0.17571 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 806 -> 806 lines PLB127B 806 -> 812 -> 9 lines PLB129A Cost= 19.137 Probability=0.17571 1 -> 2052 2052 -> 2058 -> 806 lines ISL-UP 806 -> 812 -> 9 lines PLB129A Cost= 19.896 Probability=0.226877 1 -> 773 773 -> 771 -> 771 lines GMB1-36A 771 -> 799 -> 799 lines GMB1-39MB 799 -> 812 -> 9 lines PLB129A Cost= 15.764 Probability=0.163768 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 796 -> 796 lines PLB1-113A 796 -> 799 -> 799 lines PLB144B 799 -> 812 -> 9 lines PLB129A Cost= 17.249 Probability=0.00468973 1 -> 773 773 -> 769 -> 769 lines GMB1-36A 769 -> 812 -> 9 lines PLB129A Cost= 14.849 Probability=0.121547
12
This report shows multiple routes from zone 1 to zone 9, along with their probability of use. The first line for each route shows the access leg from the origin zone to the first boarding point. Subsequent lines for the route show pairs of transit and nontransit legs with the names of the transit lines running on the transit legs. The cost shown is the generalized cost of each route in minutes, weighted by the probability of use. This cost includes walk and invehicle times, and boarding and transfer penalties, but not wait time, which the program computes from the routes common segments for the origin-destination pair as a whole.
Example produced with TRACEI

Sample evaluated-route report produced with TRACEI
REval Route(s) from Origin 1129 to Destination 757 N: 1129 Mode WaitA TimeA Actual B/XPen Percvd Dist -> 5409 30 14.00 14.00 14.00 0.75 -> 4544 2 5.00 11.00 30.00 3.00 38.00 9.03 79(0.016) 80(0.953) -> 4538 31 3.00 33.00 41.00 0.25 -> 4209 7 7.50 34.85 75.35 1.00 91.85 8.92 -> 757 30 16.00 91.35 107.85 0.10 Mode TimeA Dist IWaitA XWaitA 2 11.00 9.03 5.00 0.00 7 34.85 8.92 0.00 7.50 30 30.00 0.85 31 3.00 0.25 Probability=0.5248 N: 1129 Mode WaitA TimeA Actual B/XPen Percvd Dist -> 5409 30 14.00 14.00 14.00 0.75 -> 4249 2 5.00 20.00 39.00 3.00 47.00 18.27 76(0.667) 79(0.333) -> 4201 31 1.30 40.30 48.30 0.11 -> 4209 7 7.50 17.70 65.50 1.00 82.00 4.53 -> 757 30 16.00 81.50 98.00 0.10 Mode TimeA Dist IWaitA XWaitA 2 20.00 18.27 5.00 0.00 7 17.70 4.53 0.00 7.50 30 30.00 0.85 31 1.30 0.11 Probability=0.47521 Total Lines(weight) 0.75 9.78 76(0.031) 10.03 18.95 949(1.000) 19.05
Total Lines(weight) 0.75 19.02 19.13 23.66 1359(1.000) 23.76
12
This report shows two possible routes from 1129 to 757. For each route, the report lists: Leg-by-leg information. The report contains a printed line for each leg, starting with the access leg, followed by alternating transit and nontransit legs, and ending with the egress leg. For each leg, the printed line shows destination node, mode, wait time, travel time, cumulative actual total cost, perceived boarding and transfer penalties, cumulative perceived cost, distance, cumulative distance, and transit lines used (along with probability). Mode information. For each mode used, the report lists actual travel time, distance, and wait times. Trip fare. If you model fares, the report includes the trip fare, in monetary units. Probability of taking the route.
12
Fare matrices
You can produce a report of fare matrices with the FAREMATI keyword in the REPORT control statement. The program writes the report to the main print file. The report shows the contents of the input fare matrices, specified with FILEI FAREMATI and used by fare systems defined by the FARESYSTEM control statement.
Sample fare-matrices report
FareMatrix(FMI.1.FROMTO) for FareSystem 3 (FAREZONE-FROMTO): -----------------------------------------------------------J: I=1 FareSystem 3 Tot= 11 -- --- ---------- ---- -1: 1 1 2 3 4 J: I=2 FareSystem 3 Tot= 14 -- --- ---------- ---- -1: 1 1 3 4 5 J: I=3 FareSystem 3 Tot= 20 -- --- ---------- ---- -1: 2 3 4 5 6 J: I=4 FareSystem 3 Tot= 20 -- --- ---------- ---- -1: 3 4 5 1 7 J: I=5 FareSystem 3 Tot= 23 -- --- ---------- ---- -1: 4 5 6 7 1
12
Transit line summary

You can produce a report summarizing transit lines with the LINES keyword in the REPORT control statement.
Sample transit-line-summary report (with line loadings)
REPORT LINES UserClass=Total Name Mode Op Stp Cr Distance Time Pass PassDist PassHr Sort=MODE ---------------------------------------------------------------------------------ISL-UP 1 1 14 13.60 13.56 28,407.36 15,403,939.52 2,557.14 ISL-DN 1 1 14 13.60 13.56 46,808.82 22,259,805.12 3,694.35 GMB1-29AA 7 11 3 2.46 6.48 1,295.35 39,401.16 15.01 GMB1-29AB 7 11 4 3.68 9.87 4,998.67 1,192,384.23 451.21 GMB1-53B 7 11 14 7.90 23.28 2.14 568.86 0.25 GMB1-55A 7 11 13 5.05 16.13 4,901.84 477,329.89 306.13 GMB1-49MA 7 11 5 2.70 8.28 16,684.93 2,308,165.02 1,202.95 GMB1-49MB 7 11 2 1.98 7.05 7,712.42 1,527,059.16 906.21 GMB1-24MA 7 11 10 6.07 17.53 31,436.51 8,892,119.27 3,785.20 GMB1-24MB 7 11 10 5.49 17.76 31,802.20 9,824,320.61 4,516.16 GMB1-2A 7 11 5 2.11 5.99 4,507.49 915,698.20 438.00 GMB1-2B 7 11 5 3.18 10.96 4,562.50 1,009,772.05 568.80 GMB1-16MA 7 11 4 8.97 20.90 5,178.26 4,630,383.81 1,797.44 GMB1-16MB 7 11 6 10.29 26.14 2,007.41 1,800,646.77 699.25 GMB1-1A 7 11 5 6.01 13.86 202.24 3,790.72 0.91 GMB1-1B 7 11 5 7.08 19.15 370.56 16,756.35 19.74 GMB1-39MB 7 11 7 8.25 22.77 21,992.27 7,540,680.36 3,531.89 GMB1-55B 7 11 12 4.92 12.67 2,796.67 1,090,492.38 465.26 GMB1-52A 7 11 6 8.79 22.07 8,460.99 4,409,590.96 1,836.13 GMB1-52B 7 11 6 8.79 22.07 10,497.51 6,561,755.16 2,713.20 GMB1-39MA 7 11 6 8.39 22.10 44,765.14 11,716,456.15 5,232.96
This example shows transit lines sorted by mode. Because the public transport network includes line loadings, this report includes passenger distance and passenger hours. This report shows data for all user classes. The program also produces a separate report for each user class. If the public transport network does not include line loadings, the program only reports transit line attributes once, as the attributes are common to all user classes.
12
Transit line loadings

You can produce a report of transit line loadings with the LINEVOLS keyword in the REPORT control statement.
Sample of transit-line-loading report
REPORT LINEVOLS UserClass=Total Name Mode Op N ON OFF VOL ------------------------------------------ISL-DN 1 1 ----------------------2072 7,526.20 -7,526.20 2070 -874.81 6,651.39 2068 20,072.95 1,692.68 25,031.66 2066 3,737.72 4,876.35 23,893.03 2062 7,132.78 1,290.47 29,735.34 2058 1,383.06 1,883.62 29,234.78 2056 1,817.37 13,423.42 17,628.73 2054 5,084.75 577.75 22,135.73 2052 45.97 15,108.40 7,073.30 2004 8.02 7,073.30 8.02 2001 -8.02 --
This example report shows the number of passengers boarding, alighting, and riding through the nodes of a transit line. This report shows only stopping nodes with some passenger activity because STOPSONLY and SKIP0 are set to T. This report shows data for all user classes. You can request a separate report for each user class. If the program performed crowd modeling with wait-time adjustments, the program would supplement reports showing all user classes with columns showing the flow-metered boarding, alighting, and through-ridership volumes.
12
Transfers between modes

When performing loading, the program automatically produces two reports showing transfers between modes: A report showing transfers between all modes (that is, transit and nontransit) A report showing transfers between transit modes (ignoring walk transfers between transit modes)
The program produces these reports for each user class and for all classes combined.
Sample of transfers-between-modes report
REPORT XFERSUM=MODE UserClass=1 MODE 1 7 8 11 33 34 ---------------------------------------------------------------------1 ----- 35,419.40 39,796.77 7 -- 131,189.92 63,228.77 10,669.03 124,326.24 19,008.94 8 -- 58,769.06 29,930.60 5,459.60 49,723.45 17,346.75 11 -- 10,255.88 2,931.91 1,629.01 3,849.26 116.51 33 38,743.98 126,731.07 47,398.96 444.35 --34 36,472.20 21,476.97 17,739.22 580.58 --MODE names: 1 = Train 7 = Bus 8 = Underground 11 = Light Rail 33 = Access/Egress 34 = Walk Xfer REPORT XFERSUM=TMODE UserClass=1 TMODE 1 7 8 11 ------------------------------------------------1 -- 21,476.97 17,739.22 580.58 7 19,008.94 131,189.92 63,228.77 10,669.03 8 17,346.75 58,769.06 29,930.60 5,459.60 11 116.51 10,255.88 2,931.91 1,629.01 MODE names: 1 = Train 7 = Bus 8 = Underground 11 = Light Rail 33 = Access/Egress 34 = Walk Xfer
12
Transfers between operators

When performing loading, the program automatically produces a report showing transfers between operators. The program produces this report for each user class and for all classes combined.
Sample of transfers-between-operators report
REPORT XFERSUM=OPERATOR UserClass=1 OPERATOR 1 11 14 19 ---------------------------------------------------1 -- 21,476.97 17,739.22 580.58 11 19,008.94 131,189.92 63,228.77 10,669.03 14 17,346.75 58,769.06 29,930.60 5,459.60 19 116.51 10,255.88 2,931.91 1,629.01 OPERATOR names: 1 = BR - Stratford - Lea Valley Services 11 = BR - Fenchurch Street 14 = BR - Upminster Branches 19 = BR - Liverpool Street - Via Stratford
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
12
Cost Fare
The route-evaluation process considers each component separately. The route enumeration process, described in Route enumeration cost calculation on page 775, uses a slightly simpler estimation. A trips generalized cost automatically includes walk and in-vehicle time; the cost might include wait time, boarding and transfer penalties, and fare, depending on the values of keywords in the FACTORS control statement. Generalized cost is a linear function of its components, weighted by coefficients. The coefficients let you: Reflect passengers perceived importance of each component Convert the components to a common unit
The Public Transport program measures generalized cost in time, using minutes as the s working units. Fares, if used, are input in monetary terms and converted into the corresponding time units. Subsequent sections provide details about individual components and their weighting factors.
Walk time (nontransit time)

Walking may occur at the following points in a trip: Between stop node and zone centroid, at the start and end of the trip Between stop nodes, as part of a transfer between services Between an origin and destination zone, without using any transit mode
You can develop walk links outside the Public Transport program and input the links to the program, or you can develop the walk links when developing the public transport network.
12
A links walk time (nontransit time) is typically the actual travel time. To convert the times to perceived values (for inclusion in generalized costs), you can weight the link times with the RUNFACTOR keyword.
Wait time
The program uses the combined headway of available transit services to compute the wait time at any boarding point. Specifically, the program computes wait time from wait curves that you specify. If you do not specify any wait curves, the program uses default wait curves. To represent passengers ability to control wait time at the start of a trip but not at transfer points, you may specify different wait curves for initial and subsequent boardings at each node. You define wait curves with the WAITCRVDEF control statement. You assign wait curves to nodes with IWAITCURVE and XWAITCURVE keywords in the FACTORS control statement. You can weight the wait times with the node-specific WAITFACTOR keyword. The program uses default wait curves at nodes where you do not assign wait curves. See Default wait curves on page 758 for a description of the default wait curves. When the program performs crowd modeling with wait time adjustments, passengers might experience additional wait time attributable to crowding. For example, a transit service might be so loaded that a passenger cannot board (and must wait for a later service). Similarly, a network bottleneck might occur (where demand exceeds capacity, and some passengers cannot proceed forward within the modeled period). You model these additional wait times with a node-specific WAITFACTOR keyword in the FACTORS control statement.
In-vehicle time
In-vehicle time is the time passengers spend travelling in a public transport vehicle for each transit leg of a trip. If a trip has more than one leg, the value is the total in-vehicle time for all legs.
12
You can weight in-vehicle time with a transit-mode-specific value specified with the RUNFACTOR keyword. When performing crowd modeling with link travel-time adjustments, the program also weights in-vehicle time with a crowding factor.
Boarding penalty
Boarding penalty is a fixed penalty applied at each boarding (that is, at the start of the trip) and at each interchange. You may specify separate penalties for each mode. The default penalty for each mode is zero (that is, no penalty). You specify boarding penalties by mode with the BRDPEN keyword.
Transfer penalty
Transfer penalty is the transit-mode-to-transit-mode interchange penalty, which represents the inconvenience of transferring between modes. The program applies this penalty at transfer points, even if there is walking between the two modes. The penalty is based on a combination of alighting and boarding modes. The transfer penalty applies in addition to the boarding penalty for the subsequent transit leg. For transfers between the same mode, you might set the transfer penalty to a negative value to counteract or reduce the boarding penalty applied to the subsequent leg of that mode. You can ban changes between modes by setting a high transfer penalty, such as 999, for that mode-to-mode combination. All mode-to-mode penalties default to zerothat is, there are no penalties by default. You specify transfer penalties with the XFERPEN keyword. You may add constants to transfer penalties with the XFERCONST keyword, and you may weight transfer penalties with the XFERFACTOR keyword.
12
Fare
By defining fare models, you can include fares in the routeevaluation and skimming processes. Fare models describe how the program computes the fare for part of a trip or for an entire trip. You define fare models with the FARESYSTEM control statement, and specify the input file with the FILEI control statement and FAREI keyword. You associate fare models with transit lines two ways: Directly with the LINE statement and FARESYSTEM keyword Through their mode or operator attribute, with the FACTORS control statement and FARESYSTEM keyword
Route enumeration cost calculation

Route enumeration is a heuristic process that identifies a set of discrete routes between zone pairs along with the probability that passengers will use the routes to travel between the zones. Data compression techniques improve the performance of the route-enumeration process. For example, the process bundles together transit legs with the same boarding and alighting points, and enumerates routes only for the cheapest leg in the bundle. (The process disaggregates transit leg bundles for analysis.) For this reason, the process cannot use all the components of generalized cost. The route-enumeration process converts the following components to generalized cost units: In-vehicle time, weighted by mode-specific factor specified with the RUNFACTOR (using the value of the bundles fastest transit line) Boarding penalty Wait time, weighted by WAITFACTOR and subject to a range defined by REWAITMIN and REWAITMAX
12
The route-enumeration process uses a simple estimate of wait time for each leg bundle. The process computes the headway for each bundles boarding node from the sum of the frequencies of the bundles legs. The process sets the wait time to half this headway, weighted by WAITFACTOR. Where necessary, the process adjusts the resulting value to fall within the range set by REWAITMIN to REWAITMAX. You can exclude wait time from the route-enumeration process by setting these factors to zero. Walk time, taken directly from nontransit legs and weighted by an appropriate RUNFACTOR
When modeling best paths (or when REBESTPATHCOST is T), the route-enumeration process handles some of these components differently. In this case: Calculations of wait and in-vehicle time depend on the value of
FREQBYMODE:
When true (default value), the process computes these times for individual modes (and the value for fastest mode subsequently used in enumeration). When false, the process computes these times across all modes in a transit leg bundle. In-vehicle time is based on the average value for lines in the transit leg bundle. The process uses the calculations described in SFM and SFCM examples on page 809 to discard any slow routes in the bundle and to obtain the required value. Wait time is calculated using initial or transfer wait curves and WAITFACTOR (as in the route-evaluation process). The process uses the headway of the transit-leg bundle (or the lines of a particular mode in the bundle) after discarding any slow routes. For best-path models, the route-enumeration process uses transfer penalties (based on XFERCONST, XFERFACTOR, and XFERPEN) when identifying discrete routes.
12
The route-enumeration process does not consider fares, and ignores transfer penalties except when modeling best paths. Instead, the route-evaluation process disaggregates transit-leg bundles by mode to apply transfer penalties. Using fares and transfer penalties with leg bundles during route enumeration could eliminate valid routes. For example, consider a banned transfer between transit modes 3 and 5. Routes transferring from a mode-3 leg to a mode-5 leg would be eliminated. However, suppose these legs are the top legs in bundles that contain legs of other modes. These other legs would also be eliminated. The route-enumeration process adds wait time to the time of each bundles top leg to obtain a transit-leg cost. The report produced by the TRNLEGS3 keyword in the REREPORT control statement shows the generalized cost of transit legs used during the route-enumeration process.
Modeling approach
This section discusses the algorithms that the Public Transport program uses. The program supports two distinct modeling methods: multirouting and best-path. For both modeling methods, the program finds attractive or reasonable routes, (that is, routes that have some probability of use), in three steps: network simplification, route enumeration, route evaluation. You can restrict modeling to consider just those routes that use a particular transit mode at some stage in the trip. This section discusses: Multirouting and best-path methods Network simplification Route enumeration Route evaluation Limiting selected routes to particular transit modes Advantages of the Public Transport program for multirouting
12
Multirouting and best-path methods

During a public transport trip, passengers must make decisions at several points on their route. When on a transit line, passengers might need to decide which stop to alight at (in order to transfer or walk to their destination). At the origin and on completion of a transit leg, passengers must decide where to board the next transit leg. At a stop, passengers must choose between the transit lines that enable progress toward the destination. A number of possible methods, or modeling philosophies, are possible at each decision point. The Public Transport program includes two distinct methods: Multirouting Evaluate multiple routes and calculate the probabilities of using each one. Best-path Identify a single best path route for an origindestination pair.
For example, suppose travelers waiting at node N have a choice between two routes to reach the trips destination. The first route uses line L, which runs every 20 minutes and takes 15 minutes to reach the destination after boarding. The second route uses line M, which runs every 30 minutes and takes 11 minutes to reach the destination. Either line offers an efficient effective route towards the required destination. Taking these values as components of the generalized cost (without need for further weighting), you can compute an expected travel time from the stop to the destination. In a multirouting model, travelers are prepared to board whichever bus comes first. There are a total of five services per hour. Assuming equal spacing of departures, the combined headway is 12 minutes and average wait is 6 minutes. The cost to the destination is the wait time plus travel time, either 11+6 or 15+6, that is, 17 or 21. Assuming route usage proportional to service frequency, the average time to destination is 19.4 minutes. In a best-path model, travelers choose between the two routes and then wait for a service on the chosen transit line (ignoring any service on the other line). Travelers assess attributes of each route: L
12
has an average wait of 10 minutes and travel time of 15 minutes, for a total cost of 25 minutes. M has an average wait of 15 and travel time of 11, for a total of 26 minutes. Therefore, travelers using the best-path method would select transit line L, with an average trip cost of 25 minutes. Model developers must decide between the two methods. The appropriate method might depend on externally imposed requirements or practices (for example, guidelines from government departments) or a choice regarding the suitability of each method. Many modelers prefer the multirouting method in cities with extensive, well-developed public transport systems.
Network simplification
To improve performance and to minimize memory and storage requirements, the Public Transport program simplifies the public transport network into a set of intermediate data structures: Transit legs Transit leg bundles Nontransit legs Line-zone leg Line-line legs
See Network simplification on page 782 for a description of these data structures.
Route enumeration
For multirouting modeling, the route-enumeration process finds all potentially attractive routes and enumerates them. The process follows three principles: The trip should move progressively from the origin to the destination. Travelers prefer simpler trips, that is, direct trips or trips that involve few transfers.
12
Travelers are unwilling to walk very long distances.
The route-enumeration process uses these principles to identify reasonable routes. First, the process establishes connectivity between transit lines. This step is analogous to travelers examining a map and identifying the sequence of lines they can use to travel from their origin to their destination. The process limits routes by choosing simpler trips and trips with shorter walking distances during line-to-line transfers. Next, the process identifies the route attributesbasic cost and number of transfersand compares them, selecting reasonable routes for evaluation. This step is analogous to travelers rejecting routes that are very long relative to more direct alternatives. For best-path modeling, the route-enumeration process identifies possible routes for the best single path between an origin and a destination. The route-enumeration process uses the same cost components as the route-evaluation process, with the exception of transfer penalties. The route-enumeration process allows for possible transfer-penalty values, and enumerates any route which potentially could be the best route. See Route-enumeration process on page 793 for a detailed description of this process.
Route evaluation
For multirouting models, the route-evaluation process takes the explicit list of reasonable routes between an origin and destination and determines which routes passengers will use to make trips and what fraction of passengers will use each route. The route-evaluation process treats the routes like a hierarchy of conditional choices: Each stop or branch point represents a decision whether to board a service, alight from a service, or walk elsewhere to board another service. The program uses conventional algorithms to forecast these individual choices. For example, the program uses information about the trip sequence to preclude alighting and reboarding the same service.
12
For best-path models, the route-evaluation process identifies the best path using a similar evaluation method, and assigns all demand to that route.
Limiting selected routes to particular transit modes

The Public Transport program uses the route-enumeration process to identify possible routes from an origin to a destination, followed by a the route-evaluation process to evaluate the routes. The enumerated routes may vary widely in characteristics, perhaps having different transfer points, and using different modes. Sometimes you might want routes to use a particular mode. Earlier software packages used biases to attract travelers toward one mode and away from other modes. However, biasing could lead to modeling distortions affecting route costs or identification of the best route. With the Public Transport program, you need not use biases. Instead, you can specify a must-use-modea mode that must be used during at least one leg of a public transport route in order for the Public Transport programs route-enumeration process to select that route.
Advantages of the Public Transport program for multirouting

Some software packages trace paths from all zones to a particular zone or vice-versa. Such paths do not retain the history of a trip at a node (that is, how the path reached the node or where the path came from). When using multiroute paths, such packages cannot easily extract route-based information, such as station-to-station movements, matrices of trips using selected links or transit lines, or mode-to-mode and operator-to-operator transfers. The Public Transport program finds discrete multiple routes between pairs of zones. Therefore, unlike traditional software packages, the Public Transport program operates at the zone-pair level rather than at the zonal level. The Public Transport program requires more computational time but produces more useful and better quality results.
12
The Public Transport program addresses other common problems associated with multirouting: Calculating wait time at stops using the combined frequency of visiting services Modeling access, egress, and transfer choices Modeling combination of frequent and infrequent services
Network simplification
Public transport networks are often quite detailed and data intensive. To improve algorithm performance and minimize memory and temporary disk storage, the Public Transport program simplifies the network for enumerating and storing routes. The program stores the simplified network in intermediate data structures, which you can examine to gain an understanding of how multirouting works in the Public Transport program. Use the DELMODE, DELACCESSMODE, and DELEGRESSMODE factors to remove legs of particular modes from the network representation. The program does not use specified legs at any stage in the modeling. This section introduces the network representations used for: Transit legs Transit-leg bundles Nontransit legs Line-zone legs Line-line legs
12
Transit legs
A transit leg is a trip segment, from a boarding point to an alighting point, that uses a single transit line. Travel on the transit line can be over one or more links in the public transport network. (A trip consists of an access leg, and one or more pairs of transit leg bundles and nontransit legs, the last of which is the egress leg.) Use the REREPORT control statement and LINES keyword to produce a line-attribute report.
Line-attribute report
REPORT: LINES Int Fare #Line #Stop Line Line# DIR Mode OP HDWAY Type Nodes Nodes Name --------------------------------------------------20 (f) 7 11 5.00 0 10 5 GMB1-1B DisLine Stop Node Time tance Node# Node# -------------------------------------727 0.00 0.00 1 1 -897 0.28 0.12 2 0 -947 0.97 0.42 3 0 875 1.99 0.80 4 2 751 5.54 1.15 5 3 -881 6.36 1.55 6 0 748 7.10 1.92 7 4 -745 8.40 2.39 8 0 -746 12.33 4.16 9 0 747 19.15 7.08 10 5
12
Use the REREPORT control statement and TRNLEGS3 keyword to produce a line-ordered transit-leg report.
Sample transit-leg report for the GMB1-1B transit line
REPORT: TRANSIT LEGS III (Legs for Lines) (REnum Time = actual time * RUNFACTOR + BRDPEN) Int Fare #Line #Stop Line Line# DIR Mode OP HDWAY Type Nodes Nodes Name --------------------------------------------------20 (f) 7 11 5.00 0 10 5 GMB1-1B Top ON OFF Time Time DisLeg Node Node Actual REnum tance ---------------------------------------------727 875 1.99 4.99 0.80 727 751 5.54 8.54 1.15 727 748 7.10 10.10 1.92 * 727 747 19.15 22.15 7.08 875 751 3.55 6.55 0.35 875 748 5.11 8.11 1.12 * 875 747 17.16 20.16 6.28 751 748 1.56 4.56 0.77 * 751 747 13.61 16.61 5.93 * 748 747 12.05 15.05 5.16
* Top leg of a leg bundle, see Transit-leg bundles.
Transit-leg bundles
A transit-leg bundle is a collection of transit legs that use different transit lines but board and alight start at the same node. Transit-leg bundles have the following properties: The top leg of the bundle is the cheapest in terms of travel time (in the example all legs within bundles have the same time). They may or may not traverse the same links of the underlying network.
12
The route-enumeration process treats transit-leg bundles as single entities, thus simplifying and reducing the data to examine and enumerate. The program individually evaluates each leg within a transit-leg bundle when determining attractive routes for loading and skimming. Use the REREPORT control statement and TRNLEGS2 keyword to produce a node-ordered transit-leg-bundle report.
Excerpt from node-ordered transit-leg-bundle report
REPORT: TRANSIT LEGS II (Leg Bundles from Nodes) (REnum Time = Actual Time * RUNFACTOR + BRDPEN) (And top leg in Bundle includes Estimated Wait time for Bundle) Top ON OFF Time Time DisLine Leg Node Node Actual REnum tance Name --------------------------------------------------* 875 753 5.03 6.03 0.83 GMB1-24MA 875 753 5.03 5.53 0.83 PLB1-113A 875 753 5.03 5.53 0.83 PLB129A 875 753 5.03 6.04 0.83 RES-903R * 875 757 5.32 6.32 1.06 GMB1-24MA 875 757 5.32 5.85 1.06 PLB1-113A 875 757 5.32 5.85 1.06 PLB129A 875 757 5.32 6.38 1.06 RES-903R * 875 765 6.30 9.30 1.66 GMB1-24MA * 875 774 7.75 10.75 1.95 GMB1-24MA * 875 773 8.26 11.26 2.35 GMB1-24MA * 875 776 13.04 16.04 4.30 GMB1-24MA * 875 778 17.37 20.37 5.97 GMB1-24MA * 875 751 3.55 4.55 0.35 GMB1-2B 875 751 3.55 3.55 0.35 GMB1-24MA 875 751 3.55 3.55 0.35 GMB1-1B 875 751 3.55 3.91 0.35 PLB1-113A 875 751 3.55 3.91 0.35 PLB129A 875 751 3.55 4.26 0.35 RES-903R * 875 748 5.11 7.36 1.12 GMB1-2B 875 748 5.11 5.11 1.12 GMB1-1B
This sample shows transit legs from node 875, including three sets of leg bundles: from node 875 to nodes 753, 757, and 751. When multiple lines connect node 875 to an alighting node, the report marks the top line (the fastest line or the first line, if all have equal
12
time) with *. All legs in a bundle have the same actual in-vehicle time, but the REnum time for the bundles top leg includes an estimate of the bundles waiting time. (Do not confuse this waiting time with the wait time calculated during the route-evaluation process. See Generalized cost on page 771.)
Nontransit legs
Nontransit legs are minimum-cost segments, traversed by nonmechanized modes. Nontransit legs connect: Zones and stop nodes or stop nodes and zones that allow access to and egress from the transit system Two stop nodes that allow a transfer between two lines
Nontransit legs may traverse none (special case), one, or multiple physical links. The program derives leg attributes from link attributes. The program can generate nontransit legs with the GENERATE control statement, input user-specified nontransit legs, or do both. The program associates a cost with these nontransit legs. The program automatically generates a third type of notional nontransit leg, which allows transfers between two lines visiting the same node. Such nontransit legs do not have any associated cost. Boarding and transfer costs apply to both types of transfersthose occurring at a node and those between two nodes connected with a physical nontransit leg.
12
Use the REREPORT control statement and ACCESSLEGS, EGRESSLEGS, and XFERLEGS keywords to produce nontransit-leg reports.
Sample nontransit-leg report: REREPORT ACCESSLEGS
REPORT: ACCESS LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------1 773 2.56 0.25 33 1 2052 8.70 0.36 33 1 3674 2.70 0.18 33 2 778 1.36 1.06 33 3 749 3.12 0.78 33 4 750 0.40 0.31 33 4 875 1.52 0.32 33 4 2004 7.52 0.41 33 5 959 2.70 0.11 33 6 796 1.92 0.38 33 6 800 1.92 0.39 33 6 2054 5.40 0.53 33 6 2056 5.92 0.43 33
Sample nontransit-leg report: REREPORT EGRESSLEGS

REPORT: EGRESS LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------703 19 0.64 0.23 33 705 19 0.96 0.19 33 709 19 0.96 0.70 33 714 20 1.32 0.22 33 716 20 1.80 0.24 33 721 21 1.68 0.42 33 725 22 6.00 0.24 33 728 22 0.52 0.36 33 730 22 0.76 0.20 33 734 22 0.80 0.30 33 735 23 2.64 2.46 33 747 24 1.72 0.43 33 749 3 3.12 0.78 33
12
Sample nontransit-leg report: REREPORT XFERLEGS

REPORT: TRANSFER LEGS DestiDisOrigin nation Time tance Mode ---------------------------------------701 701 0.00 0.00 -1* 702 702 0.00 0.00 -1 703 703 0.00 0.00 -1 800 800 0.00 0.00 -1 800 2056 4.00 0.04 34 803 803 0.00 0.00 -1 806 806 0.00 0.00 -1 806 2058 4.00 0.27 34 813 813 0.00 0.00 -1 813 2060 4.00 0.16 34 823 2062 4.00 0.11 34 830 830 0.00 0.00 -1 830 2066 4.00 0.02 34 837 837 0.00 0.00 -1 838 838 0.00 0.00 -1 838 2072 3.00 0.11 34
* -1 indicates a direct transfer, without any walking.
Line-zone legs
During network simplification, the program expands access and egress nontransit legslegs from zone to stop node and vice versainto zone to line and line to zone legs. The program stores line-zone legs as pointers to the corresponding access and egress nontransit legs along with some additional information that helps improve the performance of the route-enumeration algorithm. When multiple access and/or egress legs exist between a zone and a line, the program might eliminate some legs or restrict their use to ensure that routes starting or terminating on a line use distinctive segments and do not overlap. For best-path models, the program uses all connectors to ensure identification of the best route; because the program selects exactly one best route, overlapping segments are not possible. For multirouting models, the program eliminates multiple access legs by applying the following rules:
12
Among a set of legs accessing consecutive stops (disregarding intermediate nonstopping nodes), select the leg with the least generalized cost and discard the others. (Between legs of equal cost, select the downstream leg.) Always retain the first access leg (that is, the leg connected to the transit lines earliest stop). If the cost of the first access + riding to the next is more than the cost of the next access, those boarding at the first access may only ride until the stop before the next access. If the cost of the first access + riding to the next is less than the next access, discard the next access. Each access has a stop up to which those boarding can ride; either to the stop before the next valid access or to the end of the line.
For multirouting models, the program eliminates multiple egress legs by applying the following rules: Among a set of legs providing egress from consecutive stops (disregarding intermediate nonstopping nodes), select the leg with the least generalized cost and discard the others. (Between legs of equal cost, select the upstream leg.) Always retain the last egress leg (that is, the leg connected to the transit lines latest stop). If the cost of an egress leg is more than the cost of riding to the next + next egress, discard the leg. If the cost of the an egress leg is less than the cost of riding to the next + next egress, then only those boarding after the current egress can use the next one. Each egress has a stop that specifies the beginning of a range of valid boarding stops; this may be the stop after the previous valid egress or the beginning of the line.
Both sets of rules apply to circular lines.
12
Use the REREPORT control statement and LINEZONLEG1 LINEZONLEG2 keywords to produce line-to-zone nontransit-leg reports.
Sample line-ordered line-to-zone nontransit-leg report (REREPORT LINEZONLEG1)
REPORT: LINE ZONE I (In Line Order) Origin Dest Dis- Access/ Line Node Node Time tance Egress Name --------------------------------------------6 800 1.92 0.39 Access GMB1-49MA 800 6 1.92 0.39 Egress GMB1-49MA 7 803 1.52 0.41 Access GMB1-49MA 803 7 1.52 0.41 Egress GMB1-49MA 8 814 0.88 0.12 Access GMB1-49MA 814 8 0.88 0.12 Egress GMB1-49MB 3 749 3.12 0.78 Access GMB1-2A 22 728 0.52 0.36 Access GMB1-2A 728 22 0.52 0.36 Egress GMB1-2A 749 3 3.12 0.78 Egress GMB1-2B 4 875 1.52 0.32 Access GMB1-2B 875 4 1.52 0.32 Egress GMB1-2B 15 852 1.52 1.33 Access GMB1-29AA 855 16 1.80 0.97 Egress GMB1-29AA 852 15 1.52 1.33 Egress GMB1-29AB 16 855 1.80 0.97 Access GMB1-29AB
12
Sample zone-ordered line-to-zone nontransit-leg report (REREPORT LINEZONLEG2)

REPORT: LINE ZONE II (In Zone Order) Origin Dest Dis- Access/ Line Node Node Time tance Egress Name --------------------------------------------1 773 2.56 0.25 Access GMB1-24MA 1 773 2.56 0.25 Access GMB1-24MB 1 773 2.56 0.25 Access GMB1-36A 1 773 2.56 0.25 Access GMB1-36B 1 2052 8.70 0.36 Access ISL-UP 1 2052 8.70 0.36 Access ISL-DN 773 1 2.56 0.25 Egress GMB1-24MA 773 1 2.56 0.25 Egress GMB1-24MB 773 1 2.56 0.25 Egress GMB1-36A 773 1 2.56 0.25 Egress GMB1-36B 2052 1 8.70 0.36 Egress ISL-UP 2052 1 8.70 0.36 Egress ISL-DN 2 778 1.36 1.06 Access GMB1-24MB 778 2 1.36 1.06 Egress GMB1-24MA 3 749 3.12 0.78 Access GMB1-2A 749 3 3.12 0.78 Egress GMB1-2B 4 750 0.40 0.31 Access PLB1-113B 4 750 0.40 0.31 Access PLB129B 4 750 0.40 0.31 Access PLB127A 4 750 0.40 0.31 Access PLB127B 4 750 0.40 0.31 Access RES-91R
Line-line legs
During network simplification, the program expands nontransit legs between stop nodes, direct transfers at the same stop node, and walk transfers between stops into line-to-line legs. The program stores line-line legs as pointers to the nontransit transfer legs along with some additional information that improves the performance of the route-enumeration algorithm. The route-enumeration process eliminates some transfer legs. When generating line-to-line legs, the program applies the following rules:
12
For multirouting, among multiple connectors between consecutive stops on a from-line and consecutive stops on a to-line, retain only the lowest-cost connector; discard the others. Do not permit transfers from a transit lines first node; passengers must use the line before transferring. Do not permit transfers to a transit lines last node. For circular lines with the same first and last nodes, permit boarding at the first node and alighting at the last node. For multirouting, prohibit transfers involving backtracking, such as if the node prior to alighting is the same as the one after boarding. If two lines traverse the same physical route with the same stop characteristics, record only one transfer location for consecutive stops. For example, consider the following transit lines.
Interchanges between two parallel lines
In this case, the program only records one transfer location between Lines A and B instead of fourthe last stop. The program relaxes this restriction during route evaluation to give flexibility in transfer location, especially when modeling crowding. However, if stop 2 is a stopping node for line A and not for line B, then the program records two transfer locations: one at stop 1 and one at stop 4 (representing transfers at stops 3 and 4). If two lines meet at nonconsecutive stops, diverging between them, the program records a transfer location at each stop where they meet.
12
Use the REREPORT control statement and LINELINELEG keyword to produce line-to-line transfer-leg reports.
Sample line-to-line transfer-leg report (REREPORT LINELINELEG)
REPORT: LINE TO LINE LEGS From/To From/To From/To LineNode NodeSeq# LineName -----------------------------799 7 GMB1-49MA 799 14 PLB144A 806 4 GMB1-49MA 806 7 PLB144B 806 4 GMB1-49MA 806 34 PLB129A 799 7 GMB1-49MA 799 14 PLB129B 806 4 GMB1-49MA 2058 13 ISL-UP 806 4 GMB1-49MA 2058 16 ISL-DN 800 6 GMB1-49MA 2056 10 ISL-UP 800 6 GMB1-49MA 2056 19 ISL-DN 799 7 GMB1-49MA 799 1 GMB1-39MA
Route-enumeration process
Route enumeration is a heuristic process that identifies a set of discrete routes between zone pairs along with the probability that passengers will use the routes to travel between the zones. Use keywords in the FACTORS control statement to control the routeenumeration process. The program measures trip cost differently during routeenumeration than during route-evaluation. See Route enumeration cost calculation on page 775. Route enumeration has three distinct stages: Finding minimum-cost routes
12
Establishing connectivity between lines Enumerating routes
The process varies only slightly when you specify a must-use mode. See Enumerating routes with a must-use mode specified on page 798.
Finding minimum-cost routes

The route-enumeration process finds minimum-generalized-cost routes between zone pairs to establish a baseline cost. Each route has an access leg, and one or more pairs of transit and nontransit legs, the last of which is an egress leg. Using explicit couples of transit and nontransit legs is consistent with the multirouteenumeration process, described in Enumerating routes on page 797. Because the process starts with transit-leg bundles rather than individual transit legs, the process might disaggregate a minimumcost route into one or more discrete routes. For example, the following minimum-cost route is a collection of 14 individual routes:
Route(s) from Origin 1 to destination 100 1 -> 1276 1276 -> 1572 -> 1583 lines 744 746 1583 -> 1654 -> 100 lines 399 476 478 486 489 493 495
where: Node pair 1->1276 is the access leg from node 1. Triplet 1276->1572->1583 represents a transit leg between node 1276 and node 1572 on line 744 or 746, and a nontransittransfer leg between node 1572 and node 1583. Triplet 1583->1654->100 represents a transit leg between node 1583 and node 1654 on line 399, 476, 478, 486, 489, 493, or 495, and an egress leg between node 1654 and node 100.
12
The route via lines 744 and 399 will have the best travel cost; the other routes may have the same or slightly longer vehicle travel time. The route minimizes the generalized cost, not the number of transfers. Therefore, identified routes might have more than MAXFERS transfers. However, you can reflect the impact of transfers in the generalized cost with sensible boarding penalties. You can specify a spread, an upper cost limit for routes between an O-D pair when using multirouting. Select the function for calculating the spread with the SPREADFUNC keyword, and specify function parameters with the SPREADFACT and SPREADCONST keywords. The route-enumeration process uses the costs from the minimum cost routes and the spread to determine a maximum cost value for reasonable routes to that destination. Similarly, to set the maximum number of transfers permitted on reasonable routes to a destination, the route-enumeration process uses the number of transfers from the minimum-cost routes along with EXTRAXFERS1 and EXTRAXFERS2. Minimum-cost routes minimize some combination of userspecified trip attributes. Passengers might not select such routes. This is a reason to prefer multirouting, which includes both the direct and indirect routes in the full list of enumerated routes. If a destinations minimum-cost route uses more than MAXFERS transfers and the route-enumeration process has identified no other routes, then the process will enumerate this single route provided the route has no more than AONMAXFERS transfers and the route meets any must-use-mode requirements.
Establishing connectivity between lines

For each transit line, the route-enumeration process generates a set of connectors that describe available connections with other transit lines. Connectors are subject to constraints imposed by the keywords MAXFERS, EXTRAXFERS1, and EXTRAXFERS2.
12
Each connector consists of a set of lines: the from line, the to line, and intervening lines required to reach the to line. The connectors length (that is, the number of transfers) is controlled by the three keywords mentioned. The route-enumeration process only generates connectors for lines that have access legs from origin zones specified with the ROUTEO keyword and I subkeyword. The default configuration specifies all zones, and the process builds connectors for all lines. When generating connectors, the process treats lines like nodes and treats line-to-line connections like links in a network. The process stores connectors in a very compressed form; at this stage the process only requires the number of transfer points and the lines reached. The process examines alternative transfer points between lines when enumerating the routein the next stage. For example, consider the illustrated public transport network.
Simple public transport network illustrating line connectivity
For this network, the route-enumeration process generates the following connectors for line A: Line A to line B (note there are two interchange points between these lines) Line A to line C via line B Line A to line C via line D Line A to line D
12
Line-to-line legs handle all transfersdirect, between lines A and B and lines B and C, and by walking, between lines A and B and lines A and D.
Enumerating routes
After generating the connectors for a transit line, the routeenumeration process enumerates routes for each selected origin zone connecting to the line via a valid access leg. The process uses two steps: Expand routes with viable connections Record the beginning of the first route: origin zone and nontransit (access) leg. Examine the transfer points between the first two lines of the connector. If the transit leg used on the first line is the bundles top leg, and the time to the next boarding point (that is, the sum of time for transit and nontransit legs) is within the spread established earlier, and the number of transfers meets the constraints set by MAXFERS, EXTRAXFERS1 and EXTRAXFERS2, extend the route by the transfer. Examine each interchange between the two lines in the same way. Repeat the process for the subsequent lines in the connector set until connections have been fully expanded. Output valid routes Examine expanded routes to find routes that link to nontransit legs terminating in zones. If the complete route between the O-D pair meets the spread, transfer, and destination-zone selection (ROUTEO J) criteria, output as a route between that O-D pair.
12
For example, consider the connector, line A to line C via line B, shown in the example in Establishing connectivity between lines on page 795. The route-enumeration process generates the routes in the following table.
Origin Zone O O O O O Nontransit Leg O-A (access) O-A (access) O-A (access) O-A (access) O-A (access) A (ride) A (ride) A (ride) A (ride) A-B1 (walk) A-B2 (direct) A-B1 (walk) A-B2 (direct) C (ride) C (ride) C-D (egress) C-D (egress) Transit Leg Nontransit Leg Transit Leg Nontransit Leg Destination Zone x x x D D
The process does not re-record the common parts of routes, shown in italics.
Enumerating routes with a must-use mode specified

When enumerating routes required to use a particular transit mode, the route-enumeration process uses a similar procedure. If you specify two or more must-use modes, the process enumerates any route that uses at least one of the modes. When establishing the minimum-cost route, the process considers all possible routes, regardless of whether they use the specified transit modes. For a particular origin-destination pair, the process calculates a cost limit using spread factors as described in Finding minimum-cost routes on page 794. If this value exceeds the total of the cost (along the minimum-cost path) plus MUMEXTRACOST, then the process reduces the cutoff value to this total. The limit on transfers is based on the number of transfers on the minimum cost route, EXTRAXFERS1 and EXTRAXFERS2.
12
The route-enumeration process only outputs routes that use a specified must-use mode at some point in the trip. The process enumerates routes if at least one line in the bundle uses the specified mode. The route-evaluation process eliminates routes that do not use the specified transit mode.
Route-evaluation process
The route-evaluation process calculates the probability of use for each of the enumerated routes between zone pairs. The process discards enumerated routes that fail to meet certain criteria, such as routes with a probability of use less than the minimum specified by CHOICECUT. Before computing probabilities, the process removes routes that alight and reboard the same service. See Generalized cost on page 771 for a description of the trip cost used in route evaluation. The remainder of this topic presents: Methodology of route evaluation Deriving cost used Models applied at decision points
Methodology of route evaluation

The route-evaluation process uses a simple tree structure to represent the possible routes from an origin to a destination. (The process compresses data for efficiency.) Starting at the origin, passengers might use one or more access legs (first-level branches). At a stop, passengers choose between one or more transit alternatives for the next stage of the trip. One or more second-level branches linked to the first-level branch represent the available choices. Passengers continue, making
12
choices from additional branches, until reaching their destination. All routes arrive at the same destination, though they arrive via different branches. If routes have a must-use mode, the route-evaluation process checks to ensure that all routes satisfy the condition. (The routeenumeration process only ensures that at least one line in a transitleg bundle satisfies the condition.) Like the calculation of hierarchic logit models, the route-evaluation process calculates routes in two steps, passing through the data tree twice. For multirouting models, the first pass starts at the destination zone and calculates the conditional probabilities of each alternative at any decision point in the tree structure. (Trips arriving at the node may proceed towards the destination along any of the alternative next-level branches. Conditional probabilities define what proportion of the trips arriving at a node proceed along each alternative branch.) The second pass starts at the origin, and calculates the probability of choosing each discrete route. This is simply the product of all conditional probabilities along the route. For best-path models, the process uses the two-pass algorithm, but assigns all demand at any decision point to the cheapest alternative. The expected (generalized) cost to destination is the cost along a discrete route. Because demand along a discrete route is not divided among alternatives, the composite cost obtained from skimming is identical to the routes generalized cost. When the decision tree includes walking or alternative alighting choices, the process selects the cheapest route to the destination and discards all other alternatives. When making transit-line choices, the process uses the servicefrequency model; the process does not support the servicefrequency-and-cost model. The calculations of the servicefrequency model are described in Deriving cost used on page 801, Models applied at decision points on page 803, and
12
SFM and SFCM examples on page 809. For multirouting models, the process allocates routes assuming all reasonable lines forward from a node (as with multirouting), but for best-path models, the process allocates specific routes. By default, the process computes service-frequency-model calculations for identical-mode lines in a transit-leg bundle. However, when FREQBYMODE is set to F, the calculations consider all lines in a transit-leg bundle, without separating by mode. For each route forward, the process computes the expected cost to destination. The process identifies the cheapest transit-leg bundle/mode combination (or transit-leg bundle when FREQBYMODE is set to F) and allocates all demand to that route forward towards the destination.
Deriving cost used

The route-evaluation process computes a single expected cost to destination (ECD) from any choice or decision point in a trip to the destination. Often called composite cost, the process uses this generalized cost for calculating the probability that passengers will use alternative routes. Adding new services or improving existing services does not increase the costimproving service enhances passenger utility. At points close to the destination, the costs are usually simple. For example, at the start of the egress leg, the cost of the leg is the cost to reach the destination. At points further from the destination, where there are alternative routes, the process combines the costs to form a single value for the expected cost to destination from a single point. For multileg trips, the process computes the expected cost to the destination for each leg, working away from the destination. Computed at decision points using the composite-cost formula, the cost includes walk, transit, and wait times.
12
At choices between walking and alighting transit, the process uses logit models. The logit composite cost formula combines costs, producing a single value that represents the set of alternatives:
1.0 C ( comp ) = --------- ln
e
alt
( ECD alt )
Where: C(comp)
is the composite cost is a scale parameter which reflects the travelers sensitivity to cost differences is the expected (generalized) cost to destination via a particular alternative
ECDalt
At choices between transit alternatives, the process computes the cost to the destination by adding the cost of the transit leg (including boarding and transfer penalties) and the expected cost to the destination from the end of the transit leg. Then, the process combines the values for the transit alternatives into a single value for the expected cost from the node to the destination. This is calculated as the average of the costs associated with each alternative (weighted by the probability of passengers taking the alternative). In calculating the transit element of the expected cost to destination, the process applies an additional condition to ensure that adding (or improving) services does not increase costs. Specifically, the process examines each service operating between a pair of boarding and alighting points and includes the service if the resulting reduction in wait time exceeds the resulting increase in travel time. The process ensures that the expected time to the destination from the boarding node improves when a service is included in the set of attractive alternatives. This set of services is known as the basic choice set.
12
Models applied at decision points

This section describes the mathematical models that calculate the conditional probabilities for choices made at a routes decision points. Models are available for cases where there are: Walk choices Transit choices Alternative alighting choices Opportunities for transfer
Walk choices
The route-evaluation process applies the walk-choice model when passengers have alternative walk choices available. For example, when passengers leave the origin or alight from a service, they might walk to their destination, board a different line at that stop, or walk to another stop for the next transit leg. This model has a logit structure:
i ai e P ( walktoi ) = ---------------------------------------------- ( CW i + ECD j ) e
( CW + ECD )
12
Where: P(walk to i)
is the probability of walking to boarding stop i is the scaling factor for the model (LAMBDAW) is the walk (generalized) cost to the boarding stop i is the cost weighting factor (between 0 and 1), specified by ALPHA. A value of 1 indicates that the walk and onward costs have equal weight; lower values indicate that the walk cost has more influence than onward cost in the travellers choice. For example, a travellers willingness to walk may relate to familiarity with the network. is the expected (generalized) cost to destination from i. is the expected (generalized) cost to destination from j.
CWi
ECDi ECDj
Composite cost adjustment for ALPHA
The difference between the average and composite cost values, calculated as part of any logit model, represents the value of choice, or the benefit travelers gain from choosing between available alternatives. When the ALPHA value that the walk-choice model uses is less than 1.0, the cost from the end of the walk leg to the destination is discounted. The composite-cost specification, shown above, represents the true cost to the destination (or trip cost), and has a different numeric value from the discounted form. To adjust for an ALPHA value less than 1.0, the process estimates a composite cost consistent with the nondiscounted cost to the destination. First, the process uses ALPHA to calculate the value of choice for the walk-choice model. Next, the process subtracts this value of choice from the average cost (evaluated with ALPHA set to 1.0) to estimate the nondiscounted (true) composite cost.
12
Impact of LAMBDAW
The scaling factor LAMBDAW controls the shape of the logit curve used to allocate passengers to alternatives at each decision point. Large the scaling factors produce a smaller spread of trips between alternativesthat is, more trips are allocated to the best route. Conversely, low scaling factors produce trips spread over a wider range of alternatives.
Impact of the different values of scaling factor LAMBDAW
The X-axis shows the difference between the time by service i, ECDi, and the time by the best service, ECDbest. The Y-axis shows the proportion of trips allocated to the longer choice when a binary choice is available. The diagram plots three different values for the scaling factor: 0.2, 0.5, and 1. The curve for LAMBDAW = 0.5 shows that a choice five minutes longer than the best would be allocated 7.6% of the total trips. With a scaling factor of 0.2, the longer route gets 26.9% of trips, but with a scaling factor of 1.0, the longer route gets only 0.67% of trips. Thus, longer routes get a larger share of the trips as the scaling factor is reduced.
12
Transit choices
Two models are available to allocate passengers to the transit choices available at a stop: the service-frequency model (SFM) and the service-frequency-and-cost model (SFCM). SFM considers only service frequency while SFCM also considers the cost to the destination. See SFM and SFCM examples on page 809 for examples that show how the two models treat transit choices at a stop.
Service-frequency model
Applied at stops with a basic set of transit choices, the servicefrequency model calculates the conditional probabilities of the individual lines in proportion to their frequency. The model is equivalent to travelers who arrive randomly without knowledge of the timetables and take the first reasonable service forward from the node.
Frequency lineI P uselineI = ----------------------------------------------Frequency lineK
where: P(use line l) is the probability of using line l.
Frequency(line l) is the frequency of line l (in services per hour). Frequency(line k) is the frequency of line k (in services per hour).
Service-frequency-and-cost model
The service-frequency-and-cost model is an extension of the service-frequency model. The model assumes that travellers have knowledge of the travel time to the destination associated with each of the alternative routes, and that the traveller is less willing to use slower alternatives. This model defines its own set of transit choices, which may be different from the basic choice set described in Deriving cost used on page 801.
12
To define a set of transit choices, the model selects the line with lowest expected cost to the destination. Next, the model considers the next fastest line. If that line passes the validity test, the model adds the line to the set of selected lines and repeats the process, considering the next fastest line. Once a line fails the validity test, the process terminates and the model uses the set of lines currently selected as possible routes to the destination. The validity test computes the lines excess time the difference between its time to destination and the average value for the lines already selected (excluding wait time at the stop). The test compares the lines excess time to the expected cost of waiting (which is based on the headway of the combined services already selected, and any wait factors): If the excess time has a value of zero (that is, the line is no slower than those already selected), then the line is always a valid choice. If the excess time is more than the expected cost of waiting, then the line is not valid; travellers are better off ignoring this line and waiting for the next service from the selected set. If the excess time is greater than zero but no more than the expected cost of waiting, the line is valid some of the time. Specifically, excess time divided by the cost of waiting defines the proportion of time that travellers are better off ignoring the line. Therefore, one minus this proportion defines the probability of using the line when its service arrives at the stop.
As the probability of use varies between lines, the frequency of the combined services takes account of probability of use, as follows:
Frequency ( combined ) =
P(use l) Frequency(line l)
l
12
where: P(use l) Frequency(line l) is the probability of using line l when a service is at the stop. is the frequency of the line l (in services per hour).
Frequency(combined) is the combined frequency of a set of selected lines (in services per hour). During loading, the proportion of demand using a particular line is given by:
P (use l) Frequency (line l) Pr (line l) = -------------------------------------------------------Frequency (combined) Alternative alighting choices
The route-evaluation process applies the alternative-alighting model when a line has two or more valid alighting points. This model has a logit structure similar to the walk-choice model:
e P (alight at i) = ------------------------- ECD j e
ECD i
12
where: P(alight at i) is the probability of alighting at stop i.
is the scaling factor for the model (LAMBDAA).

NOTE: LAMBDAA affects the choice of alighting points
just as LAMBDAW affects walk choices. For an example, see Impact of the different values of scaling factor LAMBDAW on page 805. ECDi ECDj is the expected (generalized) cost to destination via alternative alighting point i. is the expected (generalized) cost to destination via alternative alighting point j.
Opportunities for transfer
At transfer points between transit services, the route-evaluation process applies a combination of models. First, the walk-choice model allocates demand between true walk alternatives and an imaginary alternative that represents the transit services available at the node. Next, the service-frequency model allocates the transit demand to the various services at the stop.
SFM and SFCM examples

This section provides examples of the service-frequency model and the service-frequency-and-cost model: Example of the service-frequency model Example of the service-frequency-and-cost model
Example of the service-frequency model

This example shows: Choices available Results of the service frequency model
12
Choices available
(6) (4) (1) Line 1 2 3 4 5 (2) TravelTime 20 21 22 24 26 (3) Frequency 5 6 2 1 1 Cum Frequency 5 11 13 14 15 (5) Wait Time 12.0 5.455 4.615 4.286 4.0 Cum Travel Time 100 226 270 294 320 (7) Average Travel Time 20 20.545 20.769 21 21.333 (8) Travel + Wait Times 32.0 26.0 25.385 25.286 25.333 (9) Include Line Y Y Y Y N
Notes: Lines 1-4 are included in the basic choice set because, with the addition of each line, the overall time to destination improves. Line 5 is excluded from the basic choice set because including it makes the time to destination worse. A wait factor of 2 was used to weight the waiting times. Column (5) = 60.0/(4) * 0.5 * Wait Factor Column (6) = (2)*(3), accumulated over lines Column (7) = (6)/(4) Column (8) = (7)+(5)
Results of the service frequency model

(3) (1) Line 1 2 3 4 5 (2) Line Frequency 5 6 2 1 1 Cum Frequency at Stop 5 11 13 14 (4) Proportion of Trips 0.357 0.429 0.143 0.0714 0.0
12
Notes: Column(4) = (2)/cumulative frequency at stop
Example of the service-frequency-and-cost model

This example shows: Choice set Results of the service frequency & cost model
Choice set
(4) Average travel time excluding this line (5) Excess travel time over average (6) Wait time without this line (7) Proportion of time when line used (8) Cum effective frequency (9) Wait time including this line (10) Average travel time including this line
(2) (1) Line Line frequency
(3) Travel time
1 2 3 4 5
5 6 2 1 1
20 21 22 24 26
20 20.52 20.707 20.798
1 1.48 3.293 5.202
12 5.714 5.007 4.868
1 0.917 0.742 0.342 0
5 10.500 11.983 12.326 -
12 5.714 5.007 4.868 -
20 20.52 20.707 20.798
Notes: Example uses a wait factor of 2 to weight the waiting times. Column (7) = 1-MIN( (5)/(6)),1) Column (8) = (2)*(7), accumulated over lines Column (9) = 60.0/(7) * 0.5 * Wait Factor Column (10) = ((2)*(3)*(7), accumulated over lines) / (8)
12
Results of the service frequency & cost model

(3) (2) (1) Line 1 2 3 4 5 Line frequency 5 6 2 1 1 Effective frequency at stop 5 5.500 1.483 0.343 (4) Cum frequency at stop 5 10.500 11.983 12.326 (5) Proportion of trips 0.406 0.446 0.120 0.028 -
Notes: Column(5) = (3)/cumulative frequency at stop
Skimming process
The skimming process extracts the cost of a public transport trip into a zone-to-zone matrix. Because the Public Transport program finds multiple routes between zone pairs, the program can provide several skims, suitable for different purposes: Composite-cost skim Supports scheme evaluation and demand modeling Value-of-choice skim Indicates the choice available in the public transport system Average skims Supports model validation, operational statistics, revenue calculation Best-trip skim Indicates actual trip cost
Available skims and the processes for extracting them are described in Skimming (level of service) on page 593 and Skimming Quick reference on page 604.
12
Composite-cost skim
For each zone pair, the composite-cost skim computes the composite cost, or the total utility of the trip including the choices available to the traveller. The route-evaluation process uses composite costs, also referred to as the expected cost to destination (see Deriving cost used on page 801 for a description of how they are derived). To enable you to model demand or evaluate schemes, the skim ensures that adding new routes or improving services does not lead to an increase in the cost. The skim calculates composite costs from each decision point in the trip to the destination. The calculation varies with the type of choice: Walk choices Transit choices Alternative alighting points Walk and transit choices
Value-of-choice skim
For each zone pair, the value-of-choice skim computes the value of choice, a measure of the extent to which travellers can choose between alternative routes. Higher values indicate travellers can choose between routes of similar costs, whereas lower values indicate a lack of route choice, or choices where the lesser alternatives are considerably more expensive than the best route. The value of choice provides a measure of the resilience or robustness of the public transport system. With more low-cost choices, the system can continue functioning following the failure of one or more components. The value-of-choice skim is equivalent to the difference between the composite-cost skim and the average-generalized-cost skim.
12
Average skims
Average skims compute the costs a typical traveller incurs while making a public transport trip. You can extract average skims for all components of the trip. There are three broad areas: Time Walk (nontransit) Wait In-vehicle Inconvenience Boarding Transfer Cost Fare Because multiple routes might connect zone pairs, average skims weighting each route according to its probability of use. Average skims compute component costs at network and route-set level. Within each route set, average skims can compute costs other than wait time by mode. Several average skims can compute either actual valuestrue measures of the costor perceived valuesthe costs contribution to generalized cost (usually a product of the cost and a weighting coefficient). Average skims are appropriate for model validation and skimming operational statistics, such as passenger miles, hours, and revenue.
Best-trip skim
For each zone pair, the best-trip skim computes the actual time for the best route (that is, the time if travellers make the best choice at every decision point).
12
Because the skim uses actual values for all trip components, the skim does not reflect traveller behavior, and is, therefore, inappropriate for demand modeling. The skim bases the wait time and the transit-leg time on the lowest expected values. The skim computes wait times from the appropriate wait curve, using the combined frequencies of all acceptable lines from the node towards the destination. The skim computes transit-leg times from the fastest line in the leg-bundles used.
NOTE: At present, walk (nontransit) legs have only one time
attribute, the one used to construct them (perceived time). See Walk time (nontransit time) on page 772.
Loading process
The loading process (assignment) allocates trips, either computed or from the input trip matrix, to services (transit lines) and nontransit legs. The loading process uses routing and travel time information obtained from the route-evaluation process. The loading process considers one origin-destination zone pair at a time. The process assigns the zone pairs trips to the available routes according to each routes probability of use, calculated during the route-evaluation process.
12
For example, consider the reports of enumerated and evaluated routes between zones 1 and 3.
Enumerated routes between zones 1 and 3
REnum Route(s) from Origin 1 to Destination 3 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 751 -> 751 lines PLB1-113B PLB129B PLB127A 751 -> 749 -> 3 lines GMB1-2B Cost=27.668 1 -> 773 773 -> 759 -> 759 lines GMB1-24MB 759 -> 875 -> 875 lines RES34R 875 -> 749 -> 3 lines GMB1-2B Cost=34.028 1 -> 2052 2052 -> 2004 -> 875 lines ISL-DN 875 -> 749 -> 3 lines GMB1-2B Cost=31.84
Evaluated routes between zones 1 and 3

REval Route(s) from Origin 1 to Destination 3 1 -> 773 773 -> 764 -> 764 lines GMB1-24MB 764 -> 751 -> 751 lines PLB1-113B PLB129B PLB127A 751 -> 749 -> 3 lines GMB1-2B Cost= 23.668 Probability=0.631438 1 -> 773 773 -> 759 -> 759 lines GMB1-24MB 759 -> 875 -> 875 lines RES34R 875 -> 749 -> 3 lines GMB1-2B Cost= 28.628 Probability=0.142594 1 -> 2052 2052 -> 2004 -> 875 lines ISL-DN 875 -> 749 -> 3 lines GMB1-2B Cost= 30.04 Probability=0.225968
The first report shows three bundles of enumerated routes from zone 1 to zone 3. All routes meet the evaluation criteria; none are eliminated. The second report lists the routes with their probability of use. The enumerated-routes report shows used costs. However,
12
the evaluated-routes report shows the average cost for the route bundle, not the composite costs used to calculate the probability of use. The loading process considers two walk choices from zone 1: to nodes 773 and 2052. The route-evaluation process determined that the probability of going to node 773 is 0.774032, while the probability of going to node 2052 is 0.225968, reflecting the shorter time via node 773. The loading process splits trips from zone 1 to zone 3 in this proportion and saves the trips for the nontransit (access) legs: At node 773, there is a single transit service, GMB1-24B; all trips arriving at node 773 board this service. There are two alighting points: nodes 764 and 759. The time via 764 is less than the time via 759. Thus the probability of using node 764 is 0.631438 and the probability of using node 759 is 0.142594. The loading process splits trips at node 773 between the two alighting points and saves the trips for the two transit legs. At 764, the loading process assigns arriving trips to lines PLB1-113B, PLB129B, and PLB127A in proportion to their relative frequencies for trips to node 751. From node 751, travelers go to zone 3 via node 749 and line GMB1-2B. The process saves the number of trips assigned to the four transit legs for each leg. At node 759, the loading process assigns arriving trips to transit lines RES34R and GMB1-2B for trips to nodes 875 and 749 before ending at zone 3. At node 2052, the loading process assigns travelers to transit line ISL-DN for the trip to node 875, and then to transit line GMB1-2B for the trip to node 749 before ending at zone 3.
All trips from zone 1 to 3 use line GMB1-2B as the last transit leg in the trip, and alight at node 749 where they walk to zone 3. These are saved for the nontransit (egress) leg 749-3.
12
The loading process is complete after assigning trips between all (selected) origin-destination zone pairs, and computing the total trips using transit and nontransit legs on the underlying network links.
Fares
This section describes how to model fares in the Public Transport program. Topics include: Overview Trip length Multiple fare systems Boarding and transfer costs Trip costs Fare zones Examples
Overview
Fares are a fundamental element of a public transport trip. Therefore, it is import to incorporate fares fully into the Public Transport modeling process. To incorporate fares, the Public Transport program: Considers fares in the route choice Skims average fares for each origin-destination zone pair Calculates and reports revenue
Fares do not always significantly impact route choice. To reduce run times, you might exclude fares from the route-evaluation process and skim and calculate revenue from the evaluated routes.
12
The Public Transport program must accurately represent the fare systems that passengers face. The Public Transport program provides a framework which you can use to directly represent or approximate most fare systems. In fact, you can represent different types of fare systems within a single public transport network. You can specify fare systems and value of time by user class. You might do this to use readily available ticket type data to segment and model demand by ticket type. Transit legs are the basic unit the program uses to calculate fares. A transit leg is one part of a trip, from a boarding point to an alighting point, that uses a single transport line. The program assigns each line to a fare system, either directly or through its mode or operator. The program calculates fare for a single leg of the trip. If multiple consecutive legs have the same fare system, the program assumes integrated or through ticketing and calculates fare for that sequence of legs. To model fares, the Public Transport program requires a programwide fare system that describes each transit lines individual fare system, its data requirements, and how it interfaces with other lines. You define fare systems with the FARESYSTEM control statement and input fare systems with the FILEI FAREI file. You define fare system attributes with FARESYSTEM keywords and subkeywords: Unique numeric and character identifiers (NUMBER, NAME, LONGNAME) Unit of measure for trip length, such as distance, number of fare zones crossed, or boarding-alighting fare zones. (STRUCTURE, with possible values: FLAT, DISTANCE, HILOW, COUNT, FROMTO, or ACCUMULATE) Boarding costs at the initial boarding and subsequent transfers, and the cost of transferring between fare systems (IBOARDFARE, FAREFROMFS)
12
Trip cost, which may be specified with a coefficient per unit measure of the trip, a table, or matrix (UNITFARE, FARETABLE, FAREMATRIX) Rules for computing costs when transferring to the same fare system and interpreting fare tables (SAME, INTERPOLATE)
Data requirements for fare systems depend upon the unit of trip measure (specified with STRUCTURE) and the method for specifying trip costs (specified with UNITFARE, FARETABLE, and FAREMATRIX). Requirements can vary from minimal to substantial. The following table provides a quick reference to the various fare systems and their data requirements.
STRUCTURE IBOARDFARE FAREFROMFS UNITFARE FARETABLE FAREMATRIX FAREZONE FLAT Required Optional NA NA NA NA DISTANCE Optional Optional Optional
1
HILOW Permissible Optional NA NA Required Required
COUNT Permissible Optional NA Required NA Required

3
FROMTO Permissible Optional NA NA Required Required
ACCUMULATE Permissible Optional NA Required NA Required
Optional2 NA NA
1,2 One of the two items is required. 3 Permitted but use is questionable, as it could be included in the FAREMATRIX.
The program assigns fare systems to transit lines indirectly through the lines mode and operator with the FACTORS FARESYSTEM keyword or directly with the LINE control statement. When modeling fares, each line must have an assigned fare system. Include fares in the route-evaluation process by setting
PARAMETERS FARE to T. Skim fares, whether or not they are
included in route-evaluation, by selecting skimming functions FAREA and FAREP in the SKIMIJ phase.
12
Trip length
The units for measuring trip-length is a key attribute of the fare system. Trip-length units might be based on legs, actual distance, or fare zones. Fare zones are single nodes or groups of nodes. You specify the trip-length unit with the FARESYSTEM keyword STRUCTURE. There are six possible values. Each value results in a different method for calculating trip length and fare.
Description of trip-length units
Value of STRUCTURE FLAT Method for calculating trip length and fare Trip length not used for fare calculation. Fares derived by leg using the boarding and transfer costs specified with IBOARDFARE and FAREFROMFS. DISTANCE Trip length measured as in-vehicle distance, in user-specified units. Fares calculated by leg or for sets of consecutive legs using the same fare system. Fares based on: Boarding and transfer costs, specified with IBOARDFARE and FAREFROMFS. Trip cost computed by multiplying in-vehicle distance by UNITFARE. Trip cost obtained from the fare table specified by FARETABLE. The value of INTERPOLATE determines whether the program uses linear interpolation or a step function between coded points.
HILOW
Trip length measured by the highest and lowest fare-zones crossed. Appropriate for an annular fare-zone structure. Fares calculated by leg or for sets of consecutive legs using the same fare system. Fares based on: Boarding and transfer costs, specified with IBOARDFARE and FAREFROMFS (boarding costs are added to the fare matrix) Trip cost, extracted from the fare matrix specified with FAREMATRIX (rows contain the lower fare zone, and columns contain the higher fare zone)
12
Description of trip-length units (continued)

Value of STRUCTURE COUNT Method for calculating trip length and fare Trip length measured by the number of fare zones crossed plus 1 for the initial zone. Best suited to a sequential zone system. Fares calculated by leg or for sets of consecutive legs using the same fare system. Fares based on: Boarding and transfer costs, specified with IBOARDFARE and FAREFROMFS Trip cost, extracted from the fare table specified with FARETABLE. In this case, the program interpolates the fare table as a step function.
FROMTO
Trip length measured as function of the boarding and alighting fare zones. Best suited to a sequential zone system. Fares calculated by leg or for sets of consecutive legs using the same fare system. Fares based on: Boarding and transfer costs, specified with IBOARDFARE and FAREFROMFS (boarding costs are added to the fare matrix). Trip cost, extracted from the fare matrix specified with FAREMATRIX (rows contain the lower fare zone, and columns contain the higher fare zone)
ACCUMULATE
Trip length measured by accumulating fares associated with each fare zone traversed. Differs from COUNT, where program counts the number of fare zones traversed to compute fare. Best suited to a sequential zone system. Fares calculated by leg or for sets of consecutive legs using the same fare system. Fares based on: Boarding and transfer costs, specified with IBOARDFARE and FAREFROMFS Trip cost, extracted from the fare table specified with FARETABLE. The fare table has a fare for each fare zone in the system.
12
Multiple fare systems

For public transport networks with multiple fare systems, use the SAME subkeyword to specify whether the program treats consecutive legs in the same fare system as one leg or as separate legs when calculating fares. If two consecutive legs of a trip use different fare systems, the program always calculates the fare separately for each leg.
Boarding and transfer costs

Boarding and transfer costs are key attributes of the fare system. You specify boarding and transfer costs with FARESYSTEM keywords:
IBOARDFARE Fare incurred upon boarding the first transit leg
of a trip. See IBOARDFARE on page 668.

FAREFROMFS Fare incurred when transferring from lines
using other defined fare systems. See FAREFROMFS on page 665.
Trip costs
Trip cost is a key attribute of the fare system. The program determines trip cost using one of three methods:
UNITFARE Coefficient used to calculate fares. Only available when STRUCTURE is DISTANCE. To obtain fare, the program multiplies UNITFARE by in-vehicle distance of a leg or a sequence of consecutive legs using the same fare system. FARETABLE Table of fares. Used when STRUCTURE is DISTANCE, COUNT, or ACCUMULATE. Define FARETABLE with a
list of paired X and Y coordinates, where X is the trip length and Y is the fare.
12
See FARETABLE on page 666 for more information about coding FARETABLE. Some graphic examples follow.
Fare table for STRUCTURE=DISTANCE and INTERPOLATE=T
Fare table for STRUCTURE=DISTANCE and INTERPOLATE=F
12
Fare table for fare-zone based fare systems
FAREMATRIX Matrix of fares. Used when STRUCTURE is
HILOW or FROMTO. Input matrices with FILEI FAREMATI in either standard Cube Voyager binary matrix format or as text records. See FAREMATRIX for information about coding fare matrices. To report on fare matrices, use the REPORT keyword FAREMATI. You code fares in monetary units. The program converts fares to generalized costs using the FACTORS keyword VALUEOFTIME.
Fare zones
Fare systems that have the STRUCTURE set to HILOW, FROMTO, COUNT, or ACCUMULATE require fare zones. Fare zones are either groups of nodes or single nodes. A public transport network might have multiple fare-zone schemes, but a fare system must have only one zone scheme. Therefore, a node can be in only one fare zone.
12
The HILOW structure requires an annular fare zone system while the other structures require sequential fare zones. To identify and code fare zones for fare systems with a FROMTO, COUNT, or ACCUMULATE structure
1. Display the network in Cube. 2. Add a new node attribute, FAREZONE. a.
From the Node menu, point to Attribute, and choose Add.
b. In the Add Note Network Variable dialog box, type FAREZONE and click OK. 3. Use the Polygon menu to define fare zones, one at a time 4. Assign a number to the FAREZONE attribute of the nodes
within the polygon
Example of a sequential fare zone system
To identify and code fare zones for fare systems with a HILOW structure
1. Display the network in Cube. 2. Add a new node attribute, FAREZONE.
12
a.
From the Node menu, point to Attribute, and choose Add.
b. In the Add Note Network Variable dialog box, type FAREZONE and click OK. 3. Associate the number of the outermost fare zone to the
FAREZONE attribute of all nodes.

4. Use the Polygon menu to define a ring separating the
outermost fare zone from the other zones.

5. Assign the number of the penultimate fare zone to the
FAREZONE attribute of the nodes within the polygon

6. Repeat the last two steps until all fare zones have been
completed.
Example of an annular zone system
12
Examples
This section shows how fares are calculated for a four-leg trip using different fare models, individually and in combination.
Boarding & alighting points A-B B-C C-D D-E In-vehicle distance (miles) 10 3 2 1
Leg 1 2 3 4
Mode 1=British Rail 2=Underground Piccadilly 2=Underground Bakerloo 3=Bus
Example 1: FLAT fare system

FARESYSTEM NUMBER=1, NAME=Flat Fare British Rail, STRUCTURE=FLAT, IBOARDFARE=100, FAREFROMFS[1]=0, 100 FARESYSTEM NUMBER=2, NAME=Flat Fare Underground+Bus, STRUCTURE=FLAT, IBOARDFARE=50, FAREFROMFS[1]=75, 0 FACTOR FARESYSTEM=1, MODE=1 FACTOR FARESYSTEM=2, MODE=2,3
FARE(A-E) = 175 pence, which is the sum of fares for each leg, calculated as:
Leg A-B Leg B-C 2} Leg C-D to 2} Leg D-E 2} = 100 {IBOARDFARE for A-B} + = 75 {FAREFROMFS[1] for B-C, for transferring from FARESYSTEM 1 to = = 0 {FAREFROMFS[2] for C-D, for transferring from FARESYSTEM 2 0 {FAREFROMFS[2] for D-E for transferring from FARESYSTEM 2 to
Example 2: DISTANCE fare system
The trip uses three fare models, all with STRUCTURE set to DISTANCE but with different unit cost for trip length.
FARESYSTEM NUMBER=1, NAME=Distance British Rail, STRUCTURE=DISTANCE, IBOARDFARE=100, FAREFROMFS[1]=0, 100, 100, FARETABLE=1.0,0.75, 5.0,2.50, 10.0,3.50 FARESYSTEM NUMBER=2, NAME=Distance Underground, STRUCTURE=DISTANCE, SAME=CUMULATIVE, IBOARDFARE=100, FAREFROMFS[1]=100, 0, 100, UNITFARE=60 FARESYSTEM NUMBER=3, NAME=Distance Bus, STRUCTURE=DISTANCE, IBOARDFARE=50, FAREFROMFS[1]=50, 50, 0, UNITFARE=50
12
FACTOR FARESYSTEM=1, MODE=1 FACTOR FARESYSTEM=2, MODE=2 FACTOR FARESYSTEM=3, MODE=3
FARE(A-E) = 950 pence, which is the sum of fares for trip legs, calculated as:
Leg A-B = 100 + 350 (IBOARDFARE + trip cost) Legs B-D = 100 + (5*60) (FAREFROMFS[1] + total distance * UNITFARE) Leg D-E = 50 + (1*50) (FAREFROMFS[2] + total distance * UNITFARE)
NOTE: Where two consecutive legs have the same fare system, the
fare can be calculated for each leg separately or cumulatively, depending upon the setting of SAME. In this example, legs B-C and C-D have the same fare system and SAME is set to CUMULATIVE, so the fare is calculated for B-D. SAME has no effect in this case because UNITFARE is used rather than FARETABLE. There is no cost for transferring from fare type 2 to another leg using the same fare type.
Example 3: FROMTO fare system
FARESYSTEM NUMBER=1, NAME=Trip Based, STRUCTURE=FROMTO, FAREMATRIX=MI.1.5, FAREZONES=NI.FAREZONE FACTOR FARESYSTEM=1, MODE=1-3
FARE(A-E) = 350 pence, The node variable, NI.FAREZONE, defines the fare zones for stops A through E, and the program extracts the fare from fare matrix number 5, input on FAREMATI[1], row NI.FAREZONE(A) and column NI.FAREZONE(E). There are no boarding costs or costs for transferring between the same fare system.
Example 4: COMBINATION of FROMTO and DISTANCE fare systems
The two FROMTO fare systems use different FARETABLE values and an incentive is offered to interchange between fare system 1 and 2 and vice versa.
12
FARESYSTEM NUMBER=1, NAME=British Rail, STRUCTURE=FROMTO, FAREMATRIX=FMI.2.BritRail, FAREFROMFS[1]=0, -25, 0, FAREZONES=NI.FAREZONE FARESYSTEM NUMBER=2, NAME=Underground, STRUCTURE=FROMTO, SAME=CUMULATIVE, FAREMATRIX=FMI.1.UndGrnd, FAREFROMFS[1]=-25, 0, 0, FAREZONES=NI.FAREZONE FARESYSTEM NUMBER=3, NAME=Bus, STRUCTURE=DISTANCE, UNITFARE=50, IBOARDFARE=50, FAREFROMFS[1]=50, 50, 0
FARE (A-E) = 525 pence, which is the sum of fares for legs, calculated as:
Leg A-B = 250 (FAREMATRIX FMI.2.BritRail, row NI.FAREZONE(A), column NI.FAREZONE(B)) Leg B-D = -25+200 (FAREFROMFS[1] and FAREMATRIX FMI.1.UndGrnd, row NI.FAREZONE(B), column NI.FAREZONE(D)) Leg D-E = 50 + 1*50 (FAREFROMFS[2] + trip cost)
Crowding
An iterative process, crowd modeling enables a public transport systems capacity to influence the systems travel times and thus the routes found and their probability of use, as calculated during route evaluation. The Public Transport program supports two types of crowd models: Link-travel-time adjustment Wait-time adjustment
This section also discusses: Crowding process
Link-travel-time adjustment
A link-travel-time adjustment models a passengers perception that travel time is more onerous when standing (rather than sitting), or when in crowded vehicles. Specify this adjustment with a crowding factor. The program multiplies the crowding factor by in-vehicle time to determine the perceived crowded in-vehicle time.
12
For example, suppose a vehicle has a seating capacity of 40, crush capacity of 50, and load distribution factor of 0.85 (standing occurs when more than 85% of 40that is, 34 seatsare occupied). Once standing starts, the crowding factor might increase slowly from 1.0 for the first few standing passengers, then more steeply once vehicle loading exceeds 40.
Example of crowding factor values (as a function of vehicle load)
12
The Public Transport program uses crowding curves. Derived from the crowd-factor curve, crowding curves show utilization on the X-axis. Utilization, the percentage of standing places occupied, can vary between 0 and 100. The corresponding crowding curve is shown below.
Crowding curve definition, as a function of utilization
Crowd factors are 1.0 in uncrowded conditions, and typically rise to values in the ranges 1.0 to 1.4 for seated passengers and 1.5 to 3.0 for standing passengers when the vehicle is fully loaded with standing occurring. The program calculates crowded link travel time as:
T c = T u CCrv v, c ( U )
where: Tc Tu is the crowded link travel time is the link travel time (in uncrowded conditions)
CCrvv,c (U) is the crowd curve value (where the curve is specific to a vehicle type, v, and a user class, c) for utilization U U is the utilization measure (as a percentage)
12
The utilization measure, U, is defined by the expression:

P ( LDF v SeatCap ) U = -----------------------------------------------------------------------CrushCap ( LDF v SeatCap )
where: P SeatCap is the passenger demand (per hour). is the seating capacity (per hour) for the line.
CrushCap is the crush capacity (per hour) for the line; this is the total of seated and standing capacities. LDFv is the load distribution factor for the vehicle type. As loads increase this is the proportion of seats occupied when standing starts to occur. It may be less than 1.0, indicating that standing occurs before all seats are used. (Note: the LDF value specified in commands is coded as the corresponding percentage.)
The value of utilization is constrained with a minimum value of 0% (when no standing occurs) and an upper limit of 100% (when crush capacity is exceeded). If the values of seating capacity and crush capacity are identical for any line, then utilization is 100% whenever demand exceeds the seating capacity, and 0% otherwise.
Wait-time adjustment
The wait-time adjustment reflects the ability to board a service. In simple models (without crowd modeling) travellers typically board the first service that arrives at a stop and goes to the required alighting point. As loadings on services increase, this becomes less realistic, as travellers will choose the first appropriate service that has available capacity. Using measures of demand and available capacity, the wait-time adjustment computes the probability of being able to board a service. With heavily loaded services, some travellers will wait for the next service, incurring additional wait time at the boarding node.
12
Without crowding, the program assigns demand with the servicefrequency model (SFM), or service-frequency-and-cost model (SFCM). The wait-time adjustment redistributes the initial SFM or SFCM loadings whenever any line does not have the available capacity to take its assigned demand. The program reassigns this excess demand to other lines with spare unused capacity; those travellers incur additional wait time. The additional wait time might make this route less attractive, resulting in diversion of demand to other enumerated routes for the origin-destination pair. If demand exceeds capacity and no alternative routes are available, then this transit leg acts as a bottlenecknot all of the travel demand is able to use the service during the modeled period. The demand remaining at the end of the modeled period would discharge once peak travel volumes subside; those travelers experience additional delays, which form a second component to the wait-time adjustment. Flow metering handles the bottleneck effect and the inability of demand to pass through that point. Flow metering removes the excess demand from later stages in the trip; thus demand at any downstream point reflects the number of travellers who can reach that point. For any origin-destination pair, the program can calculate the proportion of flow-metered demand (that is, demand unable to reach its destination due to network bottlenecks), and the number of trips affected.
Crowding process
The crowd modeling process uses the loaded demand from an iteration to provide updated values for: Link travel times (which may vary by user class) Probability of being able to board a line at a particular stop
These calculations incorporate a degree of damping to help stabilize the resulting assignments.
12
The crowding process is viewed as a stochastic assignment, and results are obtained from the final iteration. Crowded networks might cause instabilities in the loadings between iterations, as demand switches toward less congested routes. In turn, those routes might become more heavily loaded, and thus less attractive at the next iteration. These changes might converge toward a solution, or might continue oscillating; oscillation is more likely in highly overloaded networks. The service-frequency-and-cost model usually results in better convergence than the service-frequency model because the routechoice process is more responsive to changes in costs.
12
Public Transport Program Using the Public Transport program
Using the Public Transport program

This section discusses useful information for using the Public Transport program. Topics include: Estimating demand matrices Defining input and output files Linking Highway and Public Transport models Coding network times/speeds Generating nontransit access and egress legs Considering nontransit-only routes
Estimating demand matrices

You can use Cube Analyst to estimate public transport demand matrices. Cube Analyst uses screenline count data to update a prior matrix. Confidence levels determine how much each input influences the estimation process. See Cube Analyst Reference Guide for detailed information about the methods used. Matrix estimation requires an intercept file, which provides data on routes crossing the defined screenlines for each origin-destination pair. A run of the Public Transport program produces the intercept file. Screenline data files specify the links that compose each screenline and contain associated data, such as link counts and confidence levels. Confidence levels reflect the accuracy of count data and affect the weighting during the estimation process. You can create a screenline file with: Cube, or text-file editors, and read the file in to the Public Transport run Public Transport run, based on data values stored in the input network
12
Link variables in the input network contain the screenline number (zero if the link is not part of a screenline), link count, and confidence level. For a Public Transport run to produce matrix estimation data, the script must specify a FILEO INTERCEPTO command, along with either a FILEI SCREENLINEI or a FILEO SCREENLINEO command. Alternatively, the software may save just a screenline output file without performing any route evaluation. To configure the intercept file to contain only transit use of the links, or all demand (that is, transit plus nontransit use of all links), use the MEUSESNT keyword on PARAMETERS and FILEO SCREENLINEO commands.
Defining input and output files

You define input and output files for the Public Transport program with control statements FILEI and FILEO. These are present in the main script file. Use control statements to define input and output data items (that is, LINE, MODE, OPERATOR, and NTLEGS). These are usually contained in files defined by FILEI and FILEO, and not in the script file. All control statements available in the Public Transport program are described in Control statements on page 632. This section shows which files contain which data items.
FILEI/O keyword FAREI LINEI NTLEGI SYSTEMI LINEO NTLEGO File description Fare system Lines Nontransit leg Public transport system Lines Nontransit leg Valid control statements defining data FARESYSTEM LINE NT MODE, OPERATOR, VEHICLETYPE, WAITCRVDEF, and CROWDCRVDEF LINE NT
12
Linking Highway and Public Transport models

In studies that model both highway and transit demand, you can link the two models. Transit vehicles travel through junctions and take some of the junction capacity. For networks with congestion, a typical highway model estimates delays on links and at junctions. Link travel times include link delays, and trip time also includes junction delays. Junction delays can affect transit vehicles, though provisions like bus-only lanes can reduce or eliminate such delays at particular locations. Cube Voyager can export junction delay data from Highway program runs, and include these delays in the run times of transit lines. However, because Highway assignment does not support turn-based preloads, Cube Voyager cannot import transit-vehicle turn volumes from Public Transport to Highway. The Highway program can export delays for turning movements to a TURNPENO file. The Public Transport program can then read this file. The Public Transport program calculates a lines travel times using TRANTIME (a global parameter that represents link travel times), junction delays, link delay, and dwell time values. TRANTIME and junction delays are network components, and delay and dwell time are line components. When junction delays are included, transit-line run times are influenced by the highway networks congestion levels. To model bus-only lanes or other provisions designed to reduce transit-line delay at junctions, you can limit the delay at a junction by defining a link variable that specifies an upper limit for delay on the approach link to a junction.
LINE definitions can include RUNTIME, RT, or NNTIME keywords, which provide control values. The program scales the lines travel times up or down to match these control values. You might use control values in base-year models to ensure that the lines travel time matches an expected value.
12
For forecast years, when you do not know the lines travel time, you cannot code the time as part of the line. Instead, the program determines travel times with an incremental approach. The program calculates the lines travel times for the base year, and compares these times to the control values to generate scaling factors for the increase or decrease in travel times. The program applies these factors and the forecast-year junction delays to compute the lines travel times in the forecast year. Because the program does not scale these travel times to control totals, any changes reflect increases and decreases in junction delay along the route. The program applies scaling to link travel times and delay values; the program does not scale dwell times and junction delays. The method uses two sets of TURNPENI data, each with its own MAXDELAY variable (to reflect possibly different bus-lane provisions each year). Typically, modeled stops are close to a junction node. Therefore, the program adds the entire junction delay to the travel time of the link approaching the modeled junction. You might model turning delays at a transit lines last node. The program accounts for such delays as occurring before the line reaches its final stop, even though the vehicle does not pass through the node. The program adds that nodes lowest turning delay to the travel time along the final link. You should configure the model to read the TURNPENI file at the same time as the LINEI files. When reading LINE data from a network file, the program has already calculated link travel times and cannot amend turn penalties.
Coding network times/speeds

The Public Transport program requires a network that provides the basic infrastructure over which public transport services operate zones, nodes/stops, links. This network can contain any node and link attributes you choose. Possible sources of the network include: Network program, produced specifically for modelling a public transport system
12
Existing highway network produced by the Network or Highway programs Public Transport program, in which case only the network information is used (the public transport element is discarded)
The network must provide basic link attributes that support the Public Transport programs modelling functions: link distance, and walk and transit times or speeds. Link distance is required (specified by LI.DISTANCE or another variable from which distance can be derived). The program uses link distance to calculate link times when you provide only speeds, to skim distance from routes, and to calculate fares for distancebased fare models. Subsequent sections in this topic offer guidance on how to code transit and nontransit times and/or speeds in the network: Transit times/speeds Nontransit times/speeds
Transit times/speeds
The Public Transport program requires a base transit time for links that public transit lines traverse. This is supplied to the program with PARAMETERS TRANTIME. (You can factor each lines base linktime in a variety of way, as described in LINE on page 720.) You can use different techniques to specify a links transit time. Possible techniques include: Set a links transit time to the congested time resulting from a highway assignment: TRANTIME = LI.TIME_CONGESTED (assuming the links contain a variable named TIME_CONGESTED). Create a network variable that stores transit speeds with the Network program.
12
(If the highway network stores public transport links, you can exclude those links from highway assignments by setting those links path value to a negative value and their capacity to 0.) Set array(s) of working link values in the LINKREAD phase and use those arrays in the TRANTIME expression. For example:
PHASE=LINKREAD if (link condition) LW.TTIME = LI.DISTANCE*60/LI.SPEED * 1.2 else LW.TTIME = LI.DISTANCE *60 / LI.SPEED endif ENDPHASE PARAMETERS TRANTIME=LW.TTIME
TRIPS users only. Input the TRIPS link records directly to the Network program to create a Cube Voyager network. The Network or Public Transport programs can derive transit and nontransit link times from the link records link-type field and the LTYP data in the lines file. See Example 2: Preparing a public transport network from TRIPS link data on page 851.
Nontransit times/speeds
You can develop nontransit legs outside the Public Transport program, inside the Public Transport program, or some combination. Regardless of the process, you must use GENERATE statements within the DATAPREP phase to develop a nontransit network. When developing the nontransit network outside the Public Transport program, you must ensure that you use costsperceived or actualconsistent with the cost components that the routeenumeration and route-evaluation processes use. Keywords in the GENERATE statement set the method for obtaining nontransit legs. However, you might need to precede the GENERATE statement with a script that manipulates link attributes. As in the LINKREAD phase, you can loop through all the links in the network and set desired link values.
12
Example:
PHASE=DATAPREP LINKLOOP if(link condition) LW.NTCOST = LI.DISTANCE * 1.6 else LW.NTCOST = LI.TIME*3.8 endif ENDLINKLOOP GENERATE COST=LW.NTCOST * 2.5, EXCLUDE=(LW.NTCOST > 100) ENDPHASE
Generating nontransit access and egress legs

The GENERATE statement is a powerful and flexible tool that generates the components of the nontransit networkaccess, egress, and transfer legs. However, misuse can generate unnecessary legs, resulting in poor quality routing.
Example 1: Drive-walk nontransit legs
Consider the routes from zone 1 to zone 11 in the network shown. Travellers access the transit system through nontransit legs generated with two GENERATE statements, for modes 1 (walk) and 2 (drive).
NT LEG=1-3967 MODE=2 COST=2.03 DIST=2.03 ONEWAY=T XN=4227 4006 4007 3963 3965 3966 NT LEG=1-4000 MODE=2 COST=1.66 DIST=1.66 ONEWAY=T XN=4005 4004 15646 4003 15647 3961 NT LEG=1-4143 MODE=2 COST=3.20 DIST=3.20 ONEWAY=T XN=4226 4267 4266 4265 4302 4303 4301 4144 4773 NT LEG=1-4227 MODE=1 COST=12.96 DIST=0.27 ONEWAY=T NT LEG=1-4263 MODE=2 COST=3.87 DIST=3.87 ONEWAY=T XN=4005 4004 15646 4003 15647 3961 4000 3999 3998 3997 9420 9419 3996 9423 3993 3992 9810 3991 NT LEG=1-4276 MODE=2 COST=2.66 DIST=2.66 ONEWAY=T XN=4268 4269 4270 4271 15687 8710 8709 4273 4274 NT LEG=1-4309 MODE=2 COST=2.12 DIST=2.12 ONEWAY=T XN=4268 4269 4307 4306 4308 NT LEG=1-4322 MODE=2 COST=3.39 DIST=3.39 ONEWAY=T XN=4268 4269 4270 4271 15687 8710 8709 4273 4315 4314 4316 4319
12
NT LEG=1-4386 MODE=2 COST=3.40 DIST=3.40 ONEWAY=T XN=4268 4269 4307 4306 4308 4309 4774 4349 4775
Travellers egress from the public transport system to zone 11 with the nontransit legs reproduced below, generated by a GENERATE statement.
NT LEG=4276-11 MODE=1 COST=3.36 DIST=0.07 ONEWAY=T NT LEG=4278-11 MODE=1 COST=14.40 DIST=0.30 ONEWAY=T XN=4276
The routing algorithms only recognize routes that have an access leg followed by pairs of transit and nontransit legs, the last being the egress leg. Although a nontransit-only route, 1->4276->11 exists, the algorithm will not enumerate that route. The all-or-nothing process, which marks base times for the routeenumeration spread, finds that 1->4276 is the best access leg to the public transport system for zone 11. Because travellers cannot cannot walk directly to 11 from 4276, they ride a transit line to 4278 and walk to 11 from there. (Where transit alternatives are either not available or not feasible, the process will find no routes between the two zones.)
12
Because the program found a route, even a nonsensical one, the program finds base times at nodes and enumerates and evaluates routes.
REval Route(s) from Origin 1 to Destination 11 1 -> 4322 4322 -> 4280 -> 4280 lines AM4L5 AM4L6- AM4L18 4280 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 30.8287 Probability=0.2803 1 -> 4322 4322 -> 4325 -> 4325 lines AM4L5 AM4L6- AM4L18 4325 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 30.83 Probability=0.2803 1 -> 4276 4276 -> 4278 -> 11 lines AM4L12- AM4L89 Cost= 31.42 Probability=0.0071 1 -> 4276 4276 -> 4280 -> 4280 lines AM4L12- AM4L89 4280 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 34.98 Probability=0.0959 1 -> 4322 4322 -> 4276 -> 11 lines AM4L12 AM4L89Cost= 19.62 Probability=0.3364
The fourth route in the list accesses and egresses the transit system at node 4276 and takes a transit line in between, raising questions about the quality of the evaluated routes. Rather than being an algorithmic problem, this arises due to the quality of the input data. In this case, if you allow drive access from zone 1 to 4276, then you should consider generating a drive-walk nontransit-only route between zones 1 and 11. Otherwise, remove the drive accesses and connect zone 1 to the transit system only with walk legs. Removing routes that access and egress the transit system at the same node would alleviate just one symptom rather than the underlying cause. A good nontransit network is essential for identifying good quality routes. You develop a nontransit network through an iterative process, validating and refining the network produced by the GENERATE statements over a few cycles.
12
Some useful GENERATE keywords to control the excessive generation of nontransit legs are:
SLACK MAXNTLEGS DIRECTLINK
Considering nontransit-only routes

A route in the Public Transport program consists of an access leg, and one or more pairs of transit leg bundles and nontransit legs, the last of which is the egress leg. Thus, nontransit-only routes never get enumerated, and zones may appear unconnected when they are not. Even when nontransit-only routes are not of interest, they have to be dealt with. Nontransit-only routes might be much faster than expected transit routes. If the cost difference between the two is outside the range of the route-enumeration SPREAD, the program will not enumerate the transit routes either. Thus the program will not connect zones by transit, for no apparent reason.
12
Example 1: Drive-only route
This diagram shows two walk (MODE=11) access legs and one drive (MODE=12) access leg that two GENERATE statements generate. No drive-drive routes are generated.
NT LEG=81-1092 MODE=11 COST=19.20 DIST=0.40 ONEWAY=T XN=1094 NT LEG=81-1104 MODE=11 COST=7.68 DIST=0.16 ONEWAY=T NT LEG=81-1109 MODE=12 COST=1.41 DIST=0.47 ONEWAY=T VOL=430 VOLT=430 XN=1104
The transit time from 1109 to 1092 is just under a minute. Therefore, the all-or-nothing process determines that the best stop to access line MAIN is 1109. The program generates several nontransit legs at 1109, including a drive egress:
NT LEG=1109-99 MODE=12 COST=1.53 DIST=0.65 ONEWAY=T XN=1108 1105
12
The best-cost route from 81->99 is to drive from 81 to 1109 and then to 99. However, because this is a nontransit-only route neither the all-or-nothing process nor the enumeration process will enumerate the route. Further, because the route is so much faster than any of the possible transit routes, the program will not enumerate the transit routes either, unless you define a very large route-enumeration SPREAD, which will result in an unnecessarily large route set for those zone pairs that genuinely connect with transit routes (most zone pairs in any study). Therefore, zones 81 and 99 will appear unconnected. If you are not interested in nontransit-only routes, skims, and loads, you can leave such zone pairs unconnected. However, when validating a network, you might establish why zone pairs do not connect. If, however, nontransit-only routes are required, then drive-only connections between zones should be generated:
GENERATE, COST=(li.DIST * 60) /li.OFFPSPD, MAXCOST[1]=5, NTLEGMODE = 14, FROMNODE=81, TONODE=99
This statement generates short drive-only routes between zones that cost 5 units or less.
NT LEG=81-99 MODE=14 COST=2.19 DIST=0.88 ONEWAY=T VOL=10 VOLT=10 XN=1094 1093 1092 1091 1090 1107
This route traverses links other than 81->1109 and 1109->99 and costs even less, making any transit-based routes even less competitive. However, because the NT statement identifies the drive-only route, the route-enumeration and route-evaluation processes enumerate that route:
REnum Route(s) from Origin 81 to Destination 99 81 -> 99 Cost=2.19 REval Route(s) from Origin 81 to Destination 99 81 -> 99 Cost= 2.19 Probability=1.0000
12
In this example, the transit routes are much slower than the driveonly one, and are only enumerated when SPREADFACT is 1.5. Although the program enumerates transit routes, the program only uses the drive-only route. The route-evaluation process discards the other routes because they cannot compete with the drive-only route.
REnum Route(s) from Origin 81 to Destination 99 81 -> 1109 1109 -> 569 -> 569 lines SMAIN 569 -> 1107 -> 99 lines SMAIN SMAIN Cost=58.95 81 -> 1109 1109 -> 1107 -> 99 lines SMAIN Cost=59.61 81 -> 99 Cost=2.19 REval Route(s) from Origin 81 to Destination 99 81 -> 99 Cost= 2.19 Probability=1.0000
You must carefully consider how to model short, fast nontransitonly routes when there are transit alternatives. Undetected, nontransit-only routes can result in poor quality routing as described in Generating nontransit access and egress legs on page 842.
Public Transport Program Examples
12
Examples
This section contains examples showing different ways to run the Public Transport program. Examples cover: Public transport network development Public transport skimming Public transport loading Public transport user classes
Public transport network development

This section contains two examples that show public transport network development: Example 1: Preparing a public transport network Example 2: Preparing a public transport network from TRIPS link data
Example 1: Preparing a public transport network

This example prepares a public transport network from: Network program-produced network, providing the basic infrastructure of zones, nodes and links (input with NETI) Line data (input with LINEI[1]) Public Transport system data (input with SYSTEMI) Factor data for route-enumeration and route-evaluation processes (input with FACTORI)
GENERATE statements that generate the nontransit network.
Parameter TRANTIME provides the location of transit time in the link record. The script explicitly codes the DATAPREP phase. You can only code
GENERATE statements in this phase.
12
This script produces a public transport network, containing validated input and the described generated components. You can save this network and for subsequent use by the Public Transport program for route enumeration, route evaluation, skimming, loading, and loading analyses. You can also display the network in Cube.
;Prepare a Public Transport Network RUN PGM = PUBLIC TRANSPORT ;Output files FILEO REPORTO = LDPRN00A.PRN FILEO NETO = LDNET00B.NET ;Input Files FILEI SYSTEMI = PTSYSTEM.PTS FILEI FACTORI[1] =FACTORLD.FAC FILEI LINEI[1] = ISL_PTLINES.LIN FILEI NETI = LDHWN00A.NET ;Globals PARAMETERS TRANTIME = li.TrnsTime PHASE=DATAPREP ;generate access/egress links list='\nGenerate Zone Access/Egress Legs' GENERATE, COST=li.WalkTime, MAXCOST[1]=16*20, LIST=T, NTLEGMODE=33, INCLUDELINK = li.WalkTime>0 ;generate xfer non-transit legs list='\nGenerate Transfer Legs' GENERATE, COST=li.WalkTime, MAXCOST[1]=16*15, LIST=T, NTLEGMODE = 34, ONEWAY=F, INCLUDELINK = li.WalkTime>0, FROMNODE=26-4000, TONODE=26-4000 ENDPHASE ENDRUN
12
Example 2: Preparing a public transport network from TRIPS link data

This example prepares a public transport network from TRIPSformatted link data. You can input the TRIPS network directly into the Network program to prepare the base network. The script uses three phases: NODEREAD reports the number, and X- and Y-coordinates of all nodes in the input network. LINKREAD calculates walk and transit times for all links in the network. TRIPS networks have links, identified by link type, that are walk only, transit only, or both walk and transit. The LINKREAD phase produces walk and transit time fields for each link. For links where only one activity can take place, the other field contains a zero. DATAPREP produces some diagnostics and generates access, egress, and transfer links. The generation process only includes links with a walk link-time greater than zero.
;Prepare a Public Transport Network from TRIPS data RUN PGM = PUBLIC TRANSPORT ;Output files FILEO NETO =LDNET00B.NET FILEO NTLEGO = LDNTL00A.NTL FILEO REPORTO =LDPRN00A.PRN ;Input files FILEI LINEI[1] = \ISL_PTLINES.LIN FILEI NETI = LDHWN00A.NET FILEI FACTORI[1] = FACTORLD.FAC, LIST=T FILEI SYSTEMI = PTSYSTEM.PTS ;GLOBALS PARAMETERS TRANTIME = li.TrnsTime ;NODEREAD phase loops over nodes. Can access network node variables N.xxx, ;and generate node variables Nw.xxx. PHASE=NODEREAD print list=ni.n, ni.x, ni.y ENDPHASE
12
;LINKREAD phase loops over links. Can access network link variables L.xxx and ;generate link variables Lw.xxx. PHASE=LINKREAD ;this phase is used to generate walk and transit times for ;the links of a TRIPS Public Transport network ;convert TRIPS distance and speed/time fields from 100dths to units lw.RDIST=li.DISTANCE/100. lw.RSPDTIME=li.SPDTIME/100. ;links with LT codes 10, 28,29,31,32 are walk only lw.WalkTimePT = 0 if(li.LType == 10,28,29,31,32 && li.STFLAG == 'S') lw.WalkTimePT = 60.* lw.RDIST/lw.RSPDTIME elseif(li.ltype == 10,28,29,30,31,32 && li.STFLAG == 'T') lw.WalkTimePT=lw.RSPDTIME elseif(li.LType == 18) lw.WalkTimePT = 60.* lw.RDIST/4. endif if(li.LType == 10,18,28,29,31,32) lw.TrnsTime = 0.0 else lw.TrnsTime = lw.RSPDTIME endif if(lw.TrnsTime != 0.0 && li.STFLAG == 'S') lw.TrnsTime =(60.* lw.RDIST/lw.RSPDTIME) endif list =li.A(9),li.B(9), li.DISTANCE(8.2), lw.RDIST(8.2) li.WalkTime(8.2), lw.WalkTimePT(8.2), li.TrnsTime(8.2), lw.TrnsTime(8.2), li.LType(3), li.STFLAG ENDPHASE ;DATAPREP is the non-transit leg generation/input phase. ;Network and line variables can be ;accessed and manipulated and non-transit legs are generated. PHASE=DATAPREP ;Count & report number of transit only, walk only and both walk and ;transit links. If no walk or transit links, or links with invalid ;time, the run is aborted with a suitable message ;(This demonstrates the use of the command LINKLOOP which loops over links) WalkLnkCnt = 0 TrnsLnkCnt = 0
12
BothLnkCnt = 0 ErrLnkCnt = 0 LINKLOOP if(lw.WalkTimePT > 0.0 && lw.TrnsTime == 0.0) WalkLnkCnt = WalkLnkCnt+1 elseif(lw.WalkTimePT == 0.0 && lw.TrnsTime > 0.0) TrnsLnkCnt = TrnsLnkCnt+1 elseif(lw.WalkTimePT > 0.0 && lw.TrnsTime > 0.0) BothLnkCnt = BothLnkCnt+1 else ErrLnkCnt = ErrLnkCnt+1 PRINT LIST = li.a, li.b, lw.WalkTimePT, lw.TrnsTime endif ENDLINKLOOP PRINT LIST = '\nNumber of walk only links = ', WalkLnkCnt, '\nNumber of transit only links = ', TrnsLnkCnt, '\nNumber of walk and transit links = ', BothLnkCnt, '\n' ;Note if and 'if' statement does not fit on one line and closing 'endif' ;is required if(WalkLnkCnt==0 && BothLnkCnt==0)abort msg = No Walk links in the Network if(TrnsLnkCnt==0 && BothLnkCnt==0)abort msg = No Transit links in the Network if(ErrLnkCnt> 0)abort msg = Links with invalid time/speeds in Network ;Generate access/egress links list='\nGenerate Zone Access/Egress Legs ' GENERATE, COST=lw.WalkTimePT, MAXCOST[1]=16*20, LIST=T, NTLEGMODE = 33, INCLUDELINK = lw.WalkTimePT>0 ;Generate xfer non-transit legs list='\nGenerate Transfer Legs ' GENERATE, COST=lw.WalkTimePT, MAXCOST[1]=16*15, LIST=T, NTLEGMODE = 34, ONEWAY=F, INCLUDELINK = lw.WalkTimePT>0, FROMNODE=26-4000, TONODE=26-4000 ENDPHASE ENDRUN
12
Public transport skimming

This example extracts skim or level-of-service matrices, reports them, and saves them to the file indicated by MATO[1]. A previously prepared public transport network is input with NETI. You must enumerate and evaluate routes before extracting skims. The ROUTEO file indicates that the script will enumerate routes. (Alternatively, you could input routes prepared in an earlier run with ROUTEI.) The SKIMIJ phase selects skimming, which the script must explicitly code. Skim functions select the skims for extraction. (Skimming automatically invokes the route-evaluation process.) The optional MATO phases reports skims.
;Skim Route Attributes from a previously prepared Public Transport network RUN PGM=PUBLIC TRANSPORT ;Output files FILEO REPORTO = LDPRN00A.PRN FILEO MATO[1] = LDMAT00E.MAT, MO=2-9,11-23, NAME = Compcost, ValOfChoice, IWAITA, XWAITA, IWAITP, XWAITP, TIMEAAM, TIMEATM, TIMEPAM, TIMEPTM, TIMEPNTM, BRDPENAM, BRDPENTM, XFERPENAM, XFERPENTM, DISTAM, DISTTM, DISTNTM, BRDINGSAM, BRDINGSTM, BESTJRNY, DEC=22*2 FILEO ROUTEO[1] = LDRTE00B.RTE ;Input files FILEI NETI = LDNET00B.NET ;SKIMIJ loops over IJ pairs. Skim are saved in working matrices. ;Routes are enumerated, evaluated and skimmed before this phase. PHASE=SKIMIJ MW[2]=COMPCOST(0) ;composite cost MW[3]=ValOfChoice(0) ;value of choice MW[4]=IWAITA(0) MW[5]=XWAITA(0) MW[6]=IWAITP(0) MW[7]=XWAITP(0) MW[8]=TIMEA(0,ALLMODES) ;initial wait time, actual, avg ;transfer wait time, actual, avg ;initial wait time, perceived, avg ;transfer wait time, perceived, avg ;time for all modes, actual
12
MW[9]=TIMEA(0,1,7,8,11) actual, avg MW[11]=TIMEP(0,ALLMODES) MW[12]= TIMEP(0,TMODES) perceived, MW[13]= TIMEP(0,33,-35)
;in-vehicle time for transit modes, ;time for all modes, perceived, avg ;in-vehicle time for transit modes, ;avg ;walk/ride time for non-transit modes, ;perceived, avg ;boarding penalty for all modes, avg ;boarding penalty for transit modes, ;transfer penalty for all modes, ;transfer penalty for transit modes, ;avg
MW[14]= BRDPEN(0,ALLMODES) MW[15]= BRDPEN(0,TMODES) avg MW[16]= XFERPENA(0, ALLMODES) actual, avg MW[17]= XFERPENP(0, 1,7,-8,11) perceived,
MW[18]= DIST(0,ALLMODES) MW[19]= DIST(0,TMODES) modes, avg MW[20]= DIST(0,NTMODES) modes, avg MW[21]= BRDINGS(0,ALLMODES) avg MW[22]= BRDINGS(0,TMODES) modes, same as
;distance for all modes, avg ;in-vehicle distance for transit ;walk/ride distance for non-transit
;number of boardings for all modes, ;number of boardings for transit ;above, avg
MW[23]=BESTJRNY ENDPHASE
;best travel time
;MATO loops over J for each I. All skims extracted above are reported PHASE=MATO if(ROWSUM(2) if(ROWSUM(3) FORM=10.2 if(ROWSUM(4) if(ROWSUM(5) if(ROWSUM(6) if(ROWSUM(7) > 0) PRINTROW mw=2 TITLE='Compcost', BASE1=T, FORM=10.2 > 0) PRINTROW mw=3 TITLE='ValOfChoice', BASE1=T,
> > > >
0) 0) 0) 0)
PRINTROW PRINTROW PRINTROW PRINTROW
mw=4 mw=5 mw=6 mw=7
TITLE='IWAITA', TITLE='XWAITA', TITLE='IWAITP', TITLE='XWAITP',
BASE1=T, BASE1=T, BASE1=T, BASE1=T,
FORM=10.2 FORM=10.2 FORM=10.2 FORM=10.2
12
if(ROWSUM(8) FORM=10.2 if(ROWSUM(9) FORM=10.2 if(ROWSUM(11) FORM=10.2 if(ROWSUM(12) FORM=10.2 if(ROWSUM(13) FORM=10.2 if(ROWSUM(14) FORM=10.2 if(ROWSUM(15) FORM=10.2 if(ROWSUM(16) FORM=10.2 if(ROWSUM(17) FORM=10.2 if(ROWSUM(18) FORM=10.2 if(ROWSUM(19) FORM=10.2 if(ROWSUM(20) FORM=10.2 if(ROWSUM(21) FORM=10.2 if(ROWSUM(22) FORM=10.2 if(ROWSUM(23) ENDPHASE ENDRUN
> 0) PRINTROW mw=8 > 0) PRINTROW mw=9
TITLE='TIMEA ALLMODES', BASE1=T, TITLE='TIMEA TMODES', BASE1=T,
> 0) PRINTROW mw=11 > 0) PRINTROW mw=12 > 0) PRINTROW mw=13
TITLE='TIMEP ALLMODES', BASE1=T, TITLE='TIMEP TMODES', BASE1=T, TITLE='TIMEP NTMODES', BASE1=T,
> 0) PRINTROW mw=14 > 0) PRINTROW mw=15 > 0) PRINTROW mw=16 > 0) PRINTROW mw=17
TITLE='BRDPEN ALLMODES', BASE1=T, TITLE='BRDPEN TMODES', BASE1=T, TITLE='XFERPEN ALLMODES', BASE1=T, TITLE='XFERPEN TMODES', BASE1=T,
TITLE='DIST ALLMODES', BASE1=T, TITLE='DIST TMODES', BASE1=T, TITLE='DIST NTMODES', BASE1=T,
TITLE='BRDINGS ALLMODES', BASE1=T, TITLE='BRDINGS TMODES', BASE1=T, TITLE='BESTJRNY', BASE1=T, FORM=10.2
Public transport loading

This example loads a trip matrix, input with MATI[1], on to a previously prepared public transport network.
12
You must enumerate and evaluate routes before loading trips. The ROUTEO file indicates that the script will enumerate routes. (Alternatively, you can input routes prepared in an earlier run with ROUTEI.) TRIPSIJ[1] indicates that loading is to be performed. (Loading automatically invokes the route-evaluation process.) The REPORT statement selects two loading reportsline summary and passenger loading.
/*Load a previously built PT Network & Produce Loading Analyses Reports */ RUN PGM=PUBLIC TRANSPORT ;Output Files FILEO NETO = LDNET00C.NET FILEO ROUTEO[1] =LDRTE00C.RTE FILEO REPORTO = LDPRN00B.PRN ;Input files FILEI MATI[1] = OD.MAT FILEI NETI =LDNET00B.NET ;Globals this invokes Loading PARAMETERS TRIPSIJ[1] = MI.1.1 ;Selection of Loading Reports REPORT LINES=T, SORT=MODE, LINEVOLS=T, STOPSONLY=T, SKIP0=T ENDRUN
Public transport user classes

This example prepares a public transport network, enumerates and evaluates routes, skims, and loads for two user classes. Essentially, this example performs the main functions of the Public Transport program for two user classes. First, the script develops the public transport network for both user classes from: Network input on NETI Lines input on LINEI[1] Factors input on FACTORI[1] and FACTORI[2]
12
Public Transport system data input on SYSTEMI

GENERATE statements for generating the nontransit network
The script codes the DATAPREP phase, a mandatory phase for public transport network development. Next, the script performs the following functions for each user class: Route enumeration Saves routes on ROUTEO[1] and ROUTEO[2]. Route evaluation Skimming Extracts composite and value-of-choice skims, saves on MATO[1] and MATO[2], and reports. Loading Loads trip matrices input on any MATI file (not necessarily the one subscripted by the user class) to the evaluated routes.
The script codes the MATO phase to report the output skim matrices. Finally, the script saves a public transport network containing the results of the loadings for both user classes to NETO. You can display the results with Cube.
;Generate Non-transit network, Enumerate, Evaluate Routes, Skim and Load for two User Classes. RUN PGM=PUBLIC TRANSPORT :Output Files FILEO REPORTO = LDPRN00A.PRN FILEO ROUTEO[2] = LDRTE00D.RTE FILEO ROUTEO[1] = LDRTE00A.RTE FILEO NETO = LDNET00E.NET :input FILEI MATI[2] = MSMAT00B.MAT FILEI MATI[1] = MSMAT00B.MAT FILEI SYSTEMI = PTSYSTEM.PTS FILEI FACTORI[2] =FACTORUS2.FAC FILEI FACTORI[1] = FACTORUS1.FAC
12
FILEI LINEI[1] = ISL_PTLINES.LIN FILEI NETI =LDHWN00A.NET ;Globals PARAMETERS PARAMETERS PARAMETERS PARAMETERS
TRANTIME=li.TrnsTime USERCLASSES=1,2 TRIPSIJ[1] = Mi.01.1 TRIPSIJ[2] = Mi.02.1
PHASE=DATAPREP ;generate access/egress links list='\nGenerate Zone Access/Egress Legs GENERATE, COST=li.WalkTime, MAXCOST[1]=16*20, LIST=T, NTLEGMODE = 33, INCLUDELINK = li.WalkTime>0 ;generate xfer non-transit legs list='\nGenerate Transfer Legs ' GENERATE, COST=li.WalkTime, MAXCOST[1]=16*15, LIST=T, NTLEGMODE = 34, ONEWAY=F, INCLUDELINK = li.WalkTime>0, FROMNODE=26-4000, TONODE=26-4000 ENDPHASE
'
;Routes are enumerated, evaluated, skimmed and loaded for each user class ;SKIMIJ loops over IJ pairs. Skims are saved in working matrices in this phase PHASE=SKIMIJ MW[1]=COMPCOST(0) ;composite cost MW[2]=ValOfChoice(0) ;value of choice ENDPHASE ;MATO loops over J for each I. Skims are reported for each user class PHASE=MATO if(ROWSUM(1) > 0) PRINTROW mw=1 TITLE='Compcost', BASE1=T, FORM=10.2 if(ROWSUM(2) > 0) PRINTROW mw=2 TITLE='ValOfChoice', BASE1=T, FORM=10.2 ENDPHASE
12
ENDRUN
13
Utilities
This chapter describes utilities. Topics include: UB2TPP TPP2UB SYNCHIMP Saturn conversion
13
Utilities UB2TPP
UB2TPP
Utility program UB2TPP can be used to convert FTA New Start User Benefit matrix files in SUMMIT binary format to standard TP+/Cube Voyager format. The following control statements are available in the Cube Voyager UB2TPP utility program.
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
Utilities UB2TPP
13
FILEO
Outputs data files. MATO VARO
Keyword MATO VARO |KF| |KF| Description Specifies the filename of the converted TP+/Cube Voyager binary matrix file. Optional. Specifies the filename of the user benefit VARO file. The VARO file contains the variable information from the user benefit file header. A sample of the VARO file is listed below:
UBTRNCOEF=2.34567 UBAUTOCOEF=8.7654336 UBPURPOSE='Pabcde' UBTOD='DataTi' UBALTNAME='Another a test header (11223344556677) with sixty characters'
The VARO file can be used in another Cube Voyager program (for example, Matrix) by reading the file in, for example:
run pgm=matrix filei mati=t10_36.mat read file=ubout.var mw[1]=mi.1.1*UBAUTOCOEF endrun
PARAMETERS
Sets general parameters. HEADERONLY
Keyword HEADERONLY |?| Description <F> is a switch to indicate that only the header information is to be written to the MATO and VARO files. The MATO file must be specified even if HEADERONLY=T.
13
Utilities TPP2UB
TPP2UB
Use the TPP2UB utility program to convert standard binary TP+/Cube Voyager format matrices to FTA New Start User Benefit matrix files in SUMMIT binary format. The following control statements are available in the Cube Voyager TPP2UB utility program.
Control statement FILEI FILEO PARAMETERS Description Specify input TP+/Cube Voyager input file and the user benefit variable file. Specify output binary user benefit file. Set static parameters.
FILEI
Inputs data files. MATI VARI
Keyword MATI VARI |KF| |KF| Description Specifies the filename of the binary TP+/Cube Voyager matrix file to be converted. Specifies an optional variable file that contains the variable information for the user benefit file header.
FILEO
Outputs data files. MATO
Keyword MATO |KF| Description Specifies the filename of the converted binary user benefit file.
Utilities TPP2UB
13
PARAMETERS
Set general parameters. The program must have values for all PARAMETERS. They may be coded directly with the PARAMETERS statement, they may be read in on the VARI file which was the result of a VARO file from UB2TPP or they may be read in on a VARI file that is hand coded. TRNCOEF AUTOCOEF PURPOSE TOD ALTNAME
PARAMETERS keywords
Keyword ALTNAME AUTOCOEF PURPOSE TOD TRNCOEF |KS| |KS| |KS| |KS| |KS| Description User Benefit ALTNAME value User Benefit AUTOCOEF value User Benefit PURPOSE value User Benefit TOD value User Benefit TRNCOEF value
13
Utilities SYNCHIMP
SYNCHIMP
Use the SYNCHMP utility program to convert SYNCHRO data to Cube Voyager intersection data format.
NOTE: Cube has a SYNCHRO data import wizard accessible from the Tools menu.
The following control statements are available in the Cube Voyager SYNCHMP utility program.
Control statement FILEI FILEO PARAMETERS Description Specify input SYNCHRO files. Specify output Cube Voyager files. Set static parameters.
FILEI
Inputs data files. LAYOUTI LANESI PHASINGI TIMINGI VOLUMEI
FILEI keywords
Keyword LANESI LAYOUTI |KF| |KF| Description Specifies the filename of the input SYNCHRO LANES file. Specifies the filename of the input SYNCHRO LAYOUT file.
Utilities SYNCHIMP
13

Keyword PHASINGI TIMINGI VOLUMEI |KF| |KF| |KF| Description Specifies the filename of the input SYNCHRO PHASING file. Specifies the filename of the input SYNCHRO TIMING file. Specifies the filename of the input SYNCHRO VOLUME file.
FILEO
Outputs data files. NODEO LINKO JUNCDATAO
Keyword JUNCDATAO LINKO NODEO |KF| |KF| |KF| Description Specifies the filename of the output intersection data file. Specifies the filename of the output link file. Specifies the filename of the output node file.
PARAMETERS
Sets general parameters. The values of these parameters are stored in the associated SYNCHRO input CSV data files. PLANID VOLDATE VOLTIME
13
Utilities SYNCHIMP
UNITS
PARAMETERS keywords
Keyword PLANID VOLDATE VOLTIME UNITS |KS| |KS| |KS| |KS| Description Specifies the PLAN ID value in the TIMING file. Specifies the date value in the VOLUME file. Specifies the time value in the VOLUME file. Specifies the units of the LANES file. Valid values are meters or feet.
Utilities Saturn conversion
13
Saturn conversion
The SaturnPath utility program converts output from the Saturn assignment program into a Cube Voyager path file. The Cube installation program installs this program in the Cube directory (C:\Program Files\Citilabs\Cube\SaturnPath.exe in standard installations). You can access this program several ways: Windows Explorer Command line or batch file Cube Base (from the Tools menu choose Convert Saturn Path File to Voyager Path File)
This section discusses: Running from program window Running from command line
Running from program window

If you access SaturnPath from Cube Base or Windows Explorer, you will open the program window.
The window contains two fields and several command buttons:

Input Saturn Path File Enter the existing file containing the
Saturn output.
13
Utilities Saturn conversion
Output Voyager Path File Enter the new file you want to
create containing a Cube Voyager path file

Browse Click to search for the file in a file browser. Convert Click to run the utility and convert the specified
input into a Cube Voyager-formatted path file and write the results to the specified output file.
Close Click to close the program window. Show Saturn File Statistics Click to show statistics about the Saturn file (number of paths, minimum and maximum zone number, node number, class number, route number, flow, and number of nodes in path).
Running from command line

When called from a command line or batch file, SaturnPath accepts up to three parameters: Input file containing Saturn paths Output file to write Cube Voyager paths Start flag (set to GO to start automatically)
If you specify all three parameters (setting the start flag to GO), the program automatically starts converting the input file. If there are no errors during the conversion, the program automatically writes the output file. If the specified output file does not exist, the program will close automatically, too; otherwise, the program will prompt to overwrite the file. If you do not specify all three parameters, the program window will open, with fields showing any parameter values that you did specify.
14
Cube Cluster
This chapter discusses Cube Cluster, an optional extension you can use with Cube Voyager. Topics include: Using Cube Cluster Control statements Utilities
14
Cube Cluster Using Cube Cluster
Using Cube Cluster

This section provides information about using Cube Cluster. Topics include: Cube Cluster introduction Cube Cluster control statement summary Working with Cube Cluster
Cube Cluster introduction

A computer cluster is a group of loosely coupled computers that work together closely so that in many respects they can be viewed as though they are a single computer. The components of a Cluster are commonly, but not always, connected to each other through fast local area networks. Clusters are usually deployed to improve speed and/or reliability over that provided by a single computer, while typically being much more cost-effective than single computers of comparable speed or reliability. Clusters are typically configured for either high availability or high performance. High availability clusters are configured for redundancy and make use of redundant nodes to provide continuous service when primary nodes fail. This type of cluster would commonly be used for a Web server for high volume web sites where continuous access is in demand. High-performance clusters increase performance by splitting a computational task across many different nodes in the cluster. These clusters are most common in scientific computing. Highperformance clusters are optimal for workloads that require the processes on separate computer nodes to communicate actively during the computation. This includes computations where intermediate results from one nodes calculations affect future calculations on other nodes.
14
Cube Cluster implemented in Cube Voyager allows you to create your own high-performance computer cluster to distribute the workload of your Cube Voyager model run across multiple computing nodes. Each computing node consist of a single computer processor so assembling your own computer cluster is as simple as networking several existing computers together on a local area network. Many office environments already have such local networks of computers in place which can be utilized to support Cube Cluster. Alternatively, dedicated machines could be connected together on a local network to form an independent modeling cluster for dedicated modeling work independent of regular office computing. Still a third and potentially superior alternative would be to purchase a dedicated multiprocessor machine with each processor acting as a cluster node so that all of the computation and data sharing is contained in one local machine and is not dependent on you local network connections. Cube Cluster can be used to significantly reduce model run time by distributing steps in the model flow that are not dependent on one another and executing them simultaneously on distributed or parallel processing nodes. Most travel demand models will have some steps that are choke points in the model flow: additional following steps require the outputs of these steps before they can be run. Most travel demand models will also have many steps that can be run at the same Itime if independent processing nodes are available. Some reconfiguration of the model flow may be required to group those steps together that can be run simultaneously. Cubes Application Manger flow chart view of your model provides a convenient tool for identifying the model steps in an application that can be distributed. Model step dependencies are easily visible from the data flows presented in the flow chart. An example is shown in the figure below. This is a fairly typical transit network development and skimming (level of service) process that might be present in many models. Transit network definitions and skim matrices are produced for two periods (peak and off peak travel) and for two separate modes of access (drive and walk only). Each of these steps is independent of each other. Assume that each of these steps run in approximately 9 to 11 minutes. This implies a
14
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
14
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
14
independently processed (see Procedures that disable intrastep distributed processing on page 885 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
14
feature is used. This is because input and script files are referenced by drive letter and directory location during a run and if they are unavailable in that location, the run will fail. Running on a network drive could significantly slow down a run for disk intensive applications depending on the computer networks throughput capacity so there may be little runtime benefit or take even longer when using DP on certain steps. Therefore, it is important to tune the DP setup to get the best performance. In general, DP works well for computation-intensive applications (for example, doing hundreds of matrix computations for each zone in a mode choice step) but will result in less time savings for disk intensive procedures (for example, combining 3 matrix files into one matrix file).
Cube Cluster control statement summary

Control statement DISTRIBUTE DistributeMULTISTEP EndDistributeMULTISTEP Wait4Files Description Global control for DP options. Initiates MDP script block in Pilot unless the global switch is off. Ends a MDP script block in Pilot. Sets a wait condition to insure all MDP steps of a block are completed prior to running subsequent model steps
The following control statements are available in the Cube Voyager Matrix and Highway programs to implement IDP
Control statement DistributeINTRASTEP Description Initiates IDP of the current Matrix or Highway step.
Working with Cube Cluster

Implementing Cube Cluster should generally be performed after model development and calibration/validation. When you are satisfied with the results of your model or model process when running on a single processing node then implement Cube Cluster
14
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.
14
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 895 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.
14
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
14
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 895 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:
14
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 895 for additional information on getting multiple instances of Cube Voyager open and configured in wait mode. The ProcessID and the ProcessNum number are used to make up the name of the wait file. ProcessID is the same as defined above for IDP. ProcessNum is a single process number since the steps are distributed to one process only. When a block of operations is distributed to another processing node, the main computer will continue running the script without waiting for the sub-process on this other processing node to finish. It is the users responsibility to check for sub-process completion before using output files generated by the sub-process. When a sub-process is done, it will create a file named {ProcessID}{Process#}.script.end. Use the Wait4Files command to wait for the .end file to be created in Pilot. For example:
Wait4Files Files=TestDist1.script.end, TestDist2.script.end, TestDist3.script.end, CheckReturnCode=T, UpdateVars=vname,Matrix.xname, PrintFiles=Merge, DelDistribFiles=T
The Files keyword specifies a list of all the files to wait for and the CheckReturnCode keyword specifies if the return codes from the sub-processes should be checked. When true, the whole run will stop if a sub-process returns with a code 2 (fatal) or higher. The UpdateVars keyword specifies a list of global variables computed in Pilot and logged from individual programs that should be merged back from the sub-process run. Any variables with the first part of the name matching an UpdateVars name will be merged back. For example, for UpdateVars=vname,Matrix.xname, variable
14
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 sub-process inherits a copy of all the global variables to start with (ThisVar=1), so even though the sub-process never modify 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
14
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
14
... 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
14
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:
14
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
14
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
14
ro.ZoneType = zt ro.SFDU = zi.1.SFDU[zt] write reco=1 endloop exit endrun
14
Cube Cluster Control statements
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
14
DISTRIBUTEMULTISTEP keywords
Keyword PROCESSID |S| Description Prefix for the file names used to communicate with the sub-processes. In addition to a string constant, a Pilot string variable can be used to set the ProcessID by putting it within @ characters (for example, ProcessID=@MyID@). Single process number since the steps are distributed to one process only. In addition to a single numeric constant, a Pilot numeric variable can also be used to set the process number dynamically (for example, ProcessNum=MyProcess). Common path for checking for availability of processors. Defaults to null (working directory used). The common path is only used for initial communication with the node. The node switches its work directory to be the same as the main process before running the multistep (or intrastep) distributed process. After completing the steps, the node reverts to waiting for the communication file in the COMMPATH directory. This will work regardless of the location of the script file and the work directory of the main process. Nodes can be waiting in the COMMPATH directory, then when a model run requests the node it will switch to the work directory for that particular model and run the steps. When it is done, it will go back and wait for further commands in the COMMPATH directory.
PROCESSNUM
|I|
COMMPATH
|S|
ENDDISTRIBUTEMULTISTEP
Statement to end current MULTISTEP subprocess.
WAIT4FILES
When a block of operations is distributed to another computer, the main computer will continue running the script without waiting for the sub-process to finish. It is the users responsibility to check for sub-process completion before using output files generated by the
14
sub-process. When a sub-process is done, it will create a {ProcessID}{Process#}.script.end file. Use the Wait4Files command in the Pilot program to wait for the .end file to be created. FILES CHECKRETURNCODE UPDATEVARS PRINTFILES DELDISTRIBFILES
WAIT4FILES keywords
Keyword CHECKRETURNCODE |?| Description Specifies if the return codes from the subprocesses should be checked. When true, the whole run will stop if a sub-process returns with a code 2 (fatal) or higher. Controls the disposition of the MDP temporary communication files. The default is true, meaning to remove all temporary files.
DELDISTRIBFILES
|?|
14
WAIT4FILES keywords (continued)

Keyword FILES |S| Description Specifies a list of all the files to wait for. In addition to a string constant, a Pilot string variable can be used to set the file names by putting it within @ characters (for example, Files=@MyFile@). Controls the disposition of the print files from the sub-processes. It can be MERGE, MERGESAVE, DELETE, or SAVE. MERGE means the print files will be merged back into the main print file then deleted. MERGESAVE means to merge the files but not delete them. DELETE means no merge but delete them and SAVE means no merge but save them. The default is SAVE. Specifies a list of global variables computed in Pilot and logged from individual programs that should be merged back from the subprocess run. Any variables with the first part of the name matching an UpdateVars name will be merged back. For example, for UpdateVars=vname,Matrix.xname, variable vname1,vnameabc,Matrix.xnamevar etc. will all be merged back to the main process.
PRINTFILES
|S|
UPDATEVARS
|S|
DISTRIBUTEINTRASTEP
Programs: Matrix, Highway
Invoke intrastep distributed processing. Currently only available in Matrix and Highway. PROCESSID PROCESSLIST MINGROUPSIZE SAVEPRN
14
COMMPATH
DISTRIBUTEINTRASTEP keywords
Keyword COMMPATH |S| Description Common path for checking for availability of processors. Defaults to null (working directory used). Minimum distributed zone group size. If there are more sub-processes than there are zone groups of this size, then some sub-processes will not be used. For example, if there are 100 zones and MinGroupSize is 20 and ProcessList=1-10, only 4 sub-processes will be used to process 20 zones each and the main process will process 20 zones itself. The ProcessID is the prefix for the file names used to communicate with the sub-processes. List of sub-processes to use for DP. It is a list of numbers and put in as individual numbers or ranges (for example, ProcessList=1,5,10-20,25). Each sub-process must be assigned a unique process number. Switch to control if the sub-process print files should be saved or not.
MINGROUPSIZE
|I|
PROCESSID PROCESSLIST
|S| |I|
SAVEPRN
|?|
Cube Cluster Utilities
14
Utilities
This section describes: Cluster executable Utility functions
Cluster executable
Use the cluster.exe utility program, found in the Cube program folder, to start multiple processing nodes on the local machine. You can access this utility from Cube Base. From the Tools menu, choose Cluster Node Management to open the Cluster Node Management dialog box.
14
In Time to Wait for Response, enter the number of seconds Cube Cluster should wait for a response from a node before determining that the node is unavailable. Click Close Nodes to close any processing node (remote or local), and click List Nodes to return the status of any processing node (remote or local). You can also run this program from a Windows command line. Therefore, you can run the program from either a .bat batch file or from a Cube Voyager * command call. The syntax for the command line is:
Cluster [ProcID] [ProcList] [Start/Close/List] [Exit]
Starting processing nodes in Cube Cluster
Prior to starting a distributed-processing run using Cube Cluster, individual instances of Cube Voyager must be running and set to wait mode with the appropriate script file name and work directory for the run. A Cube Cluster processing node corresponds to a single, properly configured instance of Cube Voyager running and waiting. Processing nodes can either be additional processors on the local computer (local nodes) or processors on remote computers connected to the main computer over a local network (remote nodes). You can start an instance of Cube Voyager manually by running the Voyager.exe program in the Cube Voyager program directory and setting the script and working directory, or by running the Cluster.exe program as described in Cluster executable on page 895. You cannot start instances of Cube Voyager on remote nodes over a network. You must start remote nodes directly on the remote machines. Typically, you must physically go to each machine and run either the Voyager.exe or the Cluster.exe program on that machine. Alternatively, you can use the COMMPATH keyword to send information to active instances of Cube Voyager, which are open and running on remote processing nodes. Use COMMPATH to send changes in script and working directory names to waiting instances of Cube Voyager without having to physically visit each machine and make changes manually.
14
You use COMMPATH only for initial communication with the node. The node will switch its work directory to be the same as the main process before running the multistep distributed process. After completing the steps, the node reverts to waiting for the communication file in the COMMPATH directory. Citilabs recommends starting an instance of Cube Voyager on each remote processor that you will use, setting the work directory to a common path like z:\wait, and leaving them run. Then, you can use this value as the COMMPATH keyword value.
Utility functions
A number of utility functions were added to the Cube Voyager system to allow more flexibility in performing distributed processing: FilesExist('file1|file2|file3...') This function will check for the existence of one or more files. The function takes one string argument (constant or variable) and if there are more than one file to check, they are put into one string and separated by '|'. The return value is the number of files that exist. If none of the files exist, then the return value will be zero. This can be use instead of the Wait4Files command if you only want to check if a node is done but dont want to wait for it to get done. NumReadyNodes('ProcessID','ProcessList') This function will check for availability of a list of Cube Cluster nodes. The second argument is a string with the list of process numbers to check. The return value is the number of ready nodes. For example, NumReadyNodes('TestDist','1-5,10,15-20') or NumReadyNodes(MyProcess,MyProcessList) FirstReadyNode('ProcessID','ProcessList') This function will check for availability of a list of Cube Cluster nodes and return the process number of the first available node. The second argument is a string with the list of process numbers to check. The processes are checked in the input order and can go from low to high or high to low so if the list is '6-2' and all processes (2-6) are available, the result will be 6. For example, FirstReadyNode('TestDist','1-5,10,15-20')
14
The following is an example for using the NumReadyNodes function when there are two separate groups of Cube Cluster nodes that may be available to participate in a DP run, the script wants to select the one with the most available nodes:
IF (NumReadyNodes(DP1,1-10) > NumReadyNodes(DP2,11-20)) MyProcessID=DP1 MyProcessList=1-10 ELSE MyProcessID=DP2 MyProcessList=11-20 ENDIF RUN PGM=Matrix DistributeIntraStep ProcessID=@MyProcessID@, ProcessList=@MyProcessList@
15
Cube Avenue
This chapter discusses Cube Avenue, an optional extension to Cube Voyager. Topics include: Using Cube Avenue Control statements Theory Examples
15
Cube Avenue Using Cube Avenue
Using Cube Avenue

This section provides information useful when using Cube Avenue: Cube Avenue introduction Phases
Cube Avenue introduction

Cube Avenue is the Cube Voyager program for performing dynamic traffic assignment. Derived from the Cube Voyager Highway program, which implements static traffic assignment, Cube Avenue shares the same PHASE structure but has additional commands and keywords to implement dynamic traffic assignment. Older traffic models tend to fall into two categories: Operational traffic models Planning models
Operational traffic models, such as Cube Dynasim (microsimulation) and SYNCHRO (signal optimization), are useful for modeling network component interactions as queues and delays vary during the model period. For example, these models can show how signal offsets and synchronization can create a green wave, or how long queues can disrupt traffic flows through upstream junctions (blocking back). However, these models are not useful for forecasting routing (if they do so at all). Microsimulation models also model day-to-day variation by using different random number seeds. Sufficient runs can provide measures of trip time reliability. However, most analysts only complete enough runs to obtain a representative sample and extract averages. Of course, random day-to-day variations differ from the way travellers learn by experimenting with different routes on different days, introducing a systematic, convergent trend into travel patterns.
15
Planning models, on the other hand, do capture how drivers experiences over long periods of time allow them to pick optimal travel strategies for regular, frequent trips, such as trips to work. These models iterate on capacity restraints, finding Wardrop User Equilibrium solutions to the travel assignment problem. These models are sometimes described as macrosimulation models. Cube Avenue tries to find a middle ground between these two extremes. Cube Avenue uses a path builder in a capacity-restraint loop to model drivers finding routes and modifying those routes based on experience. However, to evaluate the costs generated by a set of routing decisions, Cube Avenue simulates the movement of vehicles through the network. Hybrid models, like Cube Avenue, are known as mesosimulation models.
General scripting advice

The dynamic assignment program is still new but there are several points arising from our experience so far: Statically assign the matrix and study the distribution of degree of saturation in the output network. If there are any nodes or links where demand exceeds supply by a factor of two or more, you will need to clean up the network and/or matrix before continuing. Typical actions include checking that the matrix is for the right period and checking that the capacity coded in the network is correct. The target packet size should be at least as big as the expected number of iterations. If the matrix is large, a bigger value may be appropriate. Avoid small matrix cells. Every non-zero cell must generate packets. But packets consume computer memory and processor cycles. Therefore a matrix with many small cells can cause lots of time and RAM to be wasted. Bucket rounding the matrix before assigning it is probably the easiest way of cleaning a non-sparse demand matrix but, if you have enough local knowledge of the study area, you may be able to clean the matrix better by hand.
15
Phases
This section describes the typical phases in Cube Avenue: SETUP phase LINKREAD phase ILOOP phase ADJUST phase CONVERGE phase
SETUP phase
This phase behaves identically in Cube Avenue and standard Cube Voyager Highway assignments.
LINKREAD phase
This phase behaves similarly in a Cube Avenue assignment to the corresponding phase in a Cube Voyager Highway assignment. In particular it executes twice per iteration (once before phase ILOOP and once before phase ADJUST) but it does not execute time segment by time segment. The command, DYNAMIC, is only available in this phase. With this command, you can vary the values of the C variable by time segment. At present, only C my be varied in this way; future releases will allow you to vary STORAGE, too. This functionality may be used, for example, to model tidal flow lanes. Variables and input fields applicable to this phase include: DISTANCE LINKCLASS LI.SPDCLASS, LI.CAPCLASS LI.LANES SPEED
15
C T0 T1 STORAGE
DISTANCE
If the user does not set this variable in script, it will be initialized from LI.DISTANCE, if that variable exists and has a non-negative value. Failing that, it defaults to zero. Zero distance links are sometimes described as dummy links. As in any network, free-flow time must be provided independently of speed for zero distance links, and output speeds are not meaningful for them. In Cube Avenue, a link distance of zero may also cause STORAGE to default to zero (with disastrous consequences for the modeling). Distance is usually measured in miles or in kilometers.
LINKCLASS
In Cube Avenue, LinkClass functions as the index for functions TC and COST, as it does in any other highway assignment. If the script does not set the variable, LI.LINKCLASS will be used if the variable exists and has a positive value. Failing that, it defaults to one.
LI.SPDCLASS, LI.CAPCLASS
If these field(s) exist, and the values in them are positive, and appropriate speed or capacity tables are defined in the network, or in the script, they will be used, in conjunction with Li.Lanes, to look up base speed and capacity values.
15
LI.LANES
The variable Li.Lanes will be taken from the input network. If there is no such field or if the value in the field is non-positive, a value of one will be used. Note that the field name required in the input network is LANES and that fields with similar names, such as NumberOfLanes, will not be recognized as the number of lanes. As in any highway assignment, Li.Lanes, may be used as an index into speed or capacity tables. In Cube Avenue, LI.LANES may also take part in the default STORAGE calculations.
SPEED
If the user does not set this variable in script, then defaulting will be from Li.Speed if that exists. If Li.Speed does not exist, but Li.Lanes does, a speed table lookup will be attempted. If all defaults fail, or if they result in a negative value, Speed will be initialized to zero. Note that, during the modeling, SPEED is a dependent variable; the independent variable is TIME. Thus the defaulting behavior of SPEED is only significant if it is used to calculate a default for T0. Speed is in distance units per hour.
C
This is the flow capacity of the link, in vehicles per model period. Note that this measures how quickly the link can discharge or accept vehicles. This capacity differs from STORAGE, which measures how many vehicles can occupy the link simultaneously. Scripts can use the DYNAMIC command to specify that the value of C varies by time segment. If the script does not explicitly set this variable, the value in Li.Capacity is used as the default. If Li.Capacity does not exist but Li.Lanes does, a capacity table lookup will be attempted. If none of these values exists, a value of zero will be applied (with disastrous consequences for Cube Avenue modeling). Finally, if PARAMETERS CAPFAC has been coded, that factor will be applied.
15
Essentially, this value is the maximum frequency with which a vehicle can be discharged from or admitted to a link. Thus, a zerocapacity link can delay packets forever.
T0
This is the free-flow time for the link, in minutes. It is used during application of the function, TC. If the user does not set a value in script, the program will look in turn for Li.T0, Li.Time and Li.Time1, in that order. If it still cannot find a value it will try to use 60*Speed/Distance. If all else fails, a default of zero will be applied.
T1
This is the link time to be used on the first iteration of assignment, before any calculated times are available from an ADJUST phase. Note that in Cube Avenue it is applied to every time segment. It defaults to T0 unless the user explicitly sets the value in script. It is very common to accept this value, although there may be some merit to using observed times where these are available.
STORAGE
This is the number of vehicles that can fill the link. Both queuing and moving vehicles on the link will use up storage. However, the storage does not directly limit the flow on the link; so long as vehicles leave the link as fast as new vehicles arrive, the number of vehicles on the link does not change. Thus every link has two capacities: the standard capacity, C, restrains flow while STORAGE restrains occupancy. If the user script does not supply a positive value for STORAGE, the program will try to extract a value from LI.STORAGE. If a positive value still cannot be found, LI.LANES*DISTANCE*vpd, where vpd denotes the value of PARAMETERS VEHPERDIST, will be tried. If all else fails a value of zero will be applied (with the disastrous consequence that the link will always be full, and hence, impassable).
15
Note that a link that has any spare storage will admit packets. In particular, if a packet arrives at a link with some storage available, but the packets volume exceeds the available storage, it will still be admitted to the link. (The link then becomes full, and it remains full until it has discharged sufficient vehicles to reduce the occupancy back below 100%.) Thus the maximum number of vehicles that can be observed on a link may exceed that links storage slightly.
ILOOP phase
This phase is concerned with the creation of packets and the determination of routes. The user script associated with this phase is executed for each time segment, and within each time segment for every origin. This script should contain one or more DYNAMICLOAD statements. A conventional load (that is, a PATHLOAD statement) evaluates an expression (usually involving matrices) to determine the number of trips, builds paths according to some attribute minimization criterion, and then it loads the trips into the networks volume fields. A dynamic load evaluates an expression (usually involving matrices) to determine the number of trips, builds paths according to some attribute minimization criterion, but it defers updating the volume fields until the adjust phase. The trips are placed into packets, where each packet contains a start time, a volume in one or more volume fields, and a route. However, the networks volume fields may only be updated later after calculating, for each point on the route, when (that is, in which time segment) the packet arrives there. Note that on the second and subsequent iterations, packets generated during earlier iterations are not discarded; they just have their volumes modified according to the factors generated by the COMBINE methodology in force. Thus for COMBINE=AVE, the volumes in the packets generated during the current iteration will be given by {expression value}/{iteration number} and the new
15
volume for old packets will be ({iteration number} 1){previous volume}/{iteration number}. All the packets from all the iterations so far will be simulated during the current iterations ADJUST phase.
ADJUST phase
This phase is executed when the movement of packets through the network is simulated. Initially, all network link times are given by applying the TC function applied to the volumes assigned in the previous iteration for the corresponding time segment (except for the first iteration, when T1 is used). During the simulation, a queue of events is maintained. In addition, there is a queue of blocked packets waiting to get on each downstream link. There are four kinds of event that can be stored in the event queue: a packet departs an origin, a packet arrives on a new link, a packet arrives at its destination, or a packet becomes unblocked on a link. Initially the event queue contains one event for each packets departure from that packets origin and all the link queues are empty. The event queue is sorted on the time at which the events are scheduled to occur. The events from the event queue are processed in turn. As each event is processed more events are added to the queue. For example, when a packet is scheduled to arrive at a link A from link B, it is verified whether link A will accept the packet (if not it joins link As queue) and an arrival event is scheduled for the next link on the path; before the event processing is completed, a check is made to see whether any packets can be released from link Bs queue. Since every event occurs at a specified time, it is easy to determine whether the next event occurs in the same time segment as the current one. If not, or if the end of the model period has been reached, the script associated with the ADJUST phase is executed for the time segment that has just been completed. At the end of the entire simulation, some of the results are aggregated to obtain values relevant to the entire modeled period. It is these aggregate values that are passed to the Converge phase.
15
CONVERGE phase
The CONVERGE phase is only executed once per iteration. It executes exactly the same as it would in a static highway assignment.
Cube Avenue Control statements
15
Control statements
This section describes Cube Avenue-specific control statements:
DYNAMIC DYNAMICLOAD FILEO PARAMETERS PATHLOAD
The control statements available in the Highway program are also available in Cube Avenue.
DYNAMIC
Changes the value of the capacity variable by time segment. Only use this command during the LINKREAD phase.
Keyword C |NV99| Description Defines link capacity by time segment. Link capacity is initially defined as it normally would be for a static assignment (specified with COMP C= in the LINKREAD phase, read from the input network variable li.CAPACITY or read from the internal speed/capacity table). In Cube Avenue, link capacities are vectored by time segment. A links capacities by segment are initially set to the static capacities for all segments. Use the DYNAMIC statement to set segment-specific capacities. For example:
DYNAMIC C[3]=1800, 1000, 1800
results in C taking the value 1800 during time segments 3 and 5, 1000 during time segment 4 and its usual value during all other time segments. Normally this statement occurs in conjunction with an IF statement that applies the statement to the correct link:
IF (A=1005&B=1010) DYNAMIC C[4]=90
15
This statement is useful for modeling time-dependent changes in link capacities, such as reversible lanes, the closing of HOV facilities at specific times of day, the opening of HOV facilities to general purpose uses at specific times of day, or construction closures. For example, suppose you have: Input network with a default hourly lane capacity coded as CAP Cube Avenue model period is 180 minutes with three 60minute time segments In the last hour of the period some shoulder lanes available in the prior two hours are no longer available
You can set the default capacities for all links in all segments with the static script statement:
C=li.CAP*li.LANES1*3
Then use the DYNAMIC statement to set capacity in the third time segment when the shoulder lanes become unavailable:
DYNAMIC C[3]=li.CAP*li.LANES2*3
where LANES1 and LANES2 contain the available lanes during the first two hours and the last hour, respectively.
DYNAMICLOAD
DYNAMICLOAD is the dynamic analog of the static PATHLOAD
statement. DEMANDISHOURLY = t/f INCLUDEJ = list EXCLUDEJ = list VOL[n] = list PATH = time/cost/list EXCLUDEGRP = list PACKETSIZE = value PENI = list
15
PENIFACTOR = value MW[n] = TRACE(real, expr, list) NOACCESS=real This statement may only occur in PROCESS PHASE = ILOOP. A static assignment script must contain one or more PATHLOAD statements but may not contain a PARAMETERS MODELPERIOD= SEGMENTS= clause nor a DYNAMICLOAD statement. A dynamic traffic assignment must include a PARAMETERS MODELPERIOD= SEGMENTS= clause and at least one DYNAMICLOAD statement. It may also contain one or more PATHLOAD statements, in which case simultaneous dynamic and static loadings will occur. See Combined use of DYNAMICLOAD and static PATHLOAD on page 913 for a description on running combined DYNAMICLOAD and static PATHLOAD in the same run. Most of the clauses have the same syntax and meaning as the corresponding clauses of the PATHLOAD statement, so only the differences are noted in this document. Furthermore, it is intended to allow some other clauses of the PATHLOAD statement to be applied to dynamic loading once the relevant functionality has been implemented. Several clauses of the DYNAMICLOAD statement require timesegmented lists as inputs (these lists contain one item per time segment). If you enter a single value that contains one or more occurrences of __TS__, Cube Avenue expands the value into a list by replacing the __TS__ with the integers representing the time segments, such as 1, 2, and so forth. For example, entering PATH=LW.COST__TS__ is equivalent to entering PATH=LW.COST1, LW.COST2, LW.COST3, and so forth. The DYNAMICLOAD PATH= clause may take, as its value, TIME, COST, or a list of input link attributes (that is, LI. Variables or LW.Variables; one per time segment). In the first two cases, the path will be built to minimize the appropriate time varying function. In the last case, a time varying function to be minimized will be constructed by using the value from the appropriate link attribute in each time segment. The predicted disutility for a vehicle of
15
traveling down a link is therefore dependent on the time segment in which the vehicle expects to enter that link. You can use the macro expansion of _TX to abbreviate the list of link variables. The DYNAMICLOAD DEMANDISHOURLY = clause is, by default, false. It determines whether the demand volumes for each time segment are supplied as an absolute value in vehicles or as a rate in vehicles per hour. For example, suppose that there is a segment of 15 minutes, and the corresponding expression in a DYNAMICLOAD VOL[n] = clause evaluates to thirty. If DEMANDISHOURLY, then the demand is 30 vph and 7 vehicles will depart the origin during the time segment. Otherwise thirty vehicles depart the origin during the time segment, giving a departure rate of 120 vph. The DYNAMICLOAD VOL[n] = clause is similar to the PATHLOAD VOL[n] = clause. This clause evaluates expressions for each destination (subject to INCLUDEJ and EXCLUDEJ clauses) and interprets the result as a demand volume for the specified volume field. The entered value must be a list of expressions with one entry per time segment. You can use __TS__ to abbreviate the list, such as VOL[1]=MW[__TS__+3]. When the ILOOP is executed for time segment n, the nth element of the list will be the one that is evaluated. If necessary, the value is converted to give the number of vehicles departing during the segment and then compared with the target packet volume to determine how many packets are generated. At least one packet will be generated for any IJ pair that has a positive demand. The paths will be assigned routes based on their departure time and their expectations of travel time and disutility. However, no change to the volume field values occurs during PROCESS PHASE=ILOOP. Instead actual loading is deferred until the simulation runs in the PROCESS PHASE=ADJUST. The DYNAMICLOAD PACKETSIZE = clause specifies the target number of vehicles per packet. The DYNAMICLOAD MW clause specifies skims. The value must take the form:
TRACE(time, expression, penalty)
15
where: time is the start time, specified in minutes since the beginning of the model period. It indicates that the skim should be for vehicles departing their origins at the specified start time. Negative values indicate that the start time is in the 'warm up' period. expression is the expression evaluated and summed for each link on the route. penalty is an optional list of turn penalty sets to include in the skim.
You can use the special expression, PATHCOST, to skim the value of the DYNAMIC PATH clause. If the expression contains the string __TS__, it will be evaluated as a dynamic expression that varies by time segment.
Combined use of DYNAMICLOAD and static PATHLOAD

The combined use of both static and dynamic processes in the same run can be accomplished but some care should be taken to insure it is implemented correctly and the user is carrying out what is intended. There are two classes of assignment process now supported in Cube Voyager: Static and Dynamic. A static assignment process is what users should be familiar with as the typical assignment process. In Cube Voyager a static assignment process contains no dynamic elements. If using Cube Avenue to perform dynamic traffic assignment, the assignment process will include dynamic elements but may also include static elements. A few rules apply to these two cases when using Cube Avenue as described below.
Case 1: Static assignment
There are no instances of PARAMETERS MODELPERIOD= SEGMENTS= in the entire script [this setting is the key that switches modes]. There must be at least one instance of PATHLOAD in phase ILOOP; there may be more than one.
15
There may not be any instance of PATHLOAD outside phase ILOOP. There may not be any instances of DYNAMICLOAD. No variables are vectorized by segment and all apply to the model period as a whole. There is a single static time segment and it runs same as the Highway program has always run.
Case 2: Dynamic assignment
There is exactly one instance of PARAMETERS MODELPERIOD= SEGMENTS =. There must be at least one instance DYNAMICLOAD in phase ILOOP; there may be more than one. There may be instances of PATHLOAD in phase ILOOP. There may not be any instance of PATHLOAD outside phase ILOOP. There may not be any instances of DYNAMICLOAD outside of phase ILOOP. There is one time segment for each of the segments listed with the SEGMENTS= PARAMETER and phase ILOOP will be executed for each of them. During each of these executions of ILOOP, a single item from the list of matrix expressions in each DYNAMICLOAD statement is evaluated (and paths built, packets created, etc.). No PATHLOAD statements are executed during any of these executions of phase ILOOP. If there are any instances of PATHLOAD, an additional execution of PHASE ILOOP occurs prior to any of the executions described above. During this execution of phase ILOOP, no DYNAMICLOAD statements are executed but PATHLOAD statements are. The volumes assigned are assumed to apply to the model period so the volumes applicable to each of the time segments get preloaded with PATHLOAD-VOLUME*(length of segment)/(model period).
15
Phase ADJUST is executed for each time segment. The results (except for volumes) are carried forward to the corresponding execution of ILOOP during the next iteration. After ADJUST has been executed for each time segment, aggregate values applying to the model period are calculated from the results individual time segments. These aggregate results are used for the calculation of convergence statistics. If there are any PATHLOAD statements in phase ILOOP, then these values (except for the volumes) will be carried forward to the static execution of phase ILOOP during the next iteration.
Note that none of the discussion above depends on the ordering of PATHLOAD and DYNAMICLOAD statements. It is their presence or absence from the ILOOP PHASE of the script (as a whole) that is significant.
FILEO
Highway program output files are not supported under FILEO if running a dynamic assignment process under AVENUE. SUBAREAMATO (FORMAT DEC NAME) ESTMICPO (VAR SCREENLINE) ESTMDATO NAME Note that a FILEO PATHO may be specified but it may not have dynamic paths written to it during a dynamic assignment run under AVENUE. If a DYNAMICLOAD PATHO=T control is found in the ILOOP PHASE, a fatal error will be generated. Some users have keys implemented in their application scripts to turn on or off the
15
generation of the PATHO file. This will allow the script to run with the PATHO file being specified as long as no dynamic paths are directed to the output file during the dynamic run.
FILEO keywords
Keyword PACKETLOG Subkeyword |F| Description Produces the dynamic equivalent to the static path file. Specified as FILEO PACKETLOG=filename. The file is likely to be very large. It lists every packet, giving the associated volume and route. It also gives the times (in hours since the start of the model period) each packet arrives and departs from each node. The difference between these two times is the time that the packet spent queueing. NOTE: Writing a packet log requires computer resources: processor time, RAM, and disk space. Additional options on the FILEO PACKETLOG statement can reduce the number of packets included in the packet log and thus reduce the required resources. By reducing required resources, you can improve run times, even leading failed runs to succeed. However, with all the information in the file, you can filter displayed packets with Cube graphics. PACKETLOG AFTERITER |I| Iteration number when Cube Avenue begins writing packet log. By default, Cube Avenue writes the packet log for each simulation run (that is, for every iteration), overwriting the same file and ensuring that a valid packet log exists upon completion of a successful Cube Avenue run. However, if you know that Cube Avenue will require at least m iterations, you can set AFTERITER to m-1 to save some run time by not writing the file during the first few iterations. PACKETLOG ARRIVALTIME |RPV| List of time intervals. Packet log only includes packets that arrive at their destinations during the listed time intervals. Specify each interval as an ascending pair of real numbersminutes since the start of the model period.
15

Keyword PACKETLOG Subkeyword DEPARTTIME |RPV| Description List of time intervals. Packet log only includes packets that depart their origins during the listed time intervals. Specify each interval as an ascending pair of real numbersminutes since the start of the model period. List of destination nodes. Packet log only list packets ending at the listed destinations. By default, log includes packets to all destinations. Either BIN or TXT. By default, the PACKETLOG is a text file, which you can display in Cube graphics or postprocess with a user-defined program, such as a matrix record-processing script. Binary format is only suitable for display in Cube graphics, but binary files are about 60% smaller. Flag indicates type of link set specified by SELECTLINK and SELECTGROUP: True Link set defines a route section: the packet log only lists packets that pass every link in the set. False Link set defines a special area: the packet log lists any packet that passes at least one link in the set.
PACKETLOG
DESTINATION
|IV|
PACKETLOG
FORMAT
|S|
PACKETLOG
MUSTMEETALL
|?|
The default value is true. NOTE: If none of these keywords (SELECTLINK, SELECTGROUP, and MUSTMEETALL) is listed, the packet log does not restrict packets based on links traveled. PACKETLOG ORIGIN |IV| List of origin nodes. Packet log only lists packets starting at the listed origins. By default, log includes packets from all origins. List of link groups, defined in previously executed ADDTOGROUP commands. Along with SELECTLINK, defines a set of links that packets must pass through for inclusion in the packet log, based on the value of MUSTMEETALL. List of links. Along with SELECTGROUP, defines a set of links that packets must pass through for inclusion in the packet log, based on value of MUSTMEETALL.
PACKETLOG
SELECTGROUP
|IV|
PACKETLOG
SELECTLINK
|IPV|
15
Output data
Cube Avenue produces additional output data over that produced by the Highway program. The dynamic assignment process implemented in Cube Avenue automatically appends additional results variables onto the NETO output network using an indexing convention similar to that used by the Highway program when performing static assignment. The output NETO network will include all NETI input variables unless explicitly excluded with the EXCLUDE keyword and any additional variables included with the INCLUDE keyword and the following dynamic results variables: TIMESt_1 and TIME_1 SPEEDSt_1 and SPEED_1 VfSt_1, VfSMP_1, VSt_1 and VSMP_1 VITSt_1 QUEUEVSt_1 BLOCKVSt_1
TIMESt_1 and TIME_1
For vehicles arriving on a link during a particular time segment, TIMESt_1 stores the amount of time that the vehicles spent traversing the link segment (averaged over all such vehicles). TIME_1 is similar, but applies to the model period (excluding any warm up segments). The reported values are effectively the sum of two components: the base time calculated from function TC and the queue time resulting from storage and capacity constraints.
SPEEDSt_1 and SPEED_1
This field contains the ratio between distance and the time (as defined above). It does not take turn penalties or junction modelling into account.
15
VfSt_1, VfSMP_1, VSt_1 and VSMP_1
The volume of traffic entering the link, in volume field f, during time segment, t. VSt_1 is the result of applying the V function to V1St_1, V2St_1, etc. At origin zone centroid connectors, the values in the volume fields should correspond to the appropriate matrix row totals. Note there are two very different situations that can result in low volumes entering downstream links (that is, links other than origin zone centroid connectors). If there is very low demand for travel on the link, the flow will be low because the link is empty. At the other extreme, a link that is full of traffic may block further vehicles from entering. The values in the fields labelled with MP instead of a time segment number contain aggregate values for the model period (that is, excluding any warm up segments).
VITSt_1
The number of vehicles on each downstream link at the end of time segment, t, is recorded in this field. The value is found by summing across all packets of vehicles that are flowing or queuing on the link. At origin zone centroid connectors, the field value will be zero, but this is just a convention indicating that data has not been collected for these links.
QUEUEVSt_1
This measures the average number of vehicles queuing on the link during time segment t. Packets of vehicles can be made to queue by either of two mechanisms. First, if the packet tries to move onto a full link, it will be blocked, and it will queue until space becomes available on the next link. Second, links and turns in the network are associated with capacities and capacity bottlenecks may delay packets to ensure that these capacities are not exceeded; the vehicles affected queue while waiting to proceed, but are not recorded as blocked.
15
BLOCKVSt_1
This records the number of vehicles in the queue that will remain in the queue at the end of the simulation. The value will always be less than or equal to the queue variable. Values can only increase in subsequent time segments.
PARAMETERS
Set general parameters MODELPERIOD SEGMENTS VEHPERDIST COMBINE CAPLINKENTRY PKTPTHSIZ MAXPTHPERSEG All the parameters from Highway are also available in Cube Avenue. This page only mentions those parameters that are new or different in Cube Avenue.
PARAMETERS keywords
Keyword CAPLINKENTRY |?| Description <Y> When CAPLINKENTRY=Y (default) the capacity of the link limits how quickly vehicles can enter or leave a link. When CAPLINKENTRY=N, the link capacity only limits how quickly they can leave the link. Note that the primary difference between these two regimes is where the front of a queue occurs. If CAPLINKENTRY is off, then the front queue due to a bottleneck link is at the B node, but if it is on then the front of the queue is at the A node. COMBINE |KS| See COMBINE on page 216 for valid subkeywords and descriptions. Combine type EQU is not valid for Avenue. Since the default value of COMBINE is EQU, COMBINE must always be specified explicitly for AVENUE. For most uses of AVENUE, AVE is a good choice of combine value.
15

Keyword MAXPTHPERSEG |KI| Description Upper bound on the number of path builds executed for a given time segment, iteration, and origin. Defaults to 5. If the number of distinct packet departure times is less than this value, Cube Avenue builds paths for each packeteach packets node list is based on accurately built paths. Otherwise, Cube Avenue executes this many path builds, distributed evenly through the time segment. Each packets node list is based on the nearest path build, in terms of departure time. Though this value can affect the packets route, the packet's simulated departure remains unchanged. MODELPERIOD |S| The value of MODELPERIOD is the length of the model period in minutes. The value of the subsidiary segments clause is a list of time segment durations, also in minutes. The length of the list determines the number of time segments. It is the presence, or absence, of a segments clause that determines whether Cube Voyager runs Highway or Avenue. If the segments list is present, the ILOOP phase must contain a DYNAMICLOAD statement, but need not (and, usually, should not) contain a PATHLOAD statement. If the segments list is absent, the ILOOP phase must contain a PATHLOAD statement but must not contain a DYNAMICLOAD statement. Maximum number of nodes that a packet keeps in RAM. Packets use computer RAM when simulated. Windows imposes a 2 gigabyte limit on the total memory available to a program. To save memory, packets can swap their route information between RAM and temporary disk files.
PKTPTHSIZ
|KI|
15

Keyword SEGMENTS |R*| Description The sum of the values in the segments list must be greater than or equal to the model period. If the sum of the segments is strictly greater than the model period, the extra time forms a kind of warmup period before the true modeling begins. Thus, when the true model period begins, there will already be vehicles driving on roads in the network interior. This is the number of queuing vehicles that can sit in one lane of roadway one distance unit long. The value is only used for the calculation of default storage, so if storage is supplied explicitly in script, or in the input network, the parameter value does not matter. Remember that the implied vehicle spacing must be greater than the average length of a vehicle; storage must include the average gap between the vehicles (vehicles do not queue bumper to bumper). The default value of this parameter is 181.81. If the distance unit is kilometers, then 181.81 vehicles per kilometer gives a vehicle every 5.5 meters. 181.81 vehicles per mile does not yield an appropriate vehicle length. (181.81 vehicles per kilometer is 295.38 vehicles per mile.) The HCM2000 recommends that the following values be used, in the absence of local observed values: Freeway: 120 veh/mi/ln = 75 veh/km/ln Rural Highway: 210 veh/mi/ln = 130 veh/km/ln Arterial: 210 veh/mi/ln = 130 veh/km/ln
VEHPERDIST
|KR|
PATHLOAD
PATHLOAD is the static assignment path builder from the Highway program. See PATHLOAD on page 223 for a description of this command statement and its associated keywords and usage.
15
If a PATHLOAD statement is present in a Cube Avenue run, an extra initial execution of the ILOOP is performed for every iteration. During this execution, all variables take values associated with the model period; PATHLOAD statements are executed but DYNAMICLOAD statements are not executed. During dynamic simulation, the static loads (generated from
PATHLOAD statements) are present (and constant) in every time
segment. The capacity, which is available for packets, is reduced by the static loading. See Combined use of DYNAMICLOAD and static PATHLOAD on page 913 if implementing both command statements in the same run.
PATHLOAD keywords not supported if using static PATHLOAD statements in a dynamic assignment process with DYNAMICLOAD
in effect. ESTMO (ALLJ) PATHO (ALLJ INCLUDECOST NAME PATHOGROUP (FULLPATH))
15
Cube Avenue Theory
Theory
This section discusses the theory behind Cube Avenue: Cube Avenue algorithm Cube Avenue calculations Functions and built-ins
Cube Avenue algorithm

Cube Avenue is a simulation embedded into Cube Voyager highways to allow dynamic traffic assignment. It is designed to enable the prediction of time-varying costs and flows given a timevarying demand for travel. The time modeled is divided into two major periods: a warm-up period, during which the network is filled with traffic, and the model period, over which network statistics are aggregated. Furthermore the time is also divided into smaller time-slices. The demand for travel is assumed to be approximately constant during each time slice, but to vary between time slices. Initially the link and junction times are taken to be the same for all time segments (and are taken to be the values from the input data files). However, once modeling begins, the segment-by-segment times are recalculated independently. So, on the second and subsequent iterations, there will be different estimates of delay for vehicles arriving on a link (or at a stop=line) for each time segment. When dynamic demand is required for some origin-destination pair for some time segment, it is divided into a number of packets of vehicles. Each packet has a start time and a number of vehicles in each volume field. It also has a route for each iteration of assignment. The route is calculated based on the current estimate of each time segments delays and on the estimated time of arrival of the packet at each point on its route.
Cube Avenue Theory
15
On the second and subsequent iterations, the routes from previous iterations are not discarded. Instead the packet volumes travel along each route in proportion to the lambda values for the appropriate iteration. During the ILOOP phase, the path-building algorithm is invoked to calculate routes, and any flows resulting from the movement of packets during previous iterations are removed from the volume fields. Unlike a static load, no flows are assigned to the network at this stage in the process. The ADJUST phase runs the simulation. The simulation is run in continuous time (not segment-by-segment). Packets emerge from their origin zones at their start times and start moving along their routes. As they leave flows behind them in the networks volume fields. Packets must take at least the link time to traverse a link. They must also take at least the turn time to traverse a turn. Each link has a storage capacity. At any time, if a packet wishes to move into a link, it must compare the total volume of packets in transit on the destination link. The packets in transit on a link are the packets traveling on the link and the packets queuing on the link. If the volume of packets in transit exceeds the storage of the destination link, the packet that is trying to move is blocked and remains queued on its current link until space becomes available. Furthermore, each link capacity or turn capacity is represented as a gate. Given a flow, a gate will work out a busy time proportional to the flow and inversely proportional to the capacity. If a packet arrives at a gate and the gate was unoccupied for the corresponding busy time, it can pass straight through (but the gates most recent occupied time becomes now). Otherwise the packet will be delayed until the sum of the busy time with the time at which the gate was most recently occupied. Such packets are queued on the link preceding the gate, but they are not considered to be blocked.
15
Cube Avenue Theory
Cube Avenue calculations

This section describes Cube Avenue calculations: Volumes Times Speeds
Volumes
During the ILOOP phase, the matrix cells in the demand trip matrix are calculated and split into packets. Paths are calculated for each packet and the packets are written to (a temporary file on) disk. On the second and subsequent iterations, the packets are appended to the existing disk file; the paths etc. from previous iterations are retained. At the start of the simulation (that is, the ADJUST phase), all the link volume fields, for all time segments, for the current iteration are cleared to zero. The packets are read from disk and the stored values of flow are multiplied by the appropriate factor. As the simulation progresses, the packets are released onto the network and move along their predetermined paths. As they move from link to link the network volume fields are updated as follows: When a packet departs the origin, the volume for the origin zone centroid connector is updated. When a packet moves from a link to another link, the volume fields for the second link, and for the turn between the two links, are updated. Note that the volume fields are updated for a single time segment; the segment in which the first link is left. When a packet arrives at a destination no volume fields are updated.
An update to the volume fields for a given link or turn in a given time segment proceeds as follows:
Cube Avenue Theory
15
First the packet is examined to determine which of the twenty possible volume fields are present. The values of V1, V2, , V20 are increased by the values stored in the packet. If the volumes are for a link, the function, V, is executed to update the total volume; if the volumes are for a turn, the function, T, is used instead. Note that in the absence of a userdefined function, these functions default to simple summation over all volumes.
At the end of the iteration, the convergence tests decide whether Cube Avenue should continue or stop. If the latter choice is made, the volumes will be written to the output network.
Times
Logically, Cube Avenue maintains two components of link time (called flow time and block time) and one component of turn time for each time segment. The link time is the sum of the flow time and the block time. Prior to any calculations, flow times for all time segments are initialized to the T1 values read from the input network (or set by code in phase LINKREAD). Similarly turn times are initialized from the EstimatedDelay values stored in the intersection file, and from times in the turn penalty file. Any turns where these defaults do not yield a value are initialized to zero. Block times are initialized to zero. The network time fields are calculated as the sum of the blocked and flow times. There are two kinds of turns in Cube Avenue: unmodeled and modeled. Unmodeled turns are those where there is no modeling or where there is a fixed turn penalty. Unmodeled turns never change their time and they do not apply capacity gates to regulate the movement of packets from their preceding link. Modeled turns are those with function turn penalties or with intersection models. In both cases the times are updated for each
15
Cube Avenue Theory
time segment on each iteration but in the former case the capacities neither change from segment to segment nor from iteration to iteration. During path building, the link times are taken from the network time field. The costs are taken by applying the cost function to these fields. Prior to simulation, all blocked times are zeroed. As the simulation progresses the packets move from link to link. Sometimes the packets take longer than the sum (flow time + turn time) to do so. The program tracks in which time segments these excess vehicle minutes occur. Before a segment begins, the queues for each modeled turn are noted. In the first time segment these are taken from the InitialQueue values stored in the intersection file. In subsequent time segments they are found by looking at the packets simulated to be waiting to make the relevant movement. After a segment has been simulated, the blocked time for the segment becomes the average excess minutes per vehicle, incurred during the segment. The flow times are updated by running the appropriate TC functions for the segment volumes. The turn times are updated by running the intersection model with the previously noted initial queues and the turning volumes obtained from the simulation. The time fields in the network for the segment are now updated to be the sum of blocked and flow times. Any user code for the ADJUST phase is executed.
Speeds
The link speeds are not used during the path building or simulation. They are calculated immediately prior to network output as Speed = 60 Distance / Time. Note that the speeds do not take turn times into account.
Cube Avenue Theory
15
Functions and built-ins

All the script variables that would normally be available in a highway assignment script are still available. However there are some new script variables, and the interpretation of some other script variables is modified. This section describes only the new or changed variables: Storage TimeSegment SegmentStart Period Time, Cost, and Vol
Storage
There is a new script variable, STORAGE, that may be set during the LINKREAD phase. Refer to the description in LINKREAD phase on page 902.
TimeSegment
This is the time segment number. User script may not assign values to this variable. It takes the value zero during a static assignment, or during the static phase of a combined assignment. It takes values 1, 2, 3, etc. as the dynamic time segments are being processed.
SegmentStart
This is the time in minutes between the start of the modeled period and the start of the time segment currently being processed. User script may not assign values to this variable. It takes the value zero during a static assignment, or during the static phase of a combined assignment. Note that this is a signed value, with negative numbers indicating the current segment is a warm-up segment and non-negative values indicating that this segment is within the model period.
15
Cube Avenue Theory
Period
This is the duration of the period currently being processed in minutes. User script may not assign values to this variable. It is the duration of the model period during a static assignment, or during the static phase of a combined assignment. It is the duration of the current time segment when time segments are being processed.
Time, Cost, and Vol

Internally, these link arrays become two-dimensional, with one dimension referring to the time segment and the other referring to the link number. In the output network, the values referring to different time segments will be given different names (see Output data on page 918). When script is being executed, it will be in the context of the model period, or of the current time segment as appropriate. However, some care needs to be taken when calculations involve both ordinary link arrays and these time-segment vectors of link arrays. For example, a common way of handling costs for multi user class assignment is to calculate costs into a work variable:
LW.TRUCK_COST=DISTANCE+TIME LW.CAR_COST=DISTANCE/2+TIME*1.5
In a Cube Avenue dynamic assignment, this will result in both link variables having the cost values applicable to the last time segment. (Although the values for each time segment in turn will be assigned to the link variables, they are not vectored, and the costs associated with one time segment overwrite those associated with the previous one.) To correctly calculate costs by user class, more work variables must be used:
IF (TIMESEGMENT=1) LW.TRUCK_COST1=DISTANCE+TIME LW.CAR_COST1=DISTANCE/2+TIME*1.5 ELSE LW.TRUCK_COST2=DISTANCE+TIME LW.CAR_COST2=DISTANCE/2+TIME*1.5
Cube Avenue Theory
15
The new variables can be used in a DYNAMICLOAD statement. For example:

DYNAMICLOAD PATH=LW.TRUCK_COST__TS__
15
Cube Avenue Examples
Examples
This section contains examples of Cube Avenue scripts: Program Parameters LINKREAD Simplifying LINKREAD Centroids ILOOP ADJUST Enhancing ADJUST Packet logs Tuning parameters Reducing segment and volume lists
Program
Call Cube Avenue just as you call other Cube Voyager programs, with RUN PGM=.... Place all statements and keywords that control the run in a RUN... ENDRUN block. You can specify an output print file after a PGM=AVENUE PRNFILE= statement.
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" ENDRUN
15
Parameters
This example adds some parameters to the Cube Avenue script: MAXITERS specifies the maximum number of iterations. COMBINE specifies the method of combining iterations together. In this case, the method is AVE, successive averages. AVE is the recommended method for equilibrium dynamic assignment. MODELPERIOD specifies the duration of the modeled time period, in minutes. SEGMENTS specifies a list of durations for each modeled time segment. In this example, the sum of the segments exceeds the model period. Cube Avenue treats the excess time as a warm up prior to the model period. In addition, this example seeds the random number generator. Seeding the random number generator makes results repeatable between multiple runs of the same assignment. The internal random number generator randomly draws a departure time for each packet departing in a given interval.
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE="{SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" PARAMETERS MAXITERS=10, COMBINE=AVE, MODELPERIOD=90, SEGMENTS=30,30,30,30, ;30 min warm-up X=RANDSEED(165) ; seed random numbers ENDRUN
15
LINKREAD
Just as in the Highway model, Cube Avenue reads the input network and uses either user expressions or default rules to initialize important link variables. This example shows: DISTANCE Used with other variables to calculate default T0 and STORAGE values. SPEED Used with DISTANCE to calculate default T0 values. T0 Free-flow link travel time. STORAGE Number of vehicles that can physically fit on a link (should not be zero). LINKCLASS Function index number for calculating congested time and cost. C Flow rate capacity, in vehicles per model period. You might need to convert from hourly capacities.
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" PARAMETERS MAXITERS=10, COMBINE=AVE, MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up PHASE=LINKREAD DISTANCE=LI.FEET/5280 ;converting to miles SPEED=LI.MPH T0=60*DISTANCE/SPEED ;time in minutes C=LI.LANES*LI.LNCAP*1.5 ;scale to model period STORAGE = DISTANCE*LI.LANES*LI.VEHPERLNMI IF (STORAGE=0) STORAGE=9999999 LINKCLASS = LI.FTYPE ENDPHASE ENDRUN
15
Simplifying LINKREAD
Not every link variable needs an explicit expression. For example, if the input network has values for LANES and DISTANCE, then Cube Avenue can compute STORAGE using the formula VehPerDist * LANES * DISTANCE. (The default value for VehPerDist is 181.81.) Citilabs recommends using different STORAGE values for arterials and freeways. In Cube, you can define a network variable named STORAGE. Input network fields named STORAGE, CAPACITY, and TIME override any default calculations for these variables. Because the networks input capacity is specified in vehicles per hour, the example uses the CAPFAC parameter to scale the value to the model period duration.
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up PHASE=LINKREAD ;Automatically use STORAGE from network, which was ;calculated in Cube editor window based on HCM: ; freeway storage = 120 vehicles/ln-mi ; arterial storage = 220 vehicles/ln-mi ;Also use TIME from network for T0 ; as well as input CAPACITY for C ;Accordingly DISTANCE and SPEED are not used ENDPHASE ENDRUN
Centroids
Centroid connectors connect zones to the network; they do not represent physical road features. Therefore, in Cube Avenue, you must define these links to have infinite (that is, very large) capacity, infinite storage, and zero travel time.
15
Because links with zero capacity and storage can cause problems in dynamic assignment, you must find such links and give them large capacity and storage values, also. This example assigns all centroid connectors LINKCLASS=2 using the ZONES variable.
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up PHASE=LINKREAD ;Automatically use STORAGE from network, which was ;calculated in Cube network editor based on HCM: ; freeway storage = 120 vehicles/ln-mi ; arterial storage = 220 vehicles/ln-mi ;Also use TIME from network for T0 as well ; and input CAPACITY for C IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 ENDPHASE ENDRUN
ILOOP
During each main iteration, Cube Avenue loops through all the input zones, creates packets for assignment, and builds dynamic (time-varying) paths. The statement DYNAMICLOAD PATH=COST tells Cube Avenue to build dynamic paths using congested travel costs by time segment. By default, this is the same as TIME, which is initially the free-flow link travel time.
15
The input matrix for this example contains three tables, one for each half hour of the model period. The statement PACKETSIZE=10 groups the input vehicle trips into packets with a target size of ten vehicles. The tables listed in VOL[1] specify the matrix to use for each time segment, including warm-up.
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up PHASE=LINKREAD IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 PHASE=ILOOP DYNAMICLOAD PATH=COST, PACKETSIZE=10, VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3 ENDPHASE ENDRUN
ADJUST
When a script calls one or more DYNAMICLOAD statements, Cube Avenue simulates the movement of packets through the network during the ADJUST phase. After simulating packets and recording link volumes, Cube Avenue uses delay functions to calculate congested travel times by segment. By default, Cube Avenue adjusts all links using the standard BPR formula: TC[1] = T0 *(1 + 0.15* (V/C) ^ 4)
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
15
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up PHASE=LINKREAD IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 PHASE=ILOOP DYNAMICLOAD PATH=COST, PACKETSIZE=10, VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3 PHASE=ADJUST ENDPHASE ENDRUN
Enhancing ADJUST
The standard BPR formula, which does not degrade link performance significantly until volumes exceed capacity, is inadequate for Cube Avenue, where assignment volumes never exceed capacity. This example implements a performance function from Chapter 30 of the Highway Capacity Manual 2000. In this example: LI.DO represents free-flow signal delay. LI.J represents a calibration parameter coded directly into the network, based on facility type. LINKCLASS=2 represents centroid connectors, which should not degrade performance.
The example introduces a custom COST function that incorporates vehicle operating costs and tolls into route-choice behavior. The units of COST are monetary.
; Do not change filenames or add or remove FILEI/FILEO ; statements using an editor. Use Application Manager. RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET"
15
FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up PHASE=LINKREAD IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 PHASE=ILOOP DYNAMICLOAD PATH=COST, PACKETSIZE=10, VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3 PHASE=ADJUST Function TC[1]=T0+LI.D0+(0.25*30)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/30^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL Function COST[2]=TIME ENDPHASE ENDRUN
Packet logs
With the FILEO PACKETLOG statement, Cube Avenue generates an output log file containing simulated packet movements. This example modifies the output file with several options: ORIGIN / DESTINATION Lists origins and destinations of output packets DEPARTTIME / ARRIVALTIME Lists departure and arrival times (in seconds) of output packets SELECTLINK Lists links that output packets must pass through SELECTGROUP List link groups that output packets must pass through MUSTMEETALL Set to F, specifying that links specify an area; hence output packets must pass through at least one of the specified links, but not necessarily all of the links
15
AFTERITER Delays writing the packet log until the specified iteration FORMAT Specifies that the output be written to a binary log file rather than default text format
RUN PGM=AVENUE PRNFILE="{SCENARIO_DIR}\OUT.PRN" FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.LOG", ORIGIN=1-10, DESTINATION=1-10, DEPARTTIME=1800-3600, ARRIVALTIME=1800-3600, SELECTLINK=(L=101-1903*), SELECTGROUP=3, MUSTMEETALL=F, AFTERITER=9, FORMAT=BIN PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=30,30,30,30 ;30 min warm-up PHASE=LINKREAD IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 IF (LI.TOLL>0) AddToGroup=3 PHASE=ILOOP DYNAMICLOAD PATH=COST, PACKETSIZE=10, VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3 PHASE=ADJUST Function TC[1]=T0+LI.D0+(0.25*30)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/30^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL Function COST[2]=TIME ENDPHASE ENDRUN
Tuning parameters
Cube Avenue generates packet flows that depart intermittently throughout the model period, and builds time-varying paths for these flows. This computation-intensive process can result in slow run times.
15
You can use the parameter MaxPthPerSeg to limit the number of paths that Cube Avenue builds for each origin-destination pair in each time segment. This example has a segment duration of 30 minutes. A MaxPthPerSeg value of 10 forces packets within threeminute intervals to use the same path. This reduces the number of built paths and improves computation time, but can introduce model granularity.
RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.LOG", ORIGIN=1-10, DESTINATION=1-10, DEPARTTIME=1800-3600, ARRIVALTIME=1800-3600, SELECTLINK=(L=101-1903*), SELECTGROUP=3, MUSTMEETALL=F, AFTERITER=9, FORMAT=BIN PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=30,30,30,30, MaxPthPerSeg=10 PHASE=LINKREAD IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 IF (LI.TOLL>0) AddToGroup=3 PHASE=ILOOP DYNAMICLOAD PATH=COST, PACKETSIZE=10, VOL[1]=mi.1.1,mi.1.1,mi.1.2,mi.1.3 PHASE=ADJUST Function TC[1]=T0+LI.D0+(0.25*30)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/30^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL Function COST[2]=TIME ENDPHASE ENDRUN
Reducing segment and volume lists

When using many time segments, segment and volume lists can become long and unwieldy.
15
The SEGMENTS parameter supports the repetition (*) operator. If the time segments are of equal duration, you can specify them using the syntax:
SEGMENTS=N*DUR
where: N is the number of modeled time segments DUR is the duration of each segment
In addition, when the _TS_ notation is used within MW brackets for VOL, Cube Avenue substitutes the expression with an MW vector that contains the number of time segments (replacing _TS_ with the time segments index).
RUN PGM=AVENUE PRNFILE={SCENARIO_DIR}\OUT.PRN FILEO NETO = "{SCENARIO_DIR}\OUTPUT.NET" FILEI NETI = "{SCENARIO_DIR}\INPUT.NET" FILEI MATI[1] = "{SCENARIO_DIR}\INPUT.MAT" FILEO PACKETLOG = "{SCENARIO_DIR}\PACKET.LOG", ORIGIN=1-10, DESTINATION=1-10, DEPARTTIME=1800-3600, ARRIVALTIME=1800-3600, SELECTLINK=(L=101-1903*), SELECTGROUP=3, MUSTMEETALL=F, AFTERITER=9, FORMAT=BIN PARAMETERS MAXITERS=10, COMBINE=AVE, CAPFAC=1.5, MODELPERIOD=90, SEGMENTS=4*30, MaxPthPerSeg=10 PHASE=LINKREAD IF (A<=ZONES||B<=ZONES) LINKCLASS=2 IF (LINKCLASS==2||STORAGE==0) STORAGE=9999999 IF (LINKCLASS==2||C==0) C=9999999 IF (LINKCLASS==2) T0=0 IF (LI.TOLL>0) AddToGroup=3 PHASE=ILOOP MW[1]=mi.1.1 MW[2]=mi.1.1,MW[3]=mi.1.2,MW[4]=mi.1.3 DYNAMICLOAD PATH=COST, PACKETSIZE=10, VOL[1]=MW[__TS__] PHASE=ADJUST Function TC[1]=T0+LI.D0+(0.25*15)*((V/C-1)+ SQRT((V/C-1)^2+((16*LI.J*V/C*DIST^2)/15^2))) Function TC[2]=T0 Function COST[1]=TIME*{VOT}+DISTANCE*{VOC}+LI.TOLL Function COST[2]=TIME
15
ENDPHASE ENDRUN
15
Index
Symbols %...% 21, 80 * command 83 ** command 83 :label GOTO keyword, Highway 208 GOTO keyword, Pilot 91 GOTO keyword, Public Transport 716 @...@ 21, 80 _BSEARCH, Matrix variable 440 _COMPARE, Network variable 332 _SKIPTOI, Highway variable 135 _ZONES, Network variable 332 A A COMP keyword, Generation 568 Highway array 136 Network variable 332 REPORT keyword, Generation 573 SETPA keyword, Distribution 557 SETPA keyword, Fratar 125 A2P BALANCE keyword, Generation 567 AAD convergence testing calculation 167 Highway variable 137 PARAMETERS keyword, Highway 215 using in BALANCE variable 168 AADAVE function for BALANCE 170 Highway function 139 AADCHANGE function for BALANCE 169 Highway function 138
AADCHANGEAVE function for BALANCE 170 Highway function 139 AADCHANGEMAX function for BALANCE 170 Highway function 139 AADCHANGEMIN function for BALANCE 170 Highway function 139 AADCUTOFF Highway variable 137 using in BALANCE variable 168 AADMAX function for BALANCE 170 Highway function 139 AADMIN function for BALANCE 170 Highway function 139 ABORT Cube Cluster impact 886 Distribution control statement 437 Fratar control statement 437 Generation control statement 437 Highway control statement 175 Matrix control statement 437 Network control statement 335 Public Transport control statement 633 ABS 32 absolute logit model 407 AC REPORT keyword, Generation 573 ACCESS LINE NODES subkeyword, Public Transport 724
Index A
access legs generating 842 multiple, eliminating 788 report 749 restricting to modes 647 ACCESS_C LINE NODES subkeyword, Public Transport 724 ACCESSLEGS REREPORT keyword, Public Transport 749 ACCESSLINK GENERATE keyword, Public Transport 708 ACCUMULATE FILEO STOP2STOPO subkeyword, Public Transport 701 ACOMP REPORT keyword, Fratar 123 REPORT keywords, Distribution 556 ACTION NT keyword, Public Transport 735 ACTUALGREEN JUNCTION keyword, overview 265 JUNCTION keyword, signals 282 ADDTOGROUP SETGROUP keyword, Highway 244 ADJUST phase Cube Avenue 907 Highway program 159 stack for, Highway 251 ADJUSTLINK CROWDMODEL keyword, Public Transport 643 ADJUSTWAIT CROWDMODEL keyword, Public Transport 643 AFTERITER FILEO PACKETLOG subkeyword, Cube Avenue 916 afterpgm NEWPAGE keyword, Pilot 95 aftersys NEWPAGE keyword, Pilot 95 AGF SETPA keyword, Fratar 125 algorithm all-or-nothing path building 737 Cube Avenue 924 public transport transfers 738 ALIGN PLOTTER FOOTER subkeyword, Network 366 PLOTTER HEADER subkeyword, Network 367 ALL REPORT keyword, Network 376
ALLJ PATHLOAD ESTMO subkeyword, Highway 225 PATHLOAD PATHO subkeyword, Highway 231 ALLSTOPS LINE keyword, Public Transport 721 all-way-stop-controlled intersections 302 ALPHA FACTORS keyword, Public Transport 645 ALTERNATIVES CHOICE keyword, cost-based model 445 CHOICE keyword, utility-based model 448 XCHOICE keyword, cost-based model 452 XCHOICE keyword, utility-based model 455 ALTNAME PARAMETERS keyword, TPP2UB 865 ANSWER PROMPT keyword, Pilot 100 AONMAXFERS FACTORS keyword, Public Transport 645 AONMETHOD PARAMETERS keyword, Public Transport 737 APPEND FILEO NETO keyword, Highway 200 FILEO PRINTO keyword, Highway 201 FILEO PRINTO subkeyword, Matrix 504 FILEO PRINTO subkeyword, Network 355 PRINT FILE subkeyword, general 63 APPLY CROWDMODEL keyword, Public Transport 643 APPROACH JUNCTION keyword, common description 269 JUNCTION keyword, overview 265 APPROACH1 JUNCTION keyword, common description 271 JUNCTION keyword, overview 265 APPROACHWIDTH JUNCTION keyword, empirical roundabout 305 JUNCTION keyword, overview 265 ARCCOS 34 ARCSIN 34 ARCTAN 34 ARRAY Cube Cluster impact 886 Distribution control statement 437 Fratar control statement 437 Generation control statement 437 Highway control statement 175 Matrix control statement 437 Network control statement 335 SORT keyword, general 72
Index B
arrays creating and populating 490 Cube Cluster and 886 field names in, Matrix 474 finding keys in, Matrix 439 Highway 136 initializing, Highway 150 internal, reporting in Highway 243 link work, denoting 742 link, Cube Avenue 930 Matrix, DBI 474 Matrix, RECI 483 populating with LOOKUP, example 60 production and attraction 115 production and attraction, generating 564 production and attraction, number of 571 production and attraction, referencing 549 route-enumeration components 652 setting to same value, Highway 243 sorting 72 sorting, Highway 245 sorting, Network 377 specifying with keywords 25 string valued 487 user, declaring in Highway 175 user, declaring in Matrix 437 user, declaring in Network 335 user-defined, sorting in Matrix 532 zonal data, reporting in Matrix 530 ARRAYSUM COMP function, Matrix 464 Matrix built-in function 395 ARRIVALTIME FILEO PACKETLOG subkeyword, Cube Avenue 916 ATTACHMENTS SENDMAIL keyword, Pilot 107 AUTOARRAY FILEI DBI subkeyword, Matrix 474 AUTOCOEF PARAMETERS keyword, TPP2UB 865 AVE FILEI ZDATI subkeyword, Highway 193 FILEI ZDATI subkeyword, Matrix 487 MERGE keyword, Network 359 AVERAGELANEWIDTH JUNCTION keyword, geometric signals 285 JUNCTION keyword, overview 265
AVEX0 FILEI ZDATI subkeyword, Highway 193 FILEI ZDATI subkeyword, Matrix 487 MERGE keyword, Network 359 B B Highway array 136 Network variable 332 print format code, numeric items 66 print format code, string items 68 BALANCE Generation control statement 567 Highway variable 137 BALANCE variable functions for 169 setting, convergence script 167 variables for 168 BANDWIDTH PLOTTER keyword, Network 365 BASE1 PRINTROW keyword, general 69 BASECOSTS CHOICE keyword, cost-based model 445 BASECOSTSMW XCHOICE keyword, cost-based model 452 BASEDATA FILEI TURNPENI subkeyword, Public Transport 681 BASEDEMAND CHOICE keyword, cost-based model 445 CHOICE keyword, utility-based model 448 BASEDEMANDMW XCHOICE keyword, cost-based model 452 XCHOICE keyword, utility-based model 455 BASEGDBNETWORK FILEO LINEO subkeyword, Public Transport 685 FILEO NTLEGO subkeyword, Public Transport 693 BASEMW FREQUENCY keyword, Matrix 511 BASEUTILS CHOICE keyword, utility-based model 448 BASEUTILSMW XCHOICE keyword, utility-based model 456 beforepgm NEWPAGE keyword, Pilot 95 beforesys NEWPAGE keyword, Pilot 95 BEG FILEI LINKI VAR subkeyword, Network 350
Index C
BESTJRNY skim function, Public Transport 601 skim function, summary 604 BESTPATHONLY FACTORS keyword, Public Transport 646 BIN FILEO TURNVOLO file format 203 boarding penalty example 855 mode specific 646 perceived, skim function 600 reducing during transfers 774 boarding point first, default wait curve 758 first, wait curve used 756 transit leg definition 783 wait time at 773 boardings example 855 line output, including in 685 link output, including in 689 number, skim function 602 passenger loading report, including in 748 bottleneck modeling as generalized cost 773 modeling with crowding 834 queuing location, Cube Avenue 920 trips affected, skim function 603 BRDINGS skim function, Public Transport 602 skim function, summary 604 BRDPEN FACTORS keyword, Public Transport 646 skim function, Public Transport 600 skim function, summary 604 BREAK Distribution control statement 439 Fratar control statement 439 Generation control statement 439 Highway control statement 176 Matrix control statement 439 Network control statement 336 Pilot control statement 83 Public Transport control statement 634 BSEARCH Matrix control statement 439 BUSBLOCKAGE JUNCTION keyword, geometric signals 286 JUNCTION keyword, overview 265
BYCLASS FILEO LINKO subkeyword, Public Transport 687 C C DYNAMIC keyword, Cube Avenue 909 Highway variable 135 Highway variable, example value 142 print format code, numeric items 66 print format code, string items 68 set value, outside LINKREAD phase 216 setting, example in Cube Avenue 934 value computed, Highway LINKREAD phase 152 variable, Cube Avenue 904 CALL Distribution control statement 440 Fratar control statement 440 Generation control statement 440 Matrix control statement 440 CANSHARELEFT JUNCTION keyword, overview 265 JUNCTION keyword, saturation-flow priority junctions 325 JUNCTION keyword, signals 280 CANSHARERIGHT JUNCTION keyword, overview 265 JUNCTION keyword, saturation-flow priority junction 326 JUNCTION keyword, signals 281 CAPACITY REPORT keyword, Highway 241 REPORT keyword, Network 376 SPDCAP keyword, Highway 245 SPDCAP keyword, Network 378 CAPACITYFOR COMP function, Network 338 Highway function 137 Network function 333 CAPACITYINTERCEPT JUNCTION keyword, empirical roundabout 306 JUNCTION keyword, overview 266 CAPACITYSLOPE JUNCTION keyword, empirical roundabout 307 JUNCTION keyword, overview 266 CAPFAC applying in Cube Avenue 904 PARAMETERS keyword, Highway 216 scaling input capacity with, Cube Avenue 935 CAPLINKENTRY PARAMETERS keyword, Cube Avenue 920
Index C
CC SENDMAIL keyword, Pilot 107 CENTRALBUSINESSDISTRICT JUNCTION keyword, geometric signals 287 JUNCTION keyword, overview 266 CENTRALRESERVATIONWIDTH JUNCTION keyword, geometric priority junctions 320 JUNCTION keyword, overview 266 CFORM FILEO PAO subkeyword, Generation 569 FILEO RECO subkeyword, Matrix 504 PRINT keyword, general 62 REPORT MARGINREC subkeyword, Matrix 528 CHANGEATLASTSTOP PARAMETERS keyword, Public Transport 738 CHECKRETURNCODE WAIT4FILES keyword, Cube Cluster 892 CHOICE Matrix control statement 444 Matrix control statement, replacing 405 XCHOICE, differences with 458 choice modeling absolute logit model 407 alternative alighting, Public Transport 808 destination choice model 428 general considerations 433 incremental logit model 415 introduction 405 mode-and-destination-choice model 430 route decisions, Public Transport 803 transfer points, Public Transport 809 transit choices, Public Transport 806 walk choice, Public Transport 803 CHOICECUT FACTORS keyword, Public Transport 647 CIRCULAR LINE keyword, Public Transport 721 CLEARERROR Pilot control statement 84 CLEARFILEO DOWNLOAD keyword, Pilot 89 Cluster.exe 895 CmpNumRetNum 32 CNT FILEI ZDATI subkeyword, Highway 194 FILEI ZDATI subkeyword, Matrix 487 MERGE keyword, Network 359 CODE CLEARERROR keyword, Pilot 84 example 98
COEFF CHOICE DESTSPLIT subkeyword 446 CHOICE SPLIT subkeyword 447 XCHOICE DESTSPLIT subkeyword 453 XCHOICE SPLIT subkeyword 454 COL CROSSTAB keyword, Network 342 COMBINE FILEI LINKI subkeyword, Network 348 FILEO MATO keyword, Highway 198 PARAMETERS keyword, Cube Avenue 920 PARAMETERS keyword, Highway 216 command prompt, starting Cube Voyager from 14 comments 22 COMMPATH DISTRIBUTEINTRASTEP keyword, Cube Cluster 894 DISTRIBUTEMULTISTEP keyword, Cube Cluster 891 COMP control statement, general 43 CROSSTAB keyword, Network 342 Distribution control statement 460 Fratar control statement 460 Generation control statement 567 Highway control statement 177 Matrix control statement 460 Network control statement 337 Pilot control statement 85 Public Transport control statement 636 COMPARE Network control statement 338 COMPCOST skim function, Public Transport 602 skim function, summary 604 composite cost skim function 602 confidence levels matrix estimation 836 output links 698 CONFLICTINGBIKE JUNCTION keyword, geometric signals 286 CONFVAR FILEO ESTMICPO subkeyword, Highway 197 FILEO SCREENLINEO subkeyword, Public Transport 698 connectors access, restricting modes 647 egress, restricting modes 647 CONSOLE control statement, general 44
Index C
CONSOLIDATE PARAMETERS keyword, Highway 218 PATHLOAD keyword, Highway 225 CONTINUE Distribution control statement 469 Fratar control statement 469 Generation control statement 469 Highway control statement 183 Matrix control statement 469 Network control statement 341 Pilot control statement 87 Public Transport control statement 639 CONTROL SETPA keyword, Fratar 125 control blocks 23 control fields 24 control statements comments 22 control blocks 23 Cube Cluster, summary 877 DATAPREP phase, Public Transport 625 Distribution program 552 fields 24 Generation program 566 Highway program 174 Highway program, types 133 keywords 25 LINKREAD phase, Public Transport 624 MATI phase, Public Transport 627 MATO phase, Public Transport 630 Matrix program, list of 436 Matrix program, types 396 Network program 334 NODEREAD phase, Public Transport 623 null blocks 22 overview 41 Public Transport program 632 SELECTIJ phase, Public Transport 629 stacks, Highway program 250 subkeywords 26 tokens 21 CONVERGE phase Cube Avenue 908 Highway program 166 not specifying, Highway program 163 stack for, Highway program 251
convergence crowding model, Public Transport 835 Cube Avenue 927 default testing, Highway 163 Distribution model 545 Fratar distribution 114 Fratar distribution, iteration control 118 intersection modeling and 263 multiple purposes and 547 output matrices and 122 output matrices, writing 554 phase supporting, Highway 166 phases and, Highway 132 target totals, adjusting for 125 COPY Pilot control statement 87 COS 34 COST GENERATE keyword, Public Transport 709 Highway array 136 NT keyword, Public Transport 735 value set, Highway LINKREAD phase 153 COSTDEC FILEO PATHO keyword, Highway 200 COSTS CHOICE keyword, cost-based model 445 COSTSMW XCHOICE keyword, cost-based model 453 COUNTVAR FILEO ESTMICPO subkeyword, Highway 197 CRITICALGAP JUNCTION keyword, gap-acceptance roundabout 316 JUNCTION keyword, overview 266 JUNCTION keyword, two-way stop 296 CROSSING2ENTRY JUNCTION keyword, empirical roundabout 308 JUNCTION keyword, geometric priority junctions 321 CROSSING2EXIT JUNCTION keyword, empirical roundabout 309 JUNCTION keyword, geometric priority junctions 321 CROSSINGLENGTH GEOMETRIC priority junctions 321 JUNCTION keyword, empirical roundabout 309 CROSSTAB Network control statement 341
Index D
crowd modeling boarding probability, updating 834 control statement defining 643 in-vehicle-time effects 774 link travel times, updating 834 link-travel-time adjustment 830 outputs, setting 687 process, Public Transport 618 report supplements 768 theory 830 wait-time adjustment 833 wait-time effects 773 CROWDCRVDEF Public Transport control statement 641 CROWDCURVE LINE keyword, Public Transport 722 VEHICLETYPE keyword, Public Transport 755 crowding actual wait time, skim function 597 perceived wait time. skim function 597 seat occupancy value 723 theory 830 CROWDMODEL Public Transport control statement 643 CRUSHCAP LINE keyword, Public Transport 722 VEHICLETYPE keyword, Public Transport 756 CSV PATHLOAD TRACE subkeyword, Highway 234 PRINT keyword, general 62 CTLFILE RUN keyword, Pilot 103 Cube Analyst intercept file, producing for 197 MATO file, producing for 501 Public Transport demand matrices 836 Public Transport intercept file, producing for 684 Public Transport screenline file, producing for 698 screenline data file, producing for 197 Cube Avenue algorithm 924 calculations 926 control statements 909 examples 932 introduction 900 limitation of Cube Cluster 885 phases 902 script variables 929 Cube Base starting Cube Voyager with 9
Cube Cluster control statements 890 control statements, summary 877 executable for local machine 895 file permissions 878 introduction 872 utility functions 897 working with 877 Cube Voyager Distribution program 541 Fratar distribution process 113 general syntax 19 Generation program 563 Highway program 129 intersection modeling 261 Matrix program 391 Network program 329 Pilot program 75 Public Transport program 579 utilities 861 CURVE CROWDCRVDEF keyword, Public Transport 642 WAITCRVDEF keyword, Public Transport 757 CWDCOSTP skim function, Public Transport 599 skim function, summary 604 CWDWAITA skim function, Public Transport 597 skim function, summary 604 CWDWAITP skim function, Public Transport 597 skim function, summary 604 CYCLETIME JUNCTION keyword, overview 266 JUNCTION keyword, signals 281 D D print format code, numeric items 66 print format code, string items 68 DATAPREP Public Transport phase 625 DBF FILEO PAO subkeyword, Generation 569 FILEO TURNVOLO file format 203 DBF files dumping link and node records to 387 fields, writing to with Matrix RECO 505 Generation program output 569 linking to LOOKUPI file 52
Index D
DBF files (continued) matrix data input files, Matrix 478 Matrix program input, DBI 473 Matrix program input, RECI 482 stop-to-stop analysis, Public Transport 700 turning volume file, Highway 203 writing to, Matrix 533 DBI FILEI keyword, Matrix 473 DCOSTS CHOICE keyword, cost-based model 445 DCOSTSMW XCHOICE keyword, cost-based model 453 DEADLINKS REPORT keyword, Network 376 DEC FILEO MATO keyword, Highway 199 FILEO MATO subkeyword, Matrix 498 FILEO MATO subkeyword, Public Transport 691 FILEO NETO keyword 200 FILEO NETO subkeyword, Public Transport 693 FILEO SUBAREAMATO keyword, Highway 201 FILEO TURNVOLO keyword, Highway 202 PATHLOAD PATH subkeyword, Highway 231 REPORT LINES subkeyword, Public Transport 747 REPORT LINEVOLS subkeyword, Public Transport 748 REPORT ZDAT keyword, Highway 243 REPORT ZDAT subkeyword, Matrix 530 DEFAULT FILEI ZDATI subkeyword, Highway 194 FILEI ZDATI subkeyword, Matrix 487 DEFAULTCONF FILEO ESTMICPO subkeyword, Highway 198 DEFCONF FILEO SCREENLINEO subkeyword, Public Transport 698 DELACCESSMODE FACTORS keyword, Public Transport 647 DELAY LINE NODES subkeyword, Public Transport 724 DELAY_C LINE NODES subkeyword, Public Transport 725 DELAYEQUATION JUNCTION keyword, geometric signals 287 DELDISTRIBFILES WAIT4FILES keyword, Cube Cluster 892 DELEGRESSMODE FACTORS keyword, Public Transport 647 DELETE Network control statement 345
DELETESTR 34 DELIMITER FILEI DBI subkeyword, Matrix 475 FILEI RECI subkeyword, Matrix 483 FILEO LINKO subkeyword, Network 352 FILEO MATO subkeyword, Matrix 500 FILEO TURNVOLO keyword, Highway 202 DELMODE FACTORS keyword, Public Transport 648 DEMAND CHOICE keyword, cost-based model 445 CHOICE keyword, utility-based model 448 XCHOICE keyword, cost-based model 453 XCHOICE keyword, utility-based model 456 demand matrices Public Transport, estimating 836 pure mode-choice model, cost-based 453 pure mode-choice, utility-based 456 specifying name, cost-based model 452 specifying name, utility-based model 455 DEMANDMW XCHOICE keyword, cost-based model 453 XCHOICE keyword, utility-based model 456 DEPARTTIME FILEO PACKETLOG subkeyword, Cube Avenue 917 design concepts 2 DESTINATION FILEO PACKETLOG subkeyword, Cube Avenue 917 destination zones, Matrix 514 destination-choice model assigning zones, cost-based (CHOICE) 446 assigning zones, cost-based (XCHOICE) 453 assigning zones, utility-based (CHOICE) 448 assigning zones, utility-based (XCHOICE) 456 combined with mode-choice 430 demand, specifying 458 description 428 example code 538 using gravity model 544 DESTSPLIT CHOICE keyword, cost-based model 446 CHOICE keyword, utility-based model 448 XCHOICE keyword, cost-based model 453 XCHOICE keyword, utility-based model 456 DETAILS FILEI LINKI subkeyword, Network 348 DEVICE PLOTTER keyword, Network 365
Index E
DIRECTION GENERATE keyword, Public Transport 709 DIRECTLINK GENERATE keyword, Public Transport 709 DIST Highway array 136 NT keyword, Public Transport 735 skim function, Public Transport 602 skim function, summary 604 value, Highway LINKREAD phase 153 DISTANCE Highway variable 135 script variable, Cube Avenue 903 setting, example in Cube Avenue 934 value computed, Highway LINKREAD phase 151 DISTRIBUTE Cube Cluster control statement 890 DISTRIBUTEINTRASTEP Cube Cluster control statement 893 DISTRIBUTEMULTISTEP Cube Cluster control statement 890 Distribution program control statements 552 convergence 545 example 559, 559, 560 examples 559 friction factors 550 introduction 542 overview 542 DLL CALL keyword, Matrix 441 DOWNLOAD Pilot control statement 88 DRAWA PLOT keyword, Network 364 DRAWLINK PLOT keyword, Network 364 DUPLICATES REPORT keyword, Network 376 DUPSTR character function 34 DUTILS CHOICE keyword, utility-based model 449 DUTILSMW XCHOICE keyword, utility-based model 456 DWELL LINE NODES subkeyword, Public Transport 725 DWELL_C LINE NODES subkeyword, Public Transport 725 DYNAMIC Cube Avenue control statement 909
DYNAMICLOAD Cube Avenue control statement 910 example, ADJUST phase 937 using in ILOOP 936 using with PATHLOAD 913 using work variables in 931 E egress legs definition 783 eliminating in multirouting models 789 example report, TRACEI 765 generating 842 report 750 EGRESSLEGS REREPORT keyword, Public Transport 750 ELSE control statement, general 48 Highway control statement 209 Network control statement 356 Pilot control statement 92 ELSEIF control statement, general 48 Highway control statement 209 Network control statement 356 Pilot control statement 92 EMME/2 data bank file MATI, specifying as input with 478 MATO, writing with 497 output matrix names 503 RECO, writing with 504 retrieving matrix data, example 495 retrieving zonal vector matrix, example 495 scalar and vector matrix names 506 specifying matrix written 503 variable names written 505 writing with FILEO MATO, example 507 writing with FILEO RECO, example 508 ZDATI, specifiying with 486 empirical roundabout difference with gap-acceptance roundabout 277 example 314 keywords 305 model overview 304 ENABLE JUNCTION keyword, common description 271 ENDCOPY Pilot control statement 87 ENDDISTRIBUTEMULTISTEP Cube Cluster control statement 891
Index E
ENDIF control statement, general 48 Highway control statement 209 Network control statement 356 Pilot control statement 92 Public Transport control statement 716 ENDJLOOP Highway control statement 210 Matrix control statement 514 Public Transport control statement 717 ENDLINKLOOP Highway control statement 212 Public Transport control statement 731 ENDLOOP Highway control statement 213 Network control statement 356 Pilot control statement 93 Public Transport control statement 731 ENDPHASE PROCESS keyword, Generation 572 PROCESS keyword, Highway 240 ENDPROCESS Generation control statement 571 Highway control statement 239 Network control statement 374 ENDRUN Pilot control statement 102 ENTRYANGLE JUNCTION keyword, empirical roundabout 309 JUNCTION keyword, overview 266 ENTRYGATE FILEI TOLLMATI subkeyword, Highway 190 ENTRYRADIUS JUNCTION keyword, empirical roundabout 311 JUNCTION keyword, overview 266 ENTRYWIDTH JUNCTION keyword, empirical roundabout 312 JUNCTION keyword, overview 266 enumerated routes destination zones 695 destination zones reported, output file 696 file containing 695 maximum transfers in 653 origin zones 695 origin zones reported, output file 696 report 761 user-class specific 745 using FACTORS statements for 590 EQUATION 161
EQUITURNCOSTFAC PARAMETERS keyword, Highway 218 errors clearing 84 factor file, maximum number 671 listing in run print file, Matrix 484 maximum in data records, Network 361 maximum in RECI records, Matrix 484 responding to 95 transit line 741 ESTIMATEDDELAY JUNCTION keyword, common description 272 JUNCTION keyword, overview 266 ESTMDATO FILEO keyword, Highway 197 impact on Cube Avenue 915 impact on Cube Cluster 885 ESTMICPO FILEO keyword, Highway 197 impact on Cube Avenue 915 impact on Cube Cluster 885 ESTMO impact on Cube Avenue 923 PATHLOAD keyword, Highway 225 setting to true 204 evaluated routes destination zones printed, input file 678 destination zones printed, output file 697 destination zones reported, input file 677 destination zones reported, output file 696 origin zones printed, input file 678 origin zones printed, output file 697 origin zones reported, input file 677 origin zones reported, output file 696 quality issues 844 report 762 EXCESSDEMAND skim function, Public Transport 603 skim function, summary 604 EXCESSPROP skim function, Public Transport 603 skim function, summary 604 EXCLUDE CHOICE DESTSPLIT subkeyword, cost-based model 446 CHOICE DESTSPLIT subkeyword, utility-based model 448 COMP MW subkeyword, Highway 178 COMP MW subkeyword, Matrix 461 COMP MW subkeyword, Public Transport 637
Index F
EXCLUDE (continued) FILEI LINKI subkeyword, Network 348 FILEO LINKO subkeyword, Network 352 FILEO NETO keyword, Highway 200 FILEO NETO subkeyword, Network 354 JLOOP keyword, Highway 211 SETPA keyword, Distribution 557 SETPA keyword, Fratar 125 XCHOICE DESTSPLIT subkeyword, cost-based model 453 XCHOICE DESTSPLIT subkeyword, utility-based model 456 EXCLUDEGROUP PATHLOAD keyword, Highway 225 EXCLUDEJ PATHLOAD keyword, Highway 225 EXCLUDELINK GENERATE keyword, Public Transport 709 EXCLUDERECI FILEO RECO subkeyword, Matrix 504 EXCLUSIVELANES JUNCTION keyword, overview 266 JUNCTION keyword, priority junction 326 JUNCTION keyword, signals 282 EXIT Cube Cluster impact 886 Distribution control statement 470 Fratar control statement 470 Generation control statement 470 Highway control statement 184 Matrix control statement 470 Network control statement 345 Pilot control statement 89 Public Transport control statement 644 EXITGATE FILEI TOLLMATI subkeyword, Highway 190 EXITLANES JUNCTION keyword, geometric signals 287 EXITONLY JUNCTION keyword, common description 272 JUNCTION keyword, overview 266 EXP 32 expressions COMP statements 43 COMP, Matrix program 463 computing values with FUNCTION 206 LOOKUP statement 51 numeric, overview 30 selection, overview 36 variables in 39
EXTENDREPORT PARAMETERS keyword, Public Transport 738 EXTENDRUNTIMES PARAMETERS keyword, Public Transport 739 EXTRACTCOST GENERATE keyword, Public Transport 710 EXTRAXFERS1 FACTORS keyword, Public Transport 648 EXTRAXFERS2 FACTORS keyword, Public Transport 648 F factor file input, names of 671 maximum errors 671 validating fare data in 671 FACTORI FILEI keyword, Public Transport 671 FACTORS network development processing 588 Public Transport control statement 644 route enumeration, controlling with 590 FAIL LOOKUP keyword, general 52 FARE PARAMETERS keyword, Public Transport 739 fare matrices input file containing 672 name, defining 665 report 766 fare model assigning 649 defining 663 input file for, specifying 672 purpose 775 FAREA skim function, Public Transport 600 skim function, summary 604 FAREFROMFS FARESYSTEM keyword, Public Transport 665 FAREI FILEI keyword, Public Transport 672 FAREMATI FILEI keyword, Public Transport 672 FAREMATRIX FARESYSTEM keyword, Public Transport 665 FAREMSG PARAMETERS keyword, Public Transport 740
Index F
FAREP skim function, Public Transport 600 skim function, summary 604 fares boarding and transfer costs 823 determining trip cost from 823 examples 828 generalized cost component 772 input file, control statements 672 input file, matrices 672 input file, missing data 740 line, specifying for 722 matrix reports 766 methods for defining structure 821 modeling in Public Transport 818830 models for, overview 775 multiple systems in network 823 overview 818 route evaluation, including cost in 739 skim functions for 600 system describing 663670 validating in factor file 671 zones for 825 FARESYSTEM FACTORS keyword, Public Transport 649 LINE keyword, Public Transport 722 Public Transport control statement 663 FARETABLE FARESYSTEM keyword, Public Transport 666 FAREZONES FARESYSTEM keyword, Public Transport 668 FFACTORS GRAVITY keyword, Distribution 553 FIELDS FILEI DBI subkeyword, Matrix 476 FILEI MATI subkeyword, Matrix 479 FILEI RECI subkeyword, Matrix 484 FILEO MATO subkeyword, Matrix 500 FILEO RECO subkeyword, Matrix 505 FILE COPY keyword, Pilot 88 LOOKUP keyword, general 52 PLOTTER keyword, network 366 PRINT keyword, general 62 READ keyword, general 71 RENUMBER keyword, Matrix 524 REPORT MARGINREC subkeyword, Matrix 528 REPORT VDTSPD keyword, Highway 242
FILEI control statement, general 44 Distribution control statement 470 Fratar control statement 470 Generation control statement 470 Highway control statement 184 Matrix control statement 470 Network control statement 346 Pilot control statement 89 PROCESS PHASE subkeyword, Network 374 Public Transport control statement 670 REPORT keyword, Network 376 SYNCHIMP control statement 866 TPP2UB control statement 864 UB2TPP control statement 862 FILEO control statement, general 45 Cube Avenue control statement 915 Distribution control statement 496 DOWNLOAD keyword, Pilot 89 example, Matrix 506 Fratar control statement 496 Generation control statement 568 Highway control statement 196 Matrix control statement 496 Network control statement 352 Pilot control statement 90 Public Transport control statement 684 REPORT keyword, Network 376 SYNCHIMP control statement 867 TPP2UB control statement 864 UB2TPP control statement 863 FILES keyword RENUMBER keyword, Matrix 525 WAIT4FILES keyword, Cube Cluster 893 FilesExist function 897 FILET Distribution control statement 509 Fratar control statement 509 Highway control statement 205 Matrix control statement 509 FILL PLOTTER BANDWIDTH subkeyword, Network 365 FILLMW Distribution control statement 510 Fratar control statement 510 Highway control statement 206 Matrix control statement 510
Index F
FIRST FILEI ZDATI subkeyword, Highway 194 FILEI ZDATI subkeyword, Matrix 487 MERGE keyword, Network 359 FirstReadyNode function 897 FIRSTZONE Cube Cluster impact 887 Matrix built-in variable 394 FLARELENGTH JUNCTION keyword, empirical roundabout 313 JUNCTION keyword, overview 266 FLARESTORAGE JUNCTION keyword, two-way stop 296 FMCAPACITY LINE keyword, Public Transport 722 FMOFF LINE NODES subkeyword, Public Transport 725 FMON LINE NODES subkeyword, Public Transport 725 FMVOL LINE NODES subkeyword, Public Transport 725 NT keyword, Public Transport 735 FMVOLS FILEO LINKO subkeyword, Public Transport 687 FMVOLT NT keyword, Public Transport 735 FOLLOWUPTIME JUNCTION keyword, gap-acceptance roundabout 316 JUNCTION keyword, overview 266 JUNCTION keyword, two-way stop 296 FONT PLOTTER FOOTER subkeyword, Network 366 PLOTTER HEADER subkeyword, Network 367 PLOTTER LEGEND subkeyword, Network 368 PLOTTER POSTLINKVAR subkeyword, Network 370 PLOTTER POSTNODEVAR subkeyword, Network 371 FOOTER PLOTTER keyword, Network 366 FORM CROSSTAB COMP subkeyword, Network 342 CROSSTAB VAR subkeyword, Network 343 FILEO LINKO subkeyword, Network 352 FILEO PAO subkeyword, Generation 570 FILEO RECO subkeyword, Matrix 506 PRINT keyword, general 63 PRINTROW keyword, general 69 REPORT MARGINREC subkeyword, Matrix 528
FORMAT character function 34 FILEO LINKO subkeyword, Network 353 FILEO MATO keyword, Highway 199 FILEO MATO subkeyword, Matrix 501 FILEO MATO subkeyword, Public Transport 692 FILEO NETO subkeyword, Network 354 FILEO PACKETLOG subkeyword, Cube Avenue 917 FILEO SUBAREAMATO keyword, Highway 201 FILEO TURNVOLO keyword, Highway 203 FOURLANEMAJOR JUNCTION keyword, overview 266 JUNCTION keyword, two-way stop 297 FRACTIONS PARAMETERS COMBINE keyword, Highway 217 Fratar distribution control statements 121 controlling target totals 116 convergence 118 examples 127 multiple purposes 119 overview 114 specifying target values 115 FREEFLOWCAP JUNCTION keyword, geometric priority junctions 321 JUNCTION keyword, overview 266 JUNCTION keyword, two-way stop 297 FREQBYMODE FACTORS keyword, Public Transport 650 FREQUENCY Distribution control statement 511 Fratar control statement 511 impact on Cube Cluster 886 Matrix control statement 511 friction factors curves in gravity model 543 distribution process, use in 550 example, typical process 58 expression, specifying 553 FROM FACTORS XFERCONST subkeyword, Public Transport 658 FACTORS XFERFACTOR subkeyword, Public Transport 659 FACTORS XFERPEN subkeyword, Public Transport 660 SENDMAIL keyword, Pilot 107 FROMNODE GENERATE keyword, Public Transport 710 FULLPATH PATHLOAD PATHO subkeyword, Highway 231
Index G
FUNCTION Highway control statement 206 functions character, general 34 COMP expression 464 convergence, Highway program 138 Cube Avenue 929 Highway program 136 lookup 36 matrix 180183 Matrix program, built-in 395 numeric, general 32 trig, general 33 utility, supporting Cube Cluster 897 G GAP convergence testing calculation 166 Highway variable 137 PARAMETERS keyword, Highway 218 using in BALANCE variable 168 gap-acceptance roundabout difference with empirical roundabout 277 example 317, 317 keyword placement 275 keywords for 316 overview 304 GAPAVE function for BALANCE 169 Highway function 138 GAPCHANGE function for BALANCE 169 Highway function 138 GAPCHANGEAVE function for BALANCE 169 Highway function 139 GAPCHANGEMAX function for BALANCE 169 Highway function 139 GAPCHANGEMIN function for BALANCE 169 Highway function 138 GAPCUTOFF Highway variable 137 using in BALANCE variable 168 GAPMAX function for BALANCE 169 Highway function 138
GAPMIN function for BALANCE 169 Highway function 138 generalized cost boarding penalty component 774 calculation, route enumeration 775 converting from monetary fares 658 fare component 775 fares, including in 739 in-vehicle time component 773 logit choice models 408 route enumeration and evaluation, specifying 644 route evaluation, using for 799 theory, Public Transport 771 transfer penalty compoent 774 using to affect choices 433 wait-time component 773 walk-time component 772 GENERATE avoiding poor quality routing 842 DATAPREP phase 625 example preparing public transport network 849 example, two user class 858 keywords to avoid excessive legs 845 network development 588 nontransit network, developing with 841 Public Transport control statement 706 writing to nontransit legs table 714 Generation program control statements 566 examples 574 introduction to 564 GEOMETRIC JUNCTION keyword, priority junction 319 geometric priority junctions example 324 keywords 320 GEOMETRYSOURCE Network variable 332 GLOBAL control statement, general 46 GOTO Distribution control statement 512 Fratar control statement 512 Generation control statement 512 Highway control statement 208 Matrix control statement 512, 512 Pilot control statement 91 Public Transport control statement 715
Index H
GRADE JUNCTION keyword, geometric signals 288 JUNCTION keyword, overview 266 JUNCTION keyword, two-way stop 298 GRAVITY Distribution control statement 552 gravity model alternative to complete formulation 544 control statement for 552 description 542 example 559, 560 example, singly constrained 537 implementation guidelines 543 GROUPEDMODES FILEO STOP2STOPO subkeyword, Public Transport 701 GROUPS FILEO STOP2STOPO subkeyword, Public Transport 702 H HDWAYPERIOD PARAMETERS keyword, Public Transport 740 HEADER PLOTTER keyword, Network 367 HEADERONLY PARAMETERS keyword, UB2TPP 863 headway computing wait time from 773 line in reverse direction, specifying 723 line, specifying 723 route enumeration, use for 776 selecting 740 wait curve, default 759 wait curve, rules for 759 wait curve, specifying in 757 HEADWAY. LINE keyword, Public Transport 723 HEADWAY_R LINE keyword, Public Transport 723 hierarchical logit model 421 highway assignment introduction 130 iteration volume combinations 163 iterations, maximum 219 multiple iteration 156 setting up scripts 141 using PATHLOAD statement 154
Highway program ADJUST phase 159 arrays 136 assignment, getting started 141 control statement overview 133 control statements 174 CONVERGE phase 166 convergence functions 138 convergence variables 137 Cube Cluster, invoking 893 examples 252260 functions 136 ILOOP phase 154 intersection modeling 261 introduction 130 linking to Public Transport program 838 LINKREAD phase 150 logic, overview 248 SETUP phase 150 variables 135 zonal loop, select link 156 zonal loop, selected zone loading 157 zonal loop, subarea trip extraction 157 HOV facilities, assigning trips to 145 I I FILEI ROUTEI subkeyword, Public Transport 676 FILEO ROUTEO subkeyword, Public Transport 695 Highway variable 135 Matrix built-in variable 394 REPORT VDTSPD keyword, Highway 241 IBOARDFARE FARESYSTEM keyword, Public Transport 668 ID, general control statement 46 IDP commands that disable 885 description 879 using when summarizing zonal values 887 IF control statement, general 48 Cube Cluster impact 886 Distribution control statement 513 Fratar control statement 513 Generation control statement 513 Highway control statement 209 Matrix control statement 513 Network control statement 356 Pilot control statement 92 Public Transport control statement 716
Index I
ILOOP phase computing volumes, Cube Avenue 926 controlling loop processing 212 Cube Avenue 906 Cube Cluster impacts 886 Generation program 564 Highway program 154 jumping to zone 135 stack for, Highway 251 INCLUDE CHOICE DESTSPLIT subkeyword, cost-based model 446 CHOICE DESTSPLIT subkeyword, utility-based model 448 COMP MW subkeyword, Highway 178 COMP MW subkeyword, Matrix 461 COMP MW subkeyword, Public Transport 638 FILEO LINKO subkeyword, Network 353 FILEO NETO keyword, Highway 200 FILEO NETO subkeyword, Network 354 JLOOP keyword, Highway 210 SETPA keyword, Fratar 125 SETPA keywords, Distribution 557 XCHOICE DESTSPLIT subkeyword, cost-based model 453 XCHOICE DESTSPLIT subkeyword, utility-based model 456 INCLUDE0 FILEO TURNVOLO keyword, Highway 204 INCLUDECOST PATHLOAD PATHO subkeyword, Highway 231 INCLUDEJ PATHLOAD keyword, Highway 225 INCLUDELINK GENERATE keyword, Public Transport 710 incremental logit model 415 initial wait time actual, skim function 597 perceived, skim function 598 INITIALQUEUE JUNCTION keyword, common description 273 JUNCTION keyword, overview 266 INLIST function example 399 numeric function 33 INPUT REPORT keyword, Network 376
input files See also FILEI phase-based processing, Network 379 Public Transport program, overview 837 specifying 44 INPUT phase Network program 380 variable associations 382 inputs loading process, Public Transport 606 network development, Public Transport 589 route enumeration, Public Transport 591 route evaluation, Public Transport 592 select-link process, Public Transport 607 skimming, Public Transport 594 INSCRIBEDDIAMETER JUNCTION keyword, empirical roundabout 314 JUNCTION keyword, overview 266 INSERTSTR 34 installation 8 INT 33 intercept data modes considered 740 screenline file that produces 678 intercept file configuring link use 837 matrix estimation, requirement for 836 output file name, Highway 197 output file name, Public Transport 684 INTERCEPTO FILEO keyword, Public Transit 684 INTERPOLATE FARESYSTEM FARETABLE subkeyword, Public Transport 667 LOOKUP keyword, general 52 intersection modeling control statements 265 description 263 introduction 262 invoking at nodes 188 keywords 269 limitations 263 nodes invoked at, specifying 188 purpose 262 results file, specifying 198
Index J
intersections control statements 265 keywords, common 269 priority junctions 318 roundabouts 303 signal controlled 279 stop, all-way 302 two-way stop-controlled 294 two-way yield-controlled 318 INTRA Matrix keyword 397 intrastep distributed processing. See IDP INTRAZONAL Matrix keyword 397 intrazonal cells 397 in-vehicle time best-path modeling calculation 776 crowding adjustment 830 increasing to reflect crowding 641 theory 773 ITERATION Highway variable 135 Matrix built-in variable 394 iteration control 545 ITERATIONS CROWDMODEL keyword, Public Transport 643 REPORT keyword, Distribution 556 iterations ADJUST phase 160 assignment and capacity restraint 142 combining MATO matrices from 219 CONVERGE phase 166173 converge phase functions, Highway 138 convergence variables 137 convergence, Distribution 545 Cube Avenue parameters 933 highway assignment, maximum 219 maximum, Distribution 555 maximum, Fratar 122 number, crowd-modeling runs 643 processing, Cube Avenue 924 processing, Fratar distribution 118 reported, Distribution 556 testing for convergence 164, 166 writing output matrices, Distribution 554 writing packet log, Cube Avenue 916 writing path output file 201
ITERS FILEO PATHO keyword, Highway 201 IWAITA skim function, Public Transport 597 skim function, summary 604 IWAITCURVE FACTORS keyword, Public Transport 651 IWAITP skim function, Public Transport 598 skim function, summary 604 J J FILEI ROUTEI subkeyword, Public Transport 677 FILEO ROUTEO subkeyword, Public Transport 695 Highway variable 135 JLOOP keyword, Highway 210 JLOOP keyword, Matrix 516 JLOOP keyword, Public Transport 718 Matrix built-in variable 394 PRINTROW keyword, general 70 REPORT VDTSPD keyword, Highway 241 JLOOP Distribution control statement 514 Fratar control statement 514 Generation control statement 514 Highway control statement 210 Matrix control statement 514 Public Transport control statement 717 JOINTODBI FILEI DBI subkeyword, Matrix 476 JOINTOFIELDS FILEI DBI subkeyword, Matrix 477 JUNCDATAO FILEO keyword, SYNCHIMP utility 867 JUNCTION junction file control statement 265 junction file control statements 265 input, specifying 188 output, specifying 198 JUNCTIONI FILEI keyword, Highway 188 JUNCTIONO FILEO keyword, Highway 198
Index K
K keywords See also individual keyword names description 25 documentation descriptions 28 intersection modeling 269 subkeywords 26 values 28 KFACTORS GRAVITY keyword, Distribution 553 L L print format code, numeric items 67 print format code, string items 68 LAMBDA, Highway variable 135 LAMBDAA FACTORS keyword, Public Transport 651 LAMBDASEARCH PARAMETERS COMBINE keyword, Highway 218 LAMBDAW FACTORS keyword, Public Transit 652 LANEADJUST JUNCTION keyword, overview 266 JUNCTION keyword, signals 282 LANES SPDCAP keyword, Highway 245 SPDCAP keyword, Network 378 LANESI FILEI keyword, SYNCHIMP utility 866 LAST FILEI ZDATI subkeyword, Highway 194 FILEI ZDATI subkeyword, Matrix 487 MERGE keyword, Network 359 LASTITERATION, Highway variable 135 LASTZONE Cube Cluster impact 887 Matrix built-in variable 394 LAYOUTI FILEI keyword, SYNCHIMP utility 866 LEFTDRIVE FILEO NETO subkeyword, Network 355 PARAMETERS keyword, Network 361 LEFTSTR 35 LEG NT keyword, Public Transport 734 LEGEND PLOTTER keyword, Network 367 LEN FILEI LINKI VAR subkeyword, Network 350
LI.CAPCLASS input field, Cube Avenue 903 LI.LANES input field, Cube Avenue 904 LI.name Highway array 136 LI.SPDCLASS input field, Cube Avenue 903 LINE PLOTTER LEGEND subkeyword, Network 368 Public Transport control statement 720 REREPORT keyword, Public Transport 750 LINEI FILEI keyword, Public Transport 673 LINELINELEG REREPORT keyword, Public Transport 751 LINEO FILEO keyword, Public Transport 684 LINES FILEO LINKO subkeyword, Public Transport 687 REPORT keyword, Public Transport 747 report produced, example 767 REREPORT keyword, Public Transport 750 lines. See transit lines LINEVOLS REPORT keyword, Public Transport 748 LINEZONLEG1 REREPORT keyword, Public Transport 751 LINEZONLEG2 REREPORT keyword, Public Transport 751 LINKCLASS Highway variable 135 setting, example in Cube Avenue 934 value computed, Highway LINKREAD phase 151 variable, Cube Avenue 903 LINKI FILEI keyword, Network 347 LINKID#MW PATHLOAD LINKIDARRAY subkeyword, Highway 226 LINKIDARRAY PATHLOAD keyword, Highway 225 LINKIDCNTMW PATHLOAD LINKIDARRAY subkeyword, Highway 225 LINKIDLASTUSE PATHLOAD LINKIDARRAY subkeyword, Highway 226 LINKIDMW PATHLOAD LINKIDARRAY subkeyword, Highway 226 LINKLOOP Highway control statement 212 Public Transport control statement 731
Index L
LINKMERGE phase controlling plotting 363 Network program 381 plotting 384 PROCESS block rules 375 records merging data 358 variable referencing 382 LINKNO, Highway variable 135 LINKNUM, Highway function 137 LINKO FILEO keyword, Network 352 FILEO keyword, Public Transport 686 FILEO keyword, SYNCHIMP utility 867 LINKOFFSET PLOTTER keyword, Network 368 LINKPOST PLOT keyword, Network 364 LINKREAD phase Cube Avenue 902 Highway program 150 Public Transport program 624 stack for, Highway 251 links arrays supporting 136 centroid connectors 935 computing walk and transit times 851 confidence level value 698 Cube Avenue packets, specifying 917 demand using, selecting 609 drawing, Network 363 drawn, characteristics of 365 dumping to DBF files, example 387 duplicate, eliminating 358 group codes for, setting 244 listing in print file, example 387 loops for processing, Public Transport 731 merging records from multiple files, example 387 nontransit leg, maximum 709 one-way, nontransit legs 711 output file, specifying in Public Transport 686 path, loading 223 restricted use by mode 699 speed on, non-input network 729 transit line time. base 742 travel demand on, identifying 607 travel time computation, Public Transport 730 variables supporting 135 walk 772
links file defining output 686 lines data, including in 687 summing output by user class 687 LIST COMPARE keyword, Network 339 FILEI FACTORI subkeyword, Public Transport 671 FILEI FAREI subkeyword, Public Transport 672 FILEI LINEI subkeyword, Public Transport 673 FILEI SYSTEMI subkeyword, Public Transport 679 FILEI TURNPENI subkeyword, Highway 191 FILEI TURNPENI subkeyword, Public Transport 681 FILEO PAO subkeyword, Generation 570 FILEO STOP2STOPO subkeyword, Public Transport 702 GENERATE keyword, details about 714 GENERATE keyword, Public Transport 710 LOOKUP keyword, general 52 PRINT keyword, general 64 REPORT MARGINREC subkeyword, Matrix 529 LIST_ERRS PARAMETERS keyword, Network 361 LISTERRS FILEI RECI subkeyword, Matrix 484 LN 33 LOADDISTFAC LINE keyword, Public Transport 723 VEHICLETYPE keyword, Public Transport 756 loading analyses mode transfers 618 operator transfers 618 overview 617 stop-to-stop movements 618 loading process overview, Public Transport 605 theory, Public Transport 815 trip matrix into public transport network 856 LOG control statement, standard 49 impact on Cube Cluster 886 numeric function, general syntax 33 logit choice model 408 logit models absolute 407 applying to parts of matrices 434 choices 433 destination choice 428 hierarchical 421 incremental 415 incremental, practical considerations 435
Index M
logit models (continued) mode and destination choice 430 scale parameters 435 LONGNAME FARESYSTEM keyword, Public Transport 668 LINE keyword, Public Transport 723 MODE keyword, Public Transport 733 OPERATOR keyword, Public Transport 737 VEHICLETYPE keyword, Public Transport 756 WAITCRVDEF keyword, Public Transport 757 LONGNAMECROSDCRVDEF keyword, Public Transport 642 LOOKUP control statement, general 51 LOOKUP NAME subkeyword, general 53 LOOKUPI FILEI keyword, Highway 189 FILEI keyword, Matrix 478 FILEI keyword, Network 351 FILEI keyword, Pilot 90 LOOKUP keyword, general 53 LOOP Distribution control statement 517 Fratar control statement 517 Generation control statement 517 Highway control statement 213 Matrix control statement 517 Network control statement 356 Pilot control statement 93 Public Transport control statement 731 loops general variable, Matrix 517 general variable, Public Transport 731 general, Highway 213 input zones, Cube Avenue 936 jumping to end 341 link records, Highway 212 link records, Public Transport 731 matrices, Matrix 514 matrix column cells, Public Transport 717 matrix columns, Highway 210 terminating, Public Transport 644 using to control run order 76 LOS GRAVITY keyword, Distribution 553 LOSRANGE GRAVITY keyword, Distribution 553
LOWCNT COMP function, Matrix 464 Highway function 137 Highway variable 135 Matrix built-in variable 394 matrix function, Highway 181 LOWEST COMP function, Matrix 465 Highway function 137 Matrix built-in function 395 matrix function, Highway 181 LTRIM, character function 35 LW.name, Highway array 136 M MAJORROADWIDTH JUNCTION keyword, geometric priority junctions 322 JUNCTION keyword, overview 267 MAPSCALE PARAMETERS keyword, Public Transport 740 PLOTTER keyword, Network 368 MAPWINDOW PLOTTER keyword, Network 369 MARGINREC impact on Cube Cluster 886 REPORT keyword, Matrix 528 MARGINS impact on Cube Cluster 886 PLOTTER keyword, Network 369 REPORT keyword, Matrix 529 MATI FILEI keyword, Highway 189 FILEI keyword, Matrix 478 FILEI keyword, Public Transport 674 FILEI keyword, TPP2UB 864 FILEI keyword, UB2TPP 862 Public Transport phase 626 MATO FILEO keyword, Highway 198 FILEO keyword, Matrix 497 FILEO keyword, Public Transport 690 FILEO keyword, TPP2UB 864 FILEO keyword, UB2TPP 863 Public Transport phase 630 MATOADJUST PARAMETERS keyword, Highway 219 MATOEVERY PARAMETERS keyword, Distribution 554 PARAMETERS keyword, Fratar 122
Index M
matrices applying part to logit model 434 functions, Highway 180183 intrazonal cells, working with 397 variables, Highway 179 Matrix program control statements, list of 436 control statements, types 396 Cube Cluster, invoking 893 examples 534 functions, built-in 395 functions, COMP statement 464 introduction 392 variables, built-in 394 MATSTAT REPORT keyword, Matrix 529 MATVAL COMP function, matrix 465 Matrix built-in function 395 MATVALCACHE PARAMETERS keyword, Matrix 519 MAX FILEI ZDATI subkeyword, Highway 194 FILEI ZDATI subkeyword, Matrix 487 MERGE keyword, Network 359 numeric function 33 MAX_IP_ERRS PARAMETERS keyword, Network 361 MAXCOMPD FACTORS keyword, Public Transport 652 MAXCOST GENERATE keyword, Public Transport 711 MAXERRS FILEI FACTORI subkeyword, Public Transport 671 FILEI LINEI subkeyword, Public Transport 673 FILEI RECI subkeyword, Matrix 484 MAXFERS FACTORS keyword, Public Transport 653 MAXFIELDS FILEO MATO subkeyword, Matrix 502 MAXITERS convergence testing calculation 167 PARAMETERS keyword, Distribution 555 PARAMETERS keyword, Fratar 122 PARAMETERS keyword, Highway 219 MAXLINKDELAY FILEI TURNPENI subkeyword, Public Transport 682 MAXMSG PATHLOAD SUBAREAMAT subkeyword, Highway 233
MAXMW PARAMETERS keyword, Highway 219 PARAMETERS keyword, Matrix 519 PARAMETERS keyword, Public Transport 740 MAXNTLEGS GENERATE keyword, Public Transport 711 MAXPERLINE PRINTROW keyword, general 70 MAXPTHPERSEG PARAMETERS keyword, Cube Avenue 921 MAXPURPS PARAMETERS keyword, Fratar 123 MAXRECS FILEI DBI subkeyword, Matrix 477 FILEI RECI subkeyword, Matrix 484 MAXRMSE PARAMETERS keyword, Distribution 555 PARAMETERS keyword, Fratar 123 MAXSCAN FILEI RECI subkeyword, Matrix 485 MAXSTRING PARAMETERS keyword, Highway 219 PARAMETERS keyword, Matrix 519 PARAMETERS keyword, Pilot 99 MDP 881 MERGE Network control statement 358 REPORT keyword, Network 376 MESSAGE CONSOLE subkeyword 44 SENDMAIL keyword, Pilot 107 message 770 740 messages displaying 44 excessive travel time 738 zonal timing, Highway 222 zonal timing, Matrix 520 zonal timing, Public Transport 744 zone pairs without valid routes 741 MEUSESNT FILEO SCREENLINEO subkeyword, Public Transport 699 PARAMETERS keyword, Public Transport 740 MIN FILEI LINKI VAR subkeyword, Network 350 FILEI ZDATI subkeyword, Highway 194 FILEI ZDATI subkeyword, Matrix 487 MERGE keyword, Network 359 numeric function 33
Index M
MINCOST GENERATE keyword, Public Transport 711 MINGROUPSIZE DISTRIBUTEINTRASTEP keyword, Cube Cluster 894 minimum system requirements 6 MINIMUMCAPACITY JUNCTION keyword, common description 273 JUNCTION keyword, overview 267 minimum-cost routes finding, theory on 794 generation process 662 maximum transfers permitted 645 MISSINGLINK FILEI TURNPENI subkeyword, Highway 192 FILEI TURNPENI subkeyword, Public Transport 682 MISSINGZI RENUMBER keyword, Matrix 525 MISSINGZO RENUMBER keyword, Matrix 525 MO FILEO MATO keyword, Highway 199 FILEO MATO subkeyword, Matrix 503 FILEO MATO subkeyword, Public Transport 691 MODE FACTORS FARESYSTEM subkeyword, Public Transport 649 LINE keyword, Public Transport 723 NT keyword, Public Transport 736 Public Transport control statement 733 mode-and-destination-choice model 430 model period crowd model, Public Transport 643 Cube Avenue 921 duration, junction file 188 Highway program 219 modeling approaches, Public Transport 777 MODELPERIOD PARAMETERS keyword, Cube Avenue 921 PARAMETERS keyword, Highway 219 modes access connectors, prohibiting 647 banning transfers between 660 choosing between 406 choosing with destination 430 data file 679 defining 733 deleting for user class 648 demand using, selecting 612
modes (continued) egress connectors, prohibiting 647 fare model 649 intercept data and 740 limiting selected routes to 781 link use restricted 699 logit choice model 407 must-use, enumerating routes with 798 required in transit route 654 required, extra cost allowed 653 stop-to-stop movement data collected 703 transfer penalty 774 transfers between, report 769 turn-penalty free 682 MODES subkeyword FILEO STOP2STOPO, Public Transport 703 MOVEMENT JUNCTION keyword, common description 274 JUNCTION keyword, overview 267 MSG ABORT keyword, Highway 175 ABORT keyword, Matrix 437 ABORT keyword, Network 335 ABORT keyword, Public Transport 633 MULTISTEP DISTRIBUTE keyword, Cube Cluster 890 multistep distributed processing. See MDP MUMEXTRACOST FACTORS keyword, Public Transport 653 MUSTMEETALL FILEO PACKETLOG subkeyword, Cube Avenue 917 must-use mode enumerating routes with, theory 798 evaluating routes with 800 specifying 654 MUSTUSEMODE FACTORS keyword, Public Transport 654 MW COMP keyword, Highway 177 COMP keyword, Matrix 460 COMP keyword, Public Transport 637 FILLMW keyword, Matrix 510 function description 31 Highway array 136 Matrix built-in variable 394 PATHLOAD keyword, Highway 226 PRINTROW keyword, general 70 SETPA keyword, Fratar 126
Index N
N N FILEI JUNCTIONI subkeyword, Highway 188 Network variable 332 REREPORT keyword, Public Transport 752 TURNS keyword, Highway 247 NAME CROWDCRVDEF keyword, Public Transport 642 FARESYSTEM keyword, Public Transport 668 FILEI DBI subkeyword, Matrix 478 FILEI RECI subkeyword, Matrix 485 FILEI ZDATI subkeyword, Highway 194 FILEO ESTMDATO keyword, Highway 197 FILEO MATO keyword, Highway 199 FILEO MATO subkeyword, Matrix 503 FILEO MATO subkeyword, Public Transport 691 FILEO RECO subkeyword, Matrix 506 FILEO SUBAREAMATO keyword, Highway 201 LINE keyword, Public Transport 721 LOOKUP keyword, general 53 MODE keyword, Public Transport 733 OPERATOR keyword, Public Transport 737 PATHLOAD PATHO subkeyword, Highway 231 VEHICLETYPE keyword, Public Transport 756 WAITCRVDEF keyword, Public Transport 757 NAMES FILEO PAO subkeyword, Generation 570 FILEO TURNVOLO keyword, Highway 204 naming conventions string variables, Network 338 variables, general 39 NEAREST LOOKUP keyword, general 53 NET FILEO LINEO subkeyword, Public Transport 685 FILEO NTLEGO subkeyword, Public Transport 694 NETI FILEI keyword, Highway 189 FILEI keyword, Public Transport 675 NETIENTRY FILEI TOLLMATI subkeyword, Highway 190 NETIEXIT FILEI TOLLMATI subkeyword, Highway 190 NETITOLLROAD FILEI TOLLMATI subkeyword, Highway 191 NETO FILEO keyword, Highway 200 FILEO keyword, Network 353 FILEO keyword, Public Transport 692 NETWORK Example 1 387
NETWORK Introduction 330 Network program control statements 334 examples 387 INPUT phase 380 LINKMERGE phase 381 NODEMERGE phase 380 output variables 383 phases 379 plotting 384 referencing variables 381 SUMMARY phase 381 theory 379 networks building from inline data records 388 comparing records in 338 deleting data records 345 development example, Public Transport 849 development process overview, Public Transport 588 highest node number 362 highway, input file 189 highway, introduction 130 Highway, output file name 200 highway, processing 330 highway, revising speed and capacity 245 input data files 346 output file 352 plotting 384, 384 public transport, developing 625 public transport, generating nontransit legs 706 public transport, input file 675 Public Transport, output file 692 public transport, preparing 582 simplification of, Public Transport 782 speeds, Public Transport 839 times, Public Transport 839 zones, number in 362 NEWPAGE Pilot control statement 95 NHB BALANCE keyword, Distribution 567 NNTIME LINE NODES subkeyword, Public Transport 726 NOACCESS PATHLOAD MW subkeyword, Highway 228 NODE JUNCTION keyword, common description 275 JUNCTION keyword, overview 267 NODEI FILEI keyword, Network 351
Index N
NODEMERGE phase description 380 variable referencing 382 NODEO FILEO keyword, Network 355 FILEO keyword, SYNCHIMP utility 867 NODEPOST PLOT keyword, Network 364 NODEREAD Public Transport phase 623 nodes alighting, portion allocated to 651 approaches at 269 Cube Cluster processing, starting 896 destination, Cube Avenue 917 destination, nontransit legs 713 drawing, Network 363 fare zones 825 highest number in network 362 intersection modeling invoked at 188 maximum in RAM, Cube Avenue 921 nontransit leg, intermediate 736 nontransit legs, start and finish 734 origin, Cube Avenue 917 origin, nontransit legs 710 output, including in Public Transport 694 Public Transport report, including in 752 stop, including in report 748 stop, transit line flag 721 stop-to-stop movements collected for 703 transit line 724728 travel demand on, identifying 607 travel demand on, selecting 611 turning volumes accumulated 247 wait curve associated 651 wait curve associated, transfer points 661 wait-time weighting factor for 658 NODES. FACTORS IWAITCURVE subkeyword, Public Transport 651 FACTORS WAITFACTOR subkeyword, Public Transport 658 FACTORS XWAITCURVE subkeyword, Public Transport 661 FILEO STOP2STOPO subkeyword, Public Transport 703 Highway variable 135 LINE keyword, Public Transport 724 PARAMETERS keyword, Network 362
nontransit legs direction 709 excessive, avoiding 845 generating 706 generating, theory 842 link cost 709 links included 710 listing 710 maximum cost per mode 711 maximum network links 709 maximum per mode 711 minimum cost per mode 711 mode assigned 711 network links excluded 709 nodes from 710 nontransit legs file naming 693 source 694 nontransit-only routes 845 NOROUTEERRS PARAMETERS keyword, Public Transport 741 NOROUTEMSGS PARAMETERS keyword, Public Transport 741 NOTMODES FILEI TURNPENI subkeyword, Public Transport 682 NT Public Transport control statement 734 NTBYLINK FILEO LINKO subkeyword, Public Transport 687 NTLEGI FILEI keyword, Public Transport 676 NTLEGMODE GENERATE keyword, Public Transport 711 NTLEGO FILEO keyword, Public Transport 693 NTLEGS FILEO LINKO subkeyword, Public Transport 688 null blocks 22 NUMBER CROWDCRVDEF keyword, Public Transport 642 FARESYSTEM keyword, Public Transport 668 MODE keyword, Public Transport 733 OPERATOR keyword, Public Transport 737 VEHICLETYPE keyword, Public Transport 755 WAITCRVDEF keyword, Public Transport 757 NUMBEROFLANES JUNCTION keyword, all-way stop 302 JUNCTION keyword, overview 267
Index O
numbers print format 63 print format, working matrix 69 NUMLINKS, Highway variable 135 NumReadyNodes function 897 NUMRECS SORT keyword, general 72 O OCOMPCOST CHOICE keyword, cost-based model 446 OCOMPUTIL CHOICE keyword, utility-based model 449 ODEMAND CHOICE keyword, cost-based model 446 CHOICE keyword, utility-based model 449 ODEMANDMW XCHOICE keyword, cost-based model 453 XCHOICE keyword, utility-based model 456 OFF LINE NODES subkeyword, Public Transport OMITFARES FILEI FACTORI subkeyword, Public Transport 671 ON LINE NODES subkeyword, Public Transport ONELINKREC FILEO LINKO subkeyword, Public Transport ONEWAY GENERATE keyword, Public Transport 711 LINE keyword, Public Transport 728 NT keyword, Public Transport 736 ONLINE CONSOLE subkeyword 44 ONOFFS FILEO LINKO subkeyword, Public Transport ONRUNERRORGOTO Pilot control statement 95 OPERATOR FACTORS FARESYSTEM subkeyword, Public Transit 649 LINE keyword, Public Transport 728 Public Transport control statement 737 operators defining 737 demand using, selecting 612 fare model 649 transit line 728
ORIGIN FILEO PACKETLOG subkeyword, Cube Avenue 917 output files See also FILEO naming 45 Pilot program 76 Public Transport program 837 waiting for subprocess, Cube Cluster 891 outputs loading process, Public Transport 606 network development, Public Transport 589 route enumeration, Public Transport 591 route evaluation, Public Transport 592 skimming, Public Transport 594 P P COMP keyword, Generation 568 REPORT keyword, Generation 573 SETPA keyword, Distribution 558 SETPA keyword, Fratar 126 P2A BALANCE keyword, Generation 567 PACKETLOG FILEO keyword, Cube Avenue 916 PAGEHEIGHT GLOBAL keyword, general 46 PAGEWIDTH GLOBAL keyword, general 46 PAO FILEO keyword, Generation 569 PARAMETERS Cube Avenue control statement 920 Distribution control statement 554 Fratar control statement 121 Generation control statement 571 Highway control statement 215 Matrix control statement 518 Network control statement 361 Pilot control statement 98 Public Transport control statement 737 RUN keyword, Pilot 103 SYNCHIMP control statement 867 TPP2UB control statement 865 UB2TPP control statement 863 PARKINGMANEUVERS JUNCTION keyword, geometric signals 288 JUNCTION keyword, overview 267
727
727 688
689
Index P
passenger loadings analyses 617 assigning 605 example report 857 report example 768 passengers assigning to trips 605 denied boarding 773 distance, example report 767 distance, generating report 746 flow-metered volume 735 hours, example report 767 hours, generating report of 746 statistics, skimming 814 utility, improving with new service 801 volume, specifying for nontransit legs 736 PASSWORD SENDMAIL keyword, Pilot 107 PATH FILET keyword, Highway 206 FILET keyword, Matrix 509 PATHLOAD keyword, Highway 231 path file creating from Saturn output 869 PATHLOAD Cube Avenue control statement 922 Highway control statement 223 using with DYNAMICLOAD 913 PATHO FILEO keyword, Highway 200 impact on Cube Avenue 923 impact on Cube Cluster 886 PATHLOAD keyword, Highway 231 PATHOGROUP PATHLOAD PATHO subkeyword, Highway 232 PATHTRACE Highway function 137 PATTERN FILEI MATI subkeyword, Matrix 480 FILEO MATO subkeyword, Matrix 504 PC REPORT keyword, Generation 573 PCOMP REPORT keyword, Fratar 123 PDIFF convergence testing calculation 167 Highway variable 137 PARAMETERS keyword, Highway 219 using in BALANCE variable 168
PDIFFAVE function for BALANCE 171 Highway function 140 PDIFFCHANGE function for BALANCE 169 Highway function 138 PDIFFCHANGEAVE function for BALANCE 171 Highway function 140 PDIFFCHANGEMAX function for BALANCE 171 Highway function 140 PDIFFCHANGEMIN function for BALANCE 171 Highway function 140 PDIFFCUTOFF Highway variable 138 using in BALANCE variable 168 PDIFFMAX function for BALANCE 171 Highway function 140 PDIFFMIN function for BALANCE 171 Highway function 140 PDIFFVALUE PARAMETERS keyword, Highway 219 PEDESTRIANFLOW JUNCTION keyword, geometric signals 288 JUNCTION keyword, two-way stop 298 PEDESTRIANPHASE JUNCTION keyword, geometric signals 288 PEDESTRIANSPEED JUNCTION keyword, two-way stop 298 penalty boarding, perceived, skim function 600 boarding, Public Transport 646 transfer, actual, skim function 600 transfer, perceived, skim function 600 PENI PATHLOAD keywords, Highway 232 REPORT keyword, Highway 241 PENIFACTOR PATHLOAD keyword, Highway 232 PERCENT select-link expression keyword, Public Transport 616 PERIOD CROWDMODEL keyword, Public Transport 643 FILEI JUNCTIONI subkeyword, Highway 188
Index P
PGF SETPA keyword, Fratar 126 PGM RUN keyword, Pilot 104 PHASE JUNCTION keyword, overview 267 JUNCTION keyword, signals 282 PROCESS keyword, Generation 572 PROCESS keyword, Highway 240 PROCESS keyword, Network 374 phases defining in scripts 239 INPUT, Network program 380 LINKMERGE, Network program 381 Network program 379 NODEMERGE, Network program 380 NODEREAD, Public Transport 623 Public Transport program 620 SUMMARY, Network program 381 PHASES. JUNCTION keyword, geometric signals 289 JUNCTION keyword, overview 267 JUNCTION keyword, signals 283 PHASINGI FILEI keyword, SYNCHIMP utility 867 PILOT example, typical application template 110 Pilot program control statements 82 example in loop 110 example with logic 111 introduction 76 process 77 project file 76 tokens in 80 PKTPTHSIZ PARAMETERS keyword, Cube Avenue 921 PLANID PARAMETERS keyword, SYNCHIMP 868 PLATESIZE PLOTTER keyword, Network 370 PLOT Network control statement 363 PLOTTER BANDWIDTH 364 Network control statement 364 plotting networks complex example 389 simple link example 389 theory 384
PORT SENDMAIL keyword, Pilot 107 POST PLOTTER POSTLINKVAR subkeyword, Network 371 POSTLINKVAR PLOTTER keyword, Network 370 POSTNODEVAR PLOTTER keyword, Network 371 POW 33 PREFIX LOG keyword, general 51 PRINT control statement, general 62 Distribution control statement 521 FILEO PAO subkeyword, Generation 571 Fratar control statement 521 Generation control statement 521 Highway control statement 238 Matrix control statement 521 Network control statement 373 Pilot control statement 99 PRINT FILE subkeyword, general 63 PRINT PRINTO subkeyword, general 65 Public Transport control statement 746 REPORT MARGINREC subkeyword, Matrix 529 PRINTFILES WAIT4FILES keyword, Cube Cluster 893 printing defining character formats 67 defining numeric formats 66 example listing links in 387 PRINTO FILEO keyword, Highway 201 FILEO keyword, Matrix 504 FILEO keyword, Network 355 FILEO keyword, Pilot 90 FILEO keyword, Public Transport 694 PRINT keyword, general 65 PRINTROW control statement, general 69 Distribution control statement 521 Fratar control statement 521 Highway control statement 239 Matrix control statement 521 Public Transport control statement 746
Index Q
priority junctions 318 geometric, example 324 geometric, keywords 320 keywords 319 overview 318 saturation-flow, example 327 saturation-flow, keywords 325 PRNFILE RUN keyword, Pilot 104 PROBABILITY select-link expression keyword, Public Transport 616 PROCESS Generation control statement 571 Highway control statement 239 Network control statement 374 PROCESSID DISTRIBUTEINTRASTEP keyword, Cube Cluster 894 DISTRIBUTEMULTISTEP keyword, Cube Cluster 891 PROCESSLIST DISTRIBUTEINTRASTEP keyword, Cube Cluster 894 PROCESSNUM DISTRIBUTEMULTISTEP keyword, Cube Cluster 891 program features 4 PROJECTLINK, Highway variable 135 PROMPT Pilot control statement 100 public transport network developing, example 849 loading trip matrix, example 856 nontransit legs 706 Public Transport program data preparation 582 demand loading 583 input files 837 linking to Highway program 838 modeling 582 output files 837 overview 580 phases 620 processes 586 reports, details 760 reports, overview 584 routes, finding 582 skimming 583 system data input file 679 terminology 584
PURPOSE GRAVITY keyword, Distribution 553 PARAMETERS keyword, TPP2UB 865 Q QUESTION PROMPT keyword, Pilot 100 R R LOOKUP keyword, general 54 print format code, numeric items 67 print format code, string items 68 RAAD convergence testing calculation 167 Highway variable 137 PARAMETERS keyword, Highway 220 using in BALANCE variable 168 RAADAVE function for BALANCE 171 Highway function 139 RAADCHANGE function for BALANCE 169 Highway function 138 RAADCHANGEAVE function for BALANCE 171 Highway function 140 RAADCHANGEMAX function for BALANCE 171 Highway function 140 RAADCHANGEMIN function for BALANCE 171 Highway function 139 RAADCUTOFF Highway variable 138 using in BALANCE variable 168 RAADMAX function for BALANCE 171 Highway function 139 RAADMIN function for BALANCE 171 Highway function 139 RAND 33 RANDOM 33 RANDOMNESS JUNCTION keyword, common description 275 JUNCTION keyword, overview 267 RANDSEED 33
Index R
RANGE CROSSTAB COL subkeyword, Network 342 CROSSTAB ROW subkeyword, Network 343 FREQUENCY keyword, Matrix 512 REPORT VDTSPD keyword, Highway 242 READ control statement, general 71 READNTLEGI GENERATE keyword, Public Transport 712 REBESTPATHCOST FACTORS keyword, Public Transport 654 RECI FILEI keyword, Matrix 482 impact on Cube Cluster 886 RECI processing Matrix program 402 RECI.NUMFIELD Matrix built-in variable 394 RECI.NUMRECORDS Matrix built-in variable 394 RECI.RECERR Matrix built-in variable 394 RECI.RECNO Matrix built-in variable 394 RECO FILEO keyword, Matrix 504 WRITE keyword, Matrix 533 RECO processing Matrix program 402 RECORD COMPARE keyword, Network 339 MERGE keyword, Network 359 RECOSTMAX FACTORS keyword, Public Transport 654 REDIRECTIN RUN keyword, Pilot 104 REDIRECTOUT RUN keyword, Pilot 104 RELATIVEGAP PARAMETERS keyword, Highway 220 REMOVEFROMGROUP SETGROUP keyword, Highway 244 RENAME FILEI LINKI subkeyword, Network 348 RENUMBER Fratar control statement 522, 522 impact on Cube Cluster 886 REPL_DUP PARAMETERS keyword, Network 362 REPLACESTR 35
REPLACESTRIC 35 REPORT Distribution control statement 555 FILEO RECO subkeyword, Matrix 506 Fratar control statement 123 FREQUENCY keyword, Matrix 512 Generation control statement 573 Highway control statement 240 Matrix control statement 527 Network control statement 376 Pilot control statement 102 Public Transport control statement 746 REPORTI FILEI ROUTEI subkeyword, Public Transport 677 FILEO ROUTEO subkeyword, Public Transport 696 produced report, example 763 REPORTJ FILEI ROUTEI subkeyword, Public Transport 677 FILEO ROUTEO subkeyword, Public Transport 696 REPORTO FILEO keyword, Public Transport 694 reports enumerated routes 761 evaluated routes 762 fare matrices 766 public transport network 749 Public Transport, overview 760 transfers between modes 769 transfers between operators 770 transit line summary 767 transit-line loadings 768 REREPORT Public Transport control statement 749 RESULT LOOKUP NAME subkeyword, general 53 RESUME CLEARERROR keyword 84 REV FILEI LINKI subkeyword, Network 349 REVERSESTR 35 REWAITMAX FACTORS keyword, Public Transport 655 REWAITMIN FACTORS keyword, Public Transport 655 REWIND PRINT FILE subkeyword, general 63 PRINT PRINTO subkeyword, general 65
Index R
RGAP convergence testing calculation 167 Highway variable 137 using in BALANCE variable 168 RGAPAVE function for BALANCE 170 Highway function 139 RGAPCHANGE function for BALANCE 169 Highway function 138 RGAPCHANGEAVE function for BALANCE 170 Highway function 139 RGAPCHANGEMAX function for BALANCE 170 Highway function 139 RGAPCHANGEMIN function for BALANCE 170 Highway function 139 RGAPCUTOFF Highway variable 137 using in BALANCE variable 168 RGAPMAX function for BALANCE 170 Highway function 139 RGAPMIN function for BALANCE 170 Highway function 139 RIGHTSTR 35 RMSE convergence testing calculation 167 Highway variable 137 PARAMETERS keyword, Highway 220 using in BALANCE variable 168 RMSEAVE function for BALANCE 172 Highway function 140 RMSECHANGE function for BALANCE 169 Highway function 138 RMSECHANGEAVE function for BALANCE 172 Highway function 140 RMSECHANGEMAX function for BALANCE 172 Highway function 140 RMSECHANGEMIN function for BALANCE 172 Highway function 140
RMSECUTOFF Highway variable 138 using in BALANCE variable 168 RMSEMAX function for BALANCE 172 Highway function 140 RMSEMIN function for BALANCE 172 Highway function 140 ROUND, numeric function 33 roundabouts empirical, keywords 305 example, empirical 314 example, gap-acceptance 317 keywords, gap-acceptance 316 overview 303 route enumeration components generated 652 determining routes, theory 797 maximum transfers in route 648 minimum-cost routes, finding 794 modes, not using 648 must-use mode, theory 798 overview 582 process overview, Public Transport 590 required transit modes 654 theory 793 transit connectors, finding 795 route evaluation fares, including in cost 739 initial wait time 651 overview 582 process overview, Public Transport 591 required transit modes 654 theory 799 route file format 743 ROUTEI FILEI keyword, Public Transport 676 ROUTEO FILEO subkeyword, Public Transport 695 ROW CROSSTAB keyword, Network 342 ROWADD COMP function, Matrix 466 Highway function 136 Matrix built-in function 395 matrix function, Highway 181
Index S
ROWAVE COMP function, Matrix 466, 466 Highway function 136 Matrix built-in function 395 matrix function, Highway 182 ROWCNT COMP function, Matrix 466, 466 Highway function 136 Matrix built-in function 395 matrix function, Highway 182 ROWDIV COMP function, Matrix 466 Highway function 137 Matrix built-in function 395 matrix function, Highway 182 ROWFAC COMP function, Matrix 466 Highway function 136 Matrix built-in function 395 matrix function, Highway 182 ROWFIX COMP function, Matrix 466 Highway function 136 Matrix built-in function 395 matrix function, Highway 182 ROWMAX COMP function, Matrix 467 Highway function 136 Matrix built-in function 395 matrix function, Highway 183 ROWMIN COMP function, Matrix 467 Highway function 136 Matrix built-in function 395 matrix function, Highway 183 ROWMPY COMP function, Matrix 467 Highway function 136 Matrix built-in function 395 matrix function, Highway 183 ROWREAD COMP function, Matrix 468 ROWSUM COMP function, Matrix 468 Highway function 136 Matrix built-in function 395 matrix function, Highway 183 RT LINE NODES subkeyword, Public Transport 727
RUN Pilot control statement 102 RUNFACTOR FACTORS keyword, Public Transport 656 RUNTIME LINE NODES subkeyword, Public Transport 729 S S print format code, numeric items 67 SAME FARESYSTEM STRUCTURE subkeyword, Public Transport 669 SATFLOWPERLANE JUNCTION keyword, overview 267 JUNCTION keyword, saturation-flow prioirty junctions 327 JUNCTION keyword, signals 283 saturation flow 291, 327 Saturn, converting output to Cube Voyager format 869 SAVE FREQUENCY keyword, Matrix 512 SAVEPRN DISTRIBUTEINTRASTEP keyword, Cube Cluster 894 SCREENLINE FILEO ESTMICPO subkeyword, Highway 198 screenline file creating 836 SCREENLINEI FILEI keyword, Public Transport 678 SCREENLINEO FILEO keyword, Public Transport 698 SCREENVAR FILEO SCREENLINEO subkeyword, Public Transport 699 SEATCAP LINE keyword, Public Transport 729 VEHICLETYPE keyword, Public Transport 756 SEGMENTS PARAMETERS keyword, Cube Avenue 922 SELECT FILEI LINKI subkeyword, Network 349 FILEI ZDATI subkeyword, Highway 195 FILEI ZDATI subkeyword, Matrix 488 select link process, Public Transport program 607
Index S
SELECTBYMAT FILEI ROUTEI subkeyword, Public Transport 678 FILEO ROUTEO subkeyword, Public Transport 696 SELECTGROUP FILEO PACKETLOG subkeyword, Cube Avenue 917 PATHLOAD MW subkeyword, Highway 228 SELECTIJ Public Transport phase 628 SELECTLINK FILEO PACKETLOG subkeyword, Cube Avenue 917 PATHLOAD MW subkeyword, Highway 229 select-link function applying criteria simultaneously 614 combining criteria 612 demand criteria 616 description 607 links 609 loading partial demand 617 mode 612 movement types 615 nodes 611 not conditions 614 transit line 610 transit operator 612 SELECTLINKGROUP PATHLOAD MW subkeyword, Highway 230 SENDMAIL Pilot control statement 106 service-frequency mode example 809 SERVICEMODEL FACTORS keyword, Public Transport 656 SET Distribution control statement 531 FILEI JUNCTIONI subkeyword, Highway 189 Fratar control statement 531 Generation control statement 531 Highway control statement 243 Matrix control statement 531 SETGROUP Highway control statement 244 SETPA Distribution control statement 556 Fratar control statement 124 SETS FILEI TURNPENI subkeyword, Public Transport 683 SETUP phase Cube Avenue 902 Highway program 150
SETUPPER LOOKUP keyword, general 54 signals fixed-time, example 291 geometric, example 289 keywords, generic 280 keywords, geometric 285 overview 279 saturation flow, example 291 SIN 34 SINGLELANE JUNCTION keyword, overview 267 JUNCTION keyword, priority junctions 319 JUNCTION keyword, signals 284 JUNCTION keyword, two-way stop 298 SIZE LOOKUP keyword, general 54 skim functions best actual trip time 601 boardings 602 composite cost 602 distance 602 excess demand 603 fare 600 overview 594 penalties 599 summary 604 travel time 598 value of choice 603 wait time 596 SKIMIJ Public Transport phase 629 skimming example 854 overview 583 process, Public Transport 593 quick reference 604 theory 812 SKIP0 FILEO LINKO subkeyword, Public Transport 690 REPORT LINES subkeyword, Public Transport 747 REPORT LINEVOLS subkeyword, Public Transport 748 SKIPBADLINES FILEI LINEI subkeyword, Public Transport 673 PARAMETERS keyword, Public Transport 741 SLACK GENERATE keyword, Public Transport 712 SMTPSERVER SENDMAIL keyword, Pilot 107
Index S
SORT control statement, general 72 Cube Cluster impact 886 Distribution control statement 532 FILEI DBI subkeyword, Matrix 478 FILEI RECI subkeyword, Matrix 485 Fratar control statement 532 Generation control statement 532 Highway control statement 245 Matrix control statement 532 Network control statement 377 REPORT LINES subkeyword, Public Transport 747 SPDCAP Highway control statement 245 Network control statement 378 SPEED Highway variable 135 LINE NODES subkeyword, Public Transport 727 NT keyword, Public Transport 736 REPORT keyword, Highway 241 REPORT keyword, Network 376 setting, example in Cube Avenue 934 SPDCAP keyword, Highway 245 SPDCAP keyword, Network 378 value computed, Highway LINKREAD phase 151 variable, Cube Avenue 904 SPEEDFOR COMP function, Network 338 Highway function 137 Network function 333 SPLIT CHOICE keyword, cost-based model 447 CHOICE keyword, utility-based model 450 XCHOICE keyword, cost-based model 454 XCHOICE keyword, utility-based model 457 SPLITCOMP XCHOICE SPLIT subkeyword, cost-based model 454 SPLITINTO CHOICE DESTSPLIT subkeyword, cost-based model 446 CHOICE SPLIT subkeyword, cost-based model 447 XCHOICE DESTSPLIT subkeyword, cost-based model 453 XCHOICE SPLIT subkeyword, cost-based model 454 SPREAD definition 657 SPREADCONST FACTORS keyword, Public Transport 656
SPREADFACT FACTORS keyword, Public Transport 656 SPREADFUNC FACTORS keyword, Public Transport 657 SQRT 33 STACK REPORT keyword, Pilot 102 standing 723 START FILEI LINKI subkeyword, Network 349 starting Cube Voyager 9 STARTMW CHOICE keyword, cost-based model 447 CHOICE keyword, utility-based model 451 XCHOICE keyword, cost-based model 455 XCHOICE keyword, utility-based model 458 statement tokens 21 STOP FILEI LINKI subkeyword, Network 349 STOP2STOPO FILEO keyword, Public Transport 700 STOPGROUP FILEO STOP2STOPO subkeyword, Public Transport 703 STOPNODES REREPORT keyword, Public Transport 752 stops. See two-way stops, all-way stops STOPSONLY REPORT LINEVOLS subkeyword, Public Transport 748 STORAGE script variable, Cube Avenue 929 setting, example in Cube Avenue 934 variable, Cube Avenue 905 STORAGESPACE JUNCTION keyword, overview 267 JUNCTION keyword, two-way stop 299 STR 35 strings maximum length 219 print format 62 STRLEN 35 STRLOWER 35 STRPOS 35 STRPOSEX 35 STRUCTURE FARESYSTEM keyword, Public Transport 669 STRUPPER 35 SUBAREAMAT PATHLOAD keyword, Highway 233
Index T
SUBAREAMATO FILEO keyword, Highway 201 impact on Cube Avenue 915 impact on Cube Cluster 885 SUBAREANETI FILEI keyword, Highway 189 SUBJECT SENDMAIL keyword, Pilot 108 subkeywords 26 SUBSTR 35 SUM FILEI ZDATI subkeyword, Highway 195 FILEI ZDATI subkeyword, Matrix 488 MERGE keyword, Network 359 SUMMARY phase Network program 381 variable referencing 382 SYMBOL PLOTTER LEGEND subkeyword, Network 368 SYNCHIMP 866 SYNCHIMP utility 866 SYSTEMI FILEI keyword, Public Transport 679 T T print format code, numeric items 66 print format code, string items 68 TURNS keyword, Highway 247 T0 Highway variable 135 setting, example in Cube Avenue 934 value computed, Highway LINKREAD phase 152 variable, Cube Avenue 905 T1 Highway variable 135 value set, Highway LINKREAD phase 152 variable, Cube Avenue 905 TAN 34 TAPER PLOTTER BANDWIDTH subkeyword 365 TCCOEFF PARAMETERS keyword, Highway 221 TCEXP PARAMETERS keyword, Highway 222 terminology, Public Transport program 584 TF LINE NODES subkeyword, Public Transport 727
theory Cube Avenue 924 Network program 379 THISPROCESS Cube Cluster impact 887 Matrix built-in variable 395 THRUNODE PATHLOAD keyword, Highway 234 TIME Highway array 136 LINE NODES subkeyword, Public Transport 728 value set, Highway LINKREAD phase 153 TIMEA skim function, Public Transport 598 skim function, summary 605 TIMEFAC LINE keyword, Public Transport 729 TIMEP skim function, Public Transport 599 skim function, summary 605 TIMINGI FILEI keyword, SYNCHIMP utility 867 TITLE COMPARE keyword, Network 339 FREQUENCY keyword, Matrix 512 PRINTROW keyword, general 70 TO FACTORS XFERCONST subkeyword, Public Transport 658 FACTORS XFERFACTOR subkeyword, Public Transport 659 FACTORS XFERPEN subkeyword, Public Transport 660 SENDMAIL keyword, Pilot 108 TOD PARAMETERS keyword, TPP2UB 865 TOLERANCE LOOKUP keyword, general 54 TOLLFACTOR FILEI TOLLMATI subkeyword, Highway 191 PATHLOAD keyword, Highway 233 TOLLMATI 146 FILEI keyword, Highway 190 PATHLOAD keyword, Highway 234 TOLLROUND FILEI TOLLMATI subkeyword, Highway 191 TOLLS FILEI TOLLMATI subkeyword, Highway 191 TONODE GENERATE keyword, Public Transport 713 TPP2UB 864
Index T
TPP2UB utility 864 TRACE PATHLOAD keyword, Highway 234 REPORT keyword, Generation 573 REPORT keyword, Highway 241 REPORT keyword, Matrix 530 REPORT keyword, Pilot 102 TRACEI FILEI ROUTEI subkeyword, Public Transport 678 FILEO ROUTEO subkeyword, Public Transport 697 report produced, example 764 TRACEJ FILEI ROUTEI subkeyword, Public Transport 678 FILEO ROUTEO subkeyword, Public Transport 697 TRAM PARAMETERS keyword, Matrix 520 transfers actual penalty, skim function 600 actual wait time, skim function 597 banning between modes 660 between modes, report 769 between operators, report 770 maximum in route 648 method 738 penalty between modes 660 penalty weighting factor 659 penalty, constant to add 658 perceived penalty, skim function 600 perceived wait time, skim function 598 report by line 751 transit lines attribute report 750 demand using, selecting 610 errors in data, ignoring 741 excessive travel time, message 738 links file, including data in 687 loadings, report 768 passenger boardings, generating report 748 report summarizing 767 reports, including in 750 summary report, generating 747 travel demand on, identifying 607 travel time, computation of 730 travel time, extending control value 739 travel time, link 742 transposed matrix 395 TRANTIME PARAMETERS keyword, Public Transport 742
travel time actual, skim function 598 crowded link, perceived, skim function 599 perceived, skim function 599 transit line 742 transit line, exceeding control value, report 738 transit line, extending control values 739 TRIM 35 trip purposes 547 trip time best, skim function 601 trips. number computed 743 unsuccessful proportion, skim function 603 unsuccessful, skim function 603 TRIPSIJ PARAMETERS keyword, Public Transport 743 TRIPSXY FILEI LINKI subkeyword, Network 349 TRNCOEF PARAMETERS keyword, TPP2UB 865 TRNLEGS1 REREPORT keyword, Public Transport 752 TRNLEGS2 REREPORT keyword, Public Transport 753 TRNLEGS3 REREPORT keyword, Public Transport 753 TRNLEGS4 REREPORT keyword, Public Transport 754 turn penalty files input, name of 680 turn times converting to costs 222 TURNCHANNELIZED JUNCTION keyword, overview 267 JUNCTION keyword, two-way stop 300 TURNCOSTFAC PARAMETERS keyword, Highway 222 TURNGAPWT PARAMETERS keyword, Highway 222 TURNPENI FILEI keyword, Highway 191 FILEI keyword, Public Transport 680 TURNPENO FILEO keyword, Highway 202 TURNS Highway control statement 246 TURNVOLO FILEO keyword, Highway 202 two-way stop-controlled intersections 294
Index U
two-way stops example 301 keywords 295 overview 294 TXT FILEO TURNVOLO file format 204 TYP FILEI LINKI VAR subkeyword, Network 350 TYPE FILEO MATO subkeyword, Public Transport 692 JUNCTION keyword, common description 276 JUNCTION keyword, overview 267 select-link expression keyword, Public Transport 615 U UB2TPP utility 862 UNCONNECTED REPORT keyword, Network 376 UNITEXTENSION JUNCTION keyword, geometric signals 289 UNITFARE FARESYSTEM keyword, Public Transport 670 UNITS junction file control statement 267 PARAMETERS keyword, SYNCHIMP 868 UPDATEVARS WAIT4FILES keyword, Cube Cluster 893 URL DOWNLOAD keyword, Pilot 89 user class example 857 list of 743 overview 744 passenger loading report by 749 trips loaded 743 user stacks, Highway program 250 USERCLASS REREPORT keyword, Public Transport 754 USERCLASSES PARAMETERS keyword, Public Transport 743 REPORT LINEVOLS subkeyword, Public Transport 749 USERNAME SENDMAIL keyword, Pilot 108 UTILITIES CHOICE keyword, utility-based model 451 UTILITIESMW XCHOICE keyword, utility-based model 458
V V, Highway variable 135 V4ROUTEFORMAT PARAMETERS keyword, Public Transport 743 VAL 35 SET keyword, Highway 243 SET keyword, Matrix 531 ValOfChoice skim function, Public Transport 603 skim function, summary 605 value of choice skim function 603 VALUEMW FREQUENCY keyword, Matrix 512 VALUEOFTIME FACTORS keyword, Public Transport 658 VAR ARRAY keyword, Highway 176 ARRAY keyword, Matrix 438 ARRAY keyword, Network 336 COMP keyword, Highway 179 COMP keyword, Matrix 462 COMP keyword, Public Transport 638 CROSSTAB keyword, Network 343 FILEI LINKI subkeyword, Network 350 FILEO ESTMICPO subkeyword, Highway 198 LOG keyword, general 51 VARFORM FILEO LINKO subkeyword, Network 353 VARI FILEI keyword, Pilot 90 FILEI keyword, TPP2UB 864 variables COMP exrpession, Matrix 463 convergence, Highway program 137 DATAPREP phase, Public Transport 626 Highway 135 LINKREAD phase, Public Transport 625 MATI phase, Public Transport 628 MATO phase, Public Transport 631 matrix 179 Matrix program, built-in 394 naming convention 39 Network program, referencing in 381 NODEREAD phase, Public Transport 624 output, Network program 383 SELECTIJ phase, Public Transport 629 VARO FILEO keyword, UB2TPP 863
Index W
VARS FILEO TURNVOLO keyword, Highway 204 REPORT keyword, Pilot 102 SET keyword, Highway 243 SET keyword, Matrix 531 VDTSPD impact on Cube Cluster 886 REPORT keyword, Highway 241 VEHICLETYPE LINE keyword, Public Transport 729 Public Transport control statement 755 VEHPERDIST PARAMETERS keyword, Cube Avenue 922 VISIBILITY JUNCTION keyword, geometric priority junctions 323 JUNCTION keyword, overview 267 VOL FILEO LINEO subkeyword, Public Transport 685 FILEO NTLEGO subkeyword, Public Transport 694 Highway array 136 LINE NODES subkeyword, Public Transport 728 NT keyword, Public Transport 736 PATHLOAD keyword, Higwhay 235 REPORT VDTSPD keyword, Highway 243 VOLDATE PARAMETERS keyword, SYNCHIMP 868 VOLFIELDS FILEO LINKO subkeyword, Public Transport 690 VOLT NT keyword, Public Transport 736 VOLTIME PARAMETERS keyword, SYNCHIMP 868 VOLUMEI FILEI keyword, SYNCHIMP utility 867 W WAIT PROMPT keyword, Pilot 101 wait curves defining 756 description 758 wait time crowding, actual, skim function 597 crowding, perceived, skim function 597 initial, actual, skim function 597 initial, perceived, skim function 598 theory 773 transfer, actual, skim function 597 transfer, perceived, skim function 598 wait curve 757
WAIT4FILES Cube Cluster control statement 891 WAITCRVDEF Public Transport control statement 756 WAITFACTOR FACTORS keyword, Public Transport 658 walk choice portion of trips allocated to 652 walk time, theory 772 WEIGHTS. PARAMETERS COMBINE keyword, Highway 218 WIDTH JUNCTION keyword, geometric priority junctions 324 JUNCTION keyword, overview 267 Windows starting Cube Voyager from 10 work matrices maximum index, Highway 219 maximum index, Matrix 519 maximum index, Public Transport 740 WRITE Distribution control statement 532 Fratar control statement 532 Generation control statement 532 Matrix control statement 532 X X Network variable 332 XCHOICE CHOICE, differences with 458 Matrix control statement 451 XFERCONST FACTORS keyword, Public Transport 658 XFERFACTOR FACTORS keyword, Public Transport 659 XFERLEGS REREPORT keyword, Public Transport 754 XFERMETHOD GENERATE keyword, Public Transport 713 XFERPEN FACTORS keyword, Public Transport 660 XFERPENA skim function, Public Transport 600 skim function, summary 605 XFERPENP skim function, Public Transport 600 skim function, summary 605
Index Y
XN FILEO NTLEGO subkeyword, Public Transport 694 NT keyword, Public Transport 736 XWAITA skim function, Public Transport 597 skim function, summary 605 XWAITCURVE FACTORS keyword, Public Transport 661 XWAITP skim function, Public Transport 598 skim function, summary 605 XYSPD LINE NODES subkeyword, Public Transport 728 XYSPEED LINE keyword, Public Transport 729 Y Y Network variable 332 yield-controlled intersections geometric, example 324 geometric, keywords 320 keywords 319 overview 318 saturation flow, keywords 325 Z Z FILEI ZDATI subkeyword, Highway 195 FILEI ZDATI subkeyword, Matrix 488 FILEO RECO subkeyword, Matrix 506 Matrix built-in variable 395
ZDAT Report keyword, Highway 243 REPORT keyword, Matrix 530 ZDATI FILEI keyword, Highway 193 FILEI keyword, Matrix 485 zonal timing messages Highway 222 Matrix 520 Public Transport 744 zone lacking valid routes 741 lists, working with 398 substituting 400 ZONEMSG PARAMETERS keyword, Highway 222 PARAMETERS keyword, Matrix 520 PARAMETERS keyword, Public Transport 744 ZONEO RENUMBER keyword, Matrix 525 ZONES Highway variable 135 Matrix built-in variable 395 PARAMETERS keyword, Distribution 555 PARAMETERS keyword, Fratar 123 PARAMETERS keyword, Highway 223 PARAMETERS keyword, Matrix 520 PARAMETERS keyword, Network 362 RENUMBER keyword, Matrix 525
Citilabs, Inc. 1040 Marina Village Parkway Alameda, CA 94501 USA World Wide Web www.citilabs.com

RG CubeVoyager

Uploaded by

Copyright:

Available Formats

RG CubeVoyager

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

RG CubeVoyager

Uploaded by

Copyright:

Available Formats

What is the document about?

What is the document about?

What are some of the main features described in the document?

What are some of the main features described in the document?

Cube Voyager Reference Guide Cube Voyager Reference Guide

Document Revision 50-006-1 December 12, 2008

Cube Voyager Reference Guide

About This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Cube Voyager Reference Guide iii

iv Cube Voyager Reference Guide

Highway Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Cube Voyager Reference Guide v

Intersection Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

vi Cube Voyager Reference Guide

Network Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Cube Voyager Reference Guide vii

viii Cube Voyager Reference Guide

Matrix Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391

Cube Voyager Reference Guide ix

Distribution Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541

Generation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563

x Cube Voyager Reference Guide

Public Transport Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

Cube Voyager Reference Guide xi

xii Cube Voyager Reference Guide

Cube Cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871

Cube Voyager Reference Guide xiii

Cube Avenue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 899

xiv Cube Voyager Reference Guide

Cube Voyager Reference Guide

About This Document

Cube Voyager Reference Guide xv

About This Document

xvi Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 1

Introduction Design concepts

2 Cube Voyager Reference Guide

Introduction Design concepts

Cube Voyager Reference Guide 3

Introduction Program features

4 Cube Voyager Reference Guide

Introduction Program features

Capability to link with user-generated native code

Cube Voyager Reference Guide 5

Introduction Minimum system requirements

Minimum system requirements

6 Cube Voyager Reference Guide

Cube Voyager Reference Guide

Cube Voyager Reference Guide 7

Getting Started Installation

8 Cube Voyager Reference Guide

Getting Started Starting Cube Voyager

Starting Cube Voyager

Starting Cube Voyager from Cube Base

Cube Voyager Reference Guide 9

Getting Started Starting Cube Voyager

Starting Cube Voyager from Windows

10 Cube Voyager Reference Guide